Correlator handover

ARM provides an unique and powerful correlation of transactions within distributed systems. The so-called correlator is used to correlate two transactions with a parent-child relationship. A correlator needs to be passed from one system to another for example from a web-client (browser) to a web-server (httpd). Therefore the correlator must be converted into an ASCII representation because these programs communicate with each other using an ASCII protocol named HTTP.

MyARM provides different string representations of a correlator. For compatibility reasons with the first mod_arm4 Apache HTTP Server module, a correlator string without any type information is treated as a hexadecimal encoded string.

To support more encodings MyARM introduces a string prefix followed by a colon to specify the type of encoding. Currently the following encoding types are supported:

b64

the correlator string following the colon is base 64 encoded.

hex

the correlator string following the colon is hexadecimal encoded.

General rule

MyARM suggests to pass a correlator to other components within the application by extending the interfaces whenever its possible. If ARM is used it should be integral part of the application and therefore the ARM correlator is just another parameter which needs to be passed to used components.

Using HTTP

Passing an ARM correlator from a HTTP client to a HTTP server you only need to add the ARM_CORRELATOR header line to the HTTP header. For example:

GET /index.html HTTP/1.0\r\n
ARM_CORRELATOR: 00196400010000020167ab054d2901b71984e04ef3a53e068c\r\n
\r\n

Using an environment variable

If an correlator is passed using an environment variable between two components the environment variable called ARM_CORRELATOR is used. This technique can be used to pass a correlator between:

Two programs

The first program sets the ARM_CORRELATOR environment variable and starts a second program which reads the environment variable to use its contents as its parent correlator. See armtime program.

Program and a library

If a program uses a library which does not support ARM by its interface the environment variable technique can be used to pass a parent correlator to the ARM instrumentation within a library.

For example the following command will print out the MyARM generated correlator as a hexadecimal encoded string:

armtime echo "ARM_CORRELATOR=\$ARM_CORRELATOR"

will produce the following output:

ARM_CORRELATOR=0019640001000002012127097952961ab7519b8fa97486216c