ARM 4.1 Sub-buffers
[ARM 4.1]
Data Structures | |
| struct | arm_subbuffer_block_cause |
| used to specify a block cause for a blocking transaction. More... | |
| struct | arm_subbuffer_message_rcvd_event |
| used to pass an received event to the ARM implementation. More... | |
| struct | arm_subbuffer_message_sent_event |
| used to pass a sent event to the ARM implementation. More... | |
| struct | arm_subbuffer_formatted_arrival_time_usecJan1970 |
| used to pass a arrival time since jan 1970. More... | |
| struct | arm_subbuffer_formatted_arrival_time_strings |
| used to pass a arrival time in a string representation More... | |
| struct | arm_subbuffer_prep_time |
| used to pass a arrival time as a pre-calculated preparation time More... | |
| struct | arm_subbuffer_prep_stats |
| used to pass a arrival time as a pre-calculated preparation statistics More... | |
| struct | arm_subbuffer_diag_properties |
| used to pass diagnostic detail properties to the ARM implementation More... | |
| struct | arm_subbuffer_app_control |
| The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers. More... | |
| struct | arm_subbuffer_tran_id_control |
| The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for all instances using a registered transaction ID. More... | |
| struct | arm_subbuffer_tran_instance_control |
| The Transaction Instance Control sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for a transaction instance. More... | |
Defines | |
| #define | ARM_SUBBUFFER_BLOCK_CAUSE 8 |
| Block cause sub-buffer format see arm_subbuffer_block_cause_t. | |
| #define | ARM_SUBBUFFER_MESSAGE_RCVD_EVENT 9 |
| Message received event sub-buffer format see arm_subbuffer_message_rcvd_event_t. | |
| #define | ARM_SUBBUFFER_MESSAGE_SENT_EVENT 10 |
| Message sent event sub-buffer format see arm_subbuffer_message_sent_event_t. | |
| #define | ARM_SUBBUFFER_FORMATTED_ARRIVAL_TIME_USECJAN1970 11 |
| Formatted arrival time UsecJan1970 sub-buffer format see arm_subbuffer_formatted_arrival_time_usecjan1970_t. | |
| #define | ARM_SUBBUFFER_FORMATTED_ARRIVAL_TIME_STRINGS 12 |
| Formatted arrival time strings sub-buffer format see arm_subbuffer_formatted_arrival_time_strings_t. | |
| #define | ARM_SUBBUFFER_PREP_TIME 13 |
| Preparation time sub-buffer format see arm_subbuffer_prep_time_t. | |
| #define | ARM_SUBBUFFER_PREP_STATS 14 |
| Preparation statistics sub-buffer format see arm_subbuffer_prep_stats_t. | |
| #define | ARM_SUBBUFFER_DIAG_PROPERTIES 15 |
| Diagnostic properties sub-buffer format see arm_subbuffer_diag_properties_t. | |
| #define | ARM_SUBBUFFER_APP_CONTROL 108 |
| Application control sub-buffer format see arm_subbuffer_app_control_t. | |
| #define | ARM_SUBBUFFER_TRAN_ID_CONTROL 109 |
| Transction ID control sub-buffer format see arm_subbuffer_tran_id_control_t. | |
| #define | ARM_SUBBUFFER_TRAN_INSTANCE_CONTROL 110 |
| Transaction instance control sub-buffer format see arm_subbuffer_tran_instance_control_t. | |
Typedefs | |
| typedef struct arm_subbuffer_block_cause | arm_subbuffer_block_cause_t |
| used to specify a block cause for a blocking transaction. | |
| typedef struct arm_subbuffer_message_rcvd_event | arm_subbuffer_message_rcvd_event_t |
| used to pass an received event to the ARM implementation. | |
| typedef struct arm_subbuffer_message_sent_event | arm_subbuffer_message_sent_event_t |
| used to pass a sent event to the ARM implementation. | |
| typedef struct arm_subbuffer_formatted_arrival_time_usecJan1970 | arm_subbuffer_formatted_arrival_time_usecJan1970_t |
| used to pass a arrival time since jan 1970. | |
| typedef struct arm_subbuffer_formatted_arrival_time_strings | arm_subbuffer_formatted_arrival_time_strings_t |
| used to pass a arrival time in a string representation | |
| typedef struct arm_subbuffer_prep_time | arm_subbuffer_prep_time_t |
| used to pass a arrival time as a pre-calculated preparation time | |
| typedef struct arm_subbuffer_prep_stats | arm_subbuffer_prep_stats_t |
| used to pass a arrival time as a pre-calculated preparation statistics | |
| typedef struct arm_subbuffer_diag_properties | arm_subbuffer_diag_properties_t |
| used to pass diagnostic detail properties to the ARM implementation | |
| typedef struct arm_subbuffer_app_control | arm_subbuffer_app_control_t |
| The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers. | |
| typedef struct arm_subbuffer_tran_id_control | arm_subbuffer_tran_id_control_t |
| The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for all instances using a registered transaction ID. | |
| typedef struct arm_subbuffer_tran_instance_control | arm_subbuffer_tran_instance_control_t |
| The Transaction Instance Control sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for a transaction instance. | |
Typedef Documentation
| typedef struct arm_subbuffer_app_control arm_subbuffer_app_control_t |
The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers.
Its use is optional for both applications and ARM implementations. Further, the control settings represent preferences; they are not binding on the application.
The scope of the settings applies to all transactions registered by this application. These settings, except for app_control_used, tran_id_control_used, tran_instance_control_used, show_private, and show_secure may be overridden for specific transaction IDs and/or instances.
The Application Control sub-buffer is passed on arm_start_applicaiton() or with a special form of arm_generate_correlator(). This special form sets current_correlator = Null. Setting current_correlator = Null renders the arm_generate_correlator() call meaningless for the purpose of generating a correlator.
- Note:
- Some ARM 4.0 implementations do not expect to find a null current correlator value in arm_generate_correlator() and set the return code to –1012. See the Note in the arm_generate_correlator() description for an explanation of how to proceed.
The app_control_used setting is used as a handshake to determine whether both the application and the ARM implementation are using instrumentation control. Both must agree if instrumentation control is to be used. This provides protection for applications and implementations that do not support the capability.
- Note:
- A return value of app_control_used=False does not indicate that the ARM library is not collecting data. The application should continue to make ARM calls using its default assumptions about the appropriate amount of transaction detail.
| typedef struct arm_subbuffer_block_cause arm_subbuffer_block_cause_t |
used to specify a block cause for a blocking transaction.
Applications may indicate that they are blocked waiting on an external event using the arm_block_transaction() function. When the application becomes unblocked it indicates the same using arm_unblock_transaction(). Calling arm_stop_transaction() implicitly executes an arm_unblock_transaction() for every blocking condition whose end has not been explicitly indicated using arm_unblock_transaction().
Calling arm_block_transaction() with no further information does not indicate the cause of the blocking condition. The Block Cause sub-buffer provides a means to indicate the cause of the blocking condition. Its use is optional. It is valid on the following calls:
In the case of application servers that loop on queued message requests, it is important to distinguish between the application being blocked and a message being blocked (or simply not available yet). arm_block_transaction() and arm_unblock_transaction() are used only within the scope of paired arm_start_transaction() and arm_stop_transaction() calls that indicate the time that work is being processed. If the application server is idle waiting for work to process it would not report this time using arm_block_transaction() and arm_unblock_transaction().
| typedef struct arm_subbuffer_diag_properties arm_subbuffer_diag_properties_t |
used to pass diagnostic detail properties to the ARM implementation
Applications may provide additional properties of the form name=value when a transaction ends [arm_stop_transaction() or arm_report_transaction()] by passing properties in the Diagnostic Properties sub-buffer. The sub-buffer is ignored on all other calls. There are no implicit requirements on how or if these values are processed
Either the Diagnostic Properties or the Diagnostic Details sub-buffer may be provided, but not both.
There are constraints on the number of non-null properties and their size at any point in time.
| Constraint Description | Constraint Value |
|---|---|
| Maximum number of non-null properties | 20 |
| Maximum number of characters of any property name, including the termination character | 128 |
| Maximum number of characters of any property name + property value, including the termination characters | 2048 |
| Maximum number of characters of all property names + property values, including the termination characters | 4096 |
| typedef struct arm_subbuffer_formatted_arrival_time_strings arm_subbuffer_formatted_arrival_time_strings_t |
used to pass a arrival time in a string representation
When the application is unable to call ARM when the transaction starts, but it can capture and save a timestamp at that time, the application can format the arrival time, store it in the Formatted Arrival Time Strings sub-buffer, and provide the sub-buffer with arm_start_transaction().
| typedef struct arm_subbuffer_formatted_arrival_time_usecJan1970 arm_subbuffer_formatted_arrival_time_usecJan1970_t |
used to pass a arrival time since jan 1970.
When the application is unable to call ARM when the transaction starts, but it can capture and save a timestamp at that time, the application can format the arrival time, store it in the Formatted Arrival Time UsecJan1970 sub-buffer, and provide the sub-buffer with arm_start_transaction().
used to pass an received event to the ARM implementation.
The Message Received Event sub-buffer is optionally used to indicate that one or more messages have been received that have an effect on the execution state of a transaction. Some cases of interest are the following.
- A message causes the transaction to initiate.
- A message causes the transaction to unblock.
- A message is received that terminates an asynchronous transaction or a step in an asynchronous transaction.
- A message has been received during the processing of a transaction that does not fall into one of the categories above.
The Message Received Event sub-buffer can be provided on the following function calls:
- arm_start_transaction()
- arm_update_transaction()
- arm_stop_transaction()
- arm_block_transaction()
- arm_unblock_transaction()
,
used to pass a sent event to the ARM implementation.
The Message Sent Event sub-buffer is optionally used to indicate that one or more messages have been sent that have an effect on the execution state of a transaction. The cases of interest are the following.
- A message is sent that causes the transaction to block.
- A message is sent that initiates or terminates an asynchronous transaction or a step in an asynchronous transaction.
- A message is sent that is part of a conversational exchange between this transaction and another transaction.
- A message is sent that is not part of a known conversational exchange.
The Message Sent Event sub-buffer can be provided on the following function calls:
- arm_start_transaction()
- arm_update_transaction()
- arm_stop_transaction()
- arm_block_transaction()
- arm_unblock_transaction()
,
| typedef struct arm_subbuffer_prep_stats arm_subbuffer_prep_stats_t |
used to pass a arrival time as a pre-calculated preparation statistics
When the application is unable to call ARM when the transaction starts, or measure the delay for a specific transaction instance (for which it uses the Preparation Time sub-buffer), but it can measure the mean over several transactions, the application can provide the measurements in the Arrival Statistics sub-buffer, and provide the sub-buffer with arm_start_transaction().
| typedef struct arm_subbuffer_prep_time arm_subbuffer_prep_time_t |
used to pass a arrival time as a pre-calculated preparation time
When the application is unable to call ARM when the transaction starts, but it can measure the delay for the transaction instance, the application can provide the measurements in the Preparation Time sub-buffer, and provide the sub-buffer with arm_start_transaction().
| typedef struct arm_subbuffer_tran_id_control arm_subbuffer_tran_id_control_t |
The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for all instances using a registered transaction ID.
Its use is optional for both applications and ARM implementations. Further, the control settings represent preferences; they are not binding on the application.
The scope of the settings applies to all instances of the specified transaction ID. These settings may be overridden by the Transaction Instance Control sub-buffer.
The Transaction ID Control sub-buffer is passed using a special form of arm_generate_correlator(). This special form sets current_correlator = Null. Setting current_correlator = Null renders the arm_generate_correlator() call meaningless for the purpose of generating a correlator.
- Note:
- Some ARM 4.0 implementations do not expect to find a null current correlator value in arm_generate_correlator() and set the return code to –1012. See the Note in the arm_generate_correlator() description for an explanation of how to proceed.
The control_used setting is used as a handshake to determine whether both the application and the ARM implementation are using instrumentation control. Both must agree if instrumentation control is to be used. This provides protection for applications and implementations that do not support the capability.
- Note:
- A return value of control_used=False does not indicate that the ARM library is not collecting data. The application should continue to make ARM calls using its default assumptions about the appropriate amount of transaction detail, or the settings established using the application control buffer.
The Transaction Instance Control sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers for a transaction instance.
Its use is optional for both applications and ARM implementations. Further, the control settings represent preferences; they are not binding on the application.
The scope of the settings applies to a single transaction instance. They do not carry over to any other transaction instance. These settings override any settings set using the Application Control or Transaction ID Control sub-buffers.
The Transaction Instance Control sub-buffer is passed using a special form of arm_generate_correlator(). This special form sets current_correlator = Null. Setting current_correlator = Null renders the arm_generate_correlator() call meaningless for the purpose of generating a correlator.
- Note:
- Some ARM 4.0 implementations do not expect to find a null current correlator value in arm_generate_correlator() and set the return code to –1012. See the Note in the arm_generate_correlator() description for an explanation of how to proceed.
The control_used setting is used as a handshake to determine whether both the application and the ARM implementation are using instrumentation control. Both must agree if instrumentation control is to be used. This provides protection for applications and implementations that do not support the capability.
- Note:
- A return value of control_used=False does not indicate that the ARM library is not collecting data. The application should continue to make ARM calls using its default assumptions about the appropriate amount of transaction detail, or the settings estabslished using the application control buffer.
Documentation generated on Thu May 24 2018 22:24:14. © 2018 by MyARM GmbH