The following section documents a set of semantics for measurement
agents to use in formatting the correlator and agent identifiers.
The correlator passed on
Buffer word/byte/bit Format byte 0 byte 1 byte2 byte 3 |----------|----------|-----------|-----------| 0 7 8 15 16 22 23 31 msb lsb
|2 bytes||Length of the Correlator (unsigned16)
If this value is zero, it means that the measurement agent is not returning a correlator, and therefore there is no reason to pass this correlator on to other parts of the application (or servers that it calls).
A zero length provides another safeguard for agents. If an application
passes a null correlator anyway, when any agent receives this
correlator as the parent correlator for another transaction, the agent
can see that the data in the correlator is invalid and ignore it,
regardless of whether the
bit (Flags First Byte a) is set in the
|1 byte||Correlator format (unsigned8)=1
Only one format is defined at this point, but others could be added in the future.
First Byte (bit8)
ab000000, where a and b are bit flags.
a=1 if a trace of this transaction and any nested component transactions is requested by the agent.
b=1 if a trace of this transaction and any nested component
transactions is requested by the application. The application requests
this by setting the "d" bit (in abcdefgh notation) in the first flag
byte in the buffer passed on
The trace this correlator flag is a way to cause agents to trace and/or monitor a transaction and all component transactions associated with the transaction without having to trace or monitor all transactions on a system, or without requiring a complicated infrastructure to control tracing and monitoring. (Note that this does not preclude other ways to control agents, nor is this intended to be a final and comprehensive solution. It is intended that this will be used in addition to other approaches).
When an agent builds a correlator, it is free to turn on these flags. The agent might do this if an application has been experiencing unsatisfactory response times. Any agents that receive this correlator as the parent correlator for a component transaction will also see the flag, and they in turn could turn on the flag in any correlators they generate. This process could repeat, resulting in the passing of the trace flag through all the transactions of interest. All the agents might be configured to trace only the few transactions with this flag on, and this would both capture the information needed to diagnose the transaction problem, and avoid overloading the agents and their systems with attempts to trace all transactions.
|The reason there are separate flags for traces requested by an agent and an application is to provide additional flexibility in how policies for monitoring and tracing are implemented. It might be common for an installation to trace transactions only when requested by agents (based on how the administrator has configured the agents), because then the administrator would control all tracing. On the other hand, permitting the application to highlight when a transaction is special has advantages.|
|2 bytes||Format of the Address field (unsigned16)
The following formats are defined:
This list will be expanded as new requirements arise. The intent is to provide a value for any common addressing format as soon as the need is identified.
32768-65535 = undefined and available for agent implementers to use. There are no semantics associated with the address format. It will be an unusual situation where a new format is needed, but this provides a solution if this is needed. The preferred approach is to get a new format defined that is in the 0-32767 range. There is a risk that two different agent developers will choose the same id, but this risk is small.
|2 bytes||Vendor ID (unsigned16)
The vendor ID is a way to identify who built the agent. Combining this information with the Agent Version field will provide a way for a management application to know what kind of agent generated a correlator. A management application may contain specialized functions or logic that only works with the agents from a particular vendor and/or supporting particular functions or interfaces. By putting these two fields in the correlator, a management application has a way to know whether the agent that generated the correlator has some of these specialized capabilities.
|In order to minimize the possibility of two vendors using the same
vendor ID, the value should be taken from the list of enterprise
identifiers from the Internet Assigned Numbers Authority (IANA). This
list was created for vendors who have SNMP agents. Although the ARM
API specification does not require or endorse SNMP, it's likely that
most or all the organizations that will create an ARM agent will have
at least one enterprise ID assigned. The list of enterprise IDs can be
For organizations that do not have an enterprise identifier assigned by the IANA, the values between 32768-65535 are free for agent developers to use. There are no semantics associated with these ids. It is expected that most or all agent developers will have a formally assigned vendor id, and it will be an unusual situation where another id is needed, but this provides a solution if this is needed. There is a risk that two different agent developers will choose the same id, but this risk is very small.
|2 bytes||Agent Version (unsigned16)
The Agent Version is used to distinguish between different versions of an agent, and will be most useful when the capabilities and/or interfaces of an agent change from one release to another. It will also be useful to distinguish between different agents from the same vendor. Each vendor is responsible for avoiding having multiple agents with different capabilities using the same Agent Version value. Refer to the explanation in the Vendor ID field above to understand how to use this field.
|2 bytes||Agent Instance (unsigned16)
Each agent assigns transaction ids and start handles. Typically there will be one agent on each system, and this one agent is responsible for making sure that there are no duplicate ids or handles. From one system to another, however, duplicate ids and handles will be common, that is, an id/handle combination assigned on system X will also be assigned on system Y.
One of the main purposes of the Address, Vendor ID, and Agent Version fields is to tell a management application how to contact an agent in order to translate the transaction id and start handle into the names of the application, user, and transaction class, and the instance of the transaction. As long as there is only one set of ids and handles stored at that address, all the required information is there. However, if the address is not the address of an individual agent, but rather is the address of a directory that contains information about multiple agents, there is insufficient information, because the id/handle combinations can be duplicated.
The purpose of the Agent Instance field is to provide a way to identify which agent generated a correlator, even if the correlation data from multiple agents is available at the address specified in the Address field.
|4 bytes||Transaction instance (start_handle returned from an arm_start()|
|4 bytes||Transaction class ID (tran_id returned from an arm_getid()|
|2 bytes||Length of the address field (unsigned16)|
This field is the address of the agent. More precisely, it is the address that a management application can contact in order to have the Transaction class ID mapped to the names of an application, user, and transaction class, and to get information about the transaction instance, or aggregated data about the transaction class (or any other data).
The maximum length of this field is determined by an overall limit of 168 bytes for the correlator. In the correlator format described here, the maximum address length is 146 bytes. In actual practice, it is expected to be no more than 20 bytes for most implementations. If new correlator formats are added in the future, the maximum size of this field could change. The maximum correlator size of 168 bytes will not change.
Correlators are passed on
Following are the formats that have been defined so far. The data is stored in network standard byte order, in which integers are sent most significant byte first, unless otherwise indicated. This list is not intended to be exhaustive, and will be extended whenever a new agent implementation requires a new format.
Bytes 0:15 - The X.25 network address (also referred to as an X.121 address).
This is up to 16 ASCII character digits ranging from 0-9. The length is known from the Length of the address field. An agent running over an X.25 link with the IP configured may choose to use this format or the IP format. This format must be used when IP is not configured above an X.25 link.
32768-65535 = undefined and available for agent implementers to use.