Creating your own scripts

The Universal Decode is based on the TCP analysis of the monitored traffic, with the added capability of assigning meaningful names to the observed TCP operations, errors and other events. With the help of Lua scripting and Universal Decode built-in methods, you can extract and report operation names, operation attributes, custom metrics, miscellaneous parameters, errors, user identification, as well as user's software and hardware.

Prerequisites

Writing scripts for Universal Decode requires a set of skills and knowledge.

  • You should know how your application communicates over the network.
  • You should be familiar with basic concepts of NAM deployment and configuration.
  • You should have some experience in scripting, not necessarily in Lua.

Make sure you go through the following preliminary steps before you start working on your Lua scripts for Universal Decode.

Get to know your protocol and application

You need to be familiar with the specification of the protocol you are about to monitor. Universal Decode is just a tool you need to point to particular fields in the data packets, so that they can be extracted, assigned to a proper category of attributes and reported. In particular, you need to be able to identify and find ways to extract attributes carrying the operation names, errors and user identification.

Understand universal decode capabilities

The Universal Decode observes operations which are single TCP request-response pairs and seeks to associate them with meaningful names. The assumption, therefore, is that such meaningful, user-experience related names can be added. For example, this would be the case for both text protocols such as HTTP, FTP, SMTP, and binary protocols such as Corba, Epic, and ISO8583.

However, a web page load, which usually has many hits that load in parallel on many TCP connections and sequentially on the same connection, cannot be treated in this manner. It has to be measured all together and only the combined measurement reflects the page load process. The Universal Decode does not seek to provide such analysis. This type of analysis will continue to be provided by the dedicated decodes such as the HTTP decode.

In short:

  • Universal Decode analyzes separate TCP sessions and will not analyze correlations between the sessions, The TCP request-response type operation must be concluded within a single TCP session.
  • Multiplexation and side switching is supported by Universal Decode, but it is an advanced functionality not covered by this SDK.
  • You need to filter out noise (for example, keep alive packets) or Universal Decode will not be able to construct a meaningful operation.

Get to know Lua

Lua is a powerful, fast and lightweight scripting language. You need to be familiar with its syntax and basic concepts such as functions, declaring and calling variables, etc.

Lua servers as a framework that enables you to use the Universal Decode built in methods to set attributes and metrics to the hits and operations, using the payload as an input for the function. For more information, see Universal Decode methods reference and Universal Decode script structure.

Start scripting

Lua Development Tools

We recommend to use the Lua Development Tools Eclipse plugin that eases the script development by providing the Lua debugger and the script replay. For more information, see Setting up your development workspace.

Unit testing

The quickest and easiest way to verify your scripts is to use the unit tests. This way, you can observe the results of your script instantly, before pushing the sample network capture through the complete NAM monitoring chain. You will add a sample payload to the unit test scripts so that it can be used against the functions of your script. For more information, see Universal Decode unit testing.

Use your scripts in a NAM test environment

When your scripts pass the unit tests and extract the expected attributes, you can test them using a simple NAM deployment on your desktop. For more information, see Setting up your test environment.