Systems Management: Application Response Measurement (ARM) API
Copyright © 1998 The Open Group

Measurement Agent Information

This appendix contains information provided for measurement agent implementers as opposed to ARM application instrumenters. For instrumenters it is provided as reference only, the correlator is opaque from an application instrumenter's perspective.

Agents and Correlators

The agents provide the correlators, and within the correlator they provide information to uniquely identify agents. To enable an enterprise management solution (correlation application) to analyze the correlators coming from different systems in a heterogeneous environment, agents need to follow some conventions when creating correlators.

The following section documents a set of semantics for measurement agents to use in formatting the correlator and agent identifiers. The correlator passed on arm_start() calls is sent across systems, so it is always in network byte order. Network byte order is a standard described as follows: is always in network byte order. Network byte order is a standard

         Buffer word/byte/bit Format

  byte 0      byte 1      byte2      byte 3
|----------|----------|-----------|-----------|
 0        7 8       15 16       22 23        31
msb                                          lsb

Format of the Correlator

Correlators provided by agents and passed on the arm_start() calls have the following format:

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 parent correlator bit (Flags First Byte a) is set in the arm_start() buffer.
1 byte Correlator format (unsigned8)=1
Only one format is defined at this point, but others could be added in the future.
1 byte Flags
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 arm_start(). The agent will decide whether to set this bit, based on its capabilities and how it is configured.
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:

0 = reserved
1 = IPv4
2 = IPV4+port number
3 = IPv6
4 = IPv6+port number
5 = SNA
6 = X.25
7:32767 = reserved

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.
For example:
The management application wants to contact the agent to know the name of the application, user, and transaction class running this transaction instance. Although the address of the agent is known from the Address field, the protocol that one uses to interface to the agent could be anything. The management application may know how to access several different agents, and could use these values to determine if the correlator came from an agent that it knows how to access. Alternatively, an agent has a special capability. For example, maybe version 3.3 of a vendor's agent analyzes data in a particular way, but previous versions do not. The management application could use this field to see what are the agent's 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 found at:
ftp://ftp.isi.edu/in-notes/iana/assignments/enterprise-numbers
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)
Maximum
146 bytes Address
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 arm_start() calls as part of the buffer pointed to by the data pointer. The maximum size of the buffer is 256 bytes, of which 88 bytes are used for other fields, leaving 168 bytes for the correlator. An application should allocate space for the full 256 bytes when making the arm_start() call, but can then use the Correlator Length field to determine how long the correlator really is, and only forward that much data to other cooperating applications.
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.

0 = reserved

1 = IPv4

Bytes 0:3 4 byte IP address

2 = IPV4+port number

Bytes 0:3 - 4 byte IP address
Bytes 4:5 - 2 byte IP port number

3 = IPv6

Bytes 0:15 - 16 byte IP address

4 = IPv6+port number

Bytes 0:15 - 16 byte IP address
Bytes 16:17 - 2 byte IP port number

5 = SNA

Bytes 0:7 - EBCDIC-encoded network ID
Bytes 8:15 - EBCDIC-encoded network accessible unit (control point or LU)

6 = X.25

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.

7:32767 = reserved

32768-65535 = undefined and available for agent implementers to use.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents

Next section

Index

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 parent correlator bit (Flags First Byte a) is set in the arm_start() buffer.
1 byte	Correlator format (unsigned8)=1 Only one format is defined at this point, but others could be added in the future.
1 byte	Flags 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 arm_start(). The agent will decide whether to set this bit, based on its capabilities and how it is configured. 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: 0 = reserved 1 = IPv4 2 = IPV4+port number 3 = IPv6 4 = IPv6+port number 5 = SNA 6 = X.25 7:32767 = reserved 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. For example: The management application wants to contact the agent to know the name of the application, user, and transaction class running this transaction instance. Although the address of the agent is known from the Address field, the protocol that one uses to interface to the agent could be anything. The management application may know how to access several different agents, and could use these values to determine if the correlator came from an agent that it knows how to access. Alternatively, an agent has a special capability. For example, maybe version 3.3 of a vendor's agent analyzes data in a particular way, but previous versions do not. The management application could use this field to see what are the agent's 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 found at: `ftp://ftp.isi.edu/in-notes/iana/assignments/enterprise-numbers` 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)
Maximum 146 bytes	Address 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 arm_start() calls as part of the buffer pointed to by the data pointer. The maximum size of the buffer is 256 bytes, of which 88 bytes are used for other fields, leaving 168 bytes for the correlator. An application should allocate space for the full 256 bytes when making the arm_start() call, but can then use the Correlator Length field to determine how long the correlator really is, and only forward that much data to other cooperating applications. 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. 0 = reserved 1 = IPv4 Bytes 0:3 4 byte IP address 2 = IPV4+port number Bytes 0:3 - 4 byte IP address Bytes 4:5 - 2 byte IP port number 3 = IPv6 Bytes 0:15 - 16 byte IP address 4 = IPv6+port number Bytes 0:15 - 16 byte IP address Bytes 16:17 - 2 byte IP port number 5 = SNA Bytes 0:7 - EBCDIC-encoded network ID Bytes 8:15 - EBCDIC-encoded network accessible unit (control point or LU)