arm_report_transaction - report transaction statistics


#include <arm4.h>


    const arm_app_start_handle_t 

    const arm_id_t *

    const arm_tran_status_t 

    const arm_response_time_t 

    const arm_stop_time_t 

    const arm_correlator_t *

    const arm_correlator_t *

    const arm_int32_t 

    const arm_buffer4_t *


arm_report_transaction() is used to report statistics about a transaction that has already completed.
  arm_report_transaction() may be used instead of a paired arm_start_transaction() and arm_stop_transaction() call. The application would have measured the response time. The transaction could have executed on the local system or on a remote system. If it executes on a remote system, the system address sub-buffer passed on the arm_start_application() provides the addressing information for the remote system.

If the transaction represented by the arm_report_transaction() call is the correlation parent of another transaction, arm_generate_correlator() must be used to get a parent correlator, prior to invoking the child transaction (because it must be passed to the child). In this case, the sequence is the following:

Call arm_generate_correlator() to get a correlator for this transaction.
Invoke the child transaction, passing the correlator returned in step (1) to the child.
When this transaction is complete, invoke arm_report_transaction() to report the statistics about the transaction. When used, it prevents certain types of proactive management, such as monitoring for hung transactions or adjusting priorities, because the ARM implementation is not invoked when the transaction is started. Because of this, the use of arm_start_transction() and arm_stop_transaction() is preferred over arm_report_transaction().
  The intended use is to report status and response time about transactions that recently completed (typically several seconds ago) in the absence of an ARM-enabled application and/or ARM implementation on the system on which the transaction executed.

app_handle is a handle returned in an out parameter from an arm_start_application() call in the same process.

buffer4 is a pointer to the user data buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are arm_subbuffer_diag_detail_t, arm_subbuffer_metric_values_t, arm_subbuffer_tran_context_t, and arm_subbuffer_user_t.

current_correlator is a pointer to the correlator for the transaction that has completed, if any. If the pointer is null (ARM_CORR_NONE), there is no current correlator.
  flags contains 32-bit flags. In the least significant byte, 0x00000001 (ARM_FLAG_TRACE_REQUEST) is set if the application requests/suggests a trace.

parent_correlator is a pointer to a parent correlator, if any. If the pointer is null (ARM_CORR_NONE), there is no parent correlator.

response_time is the response time in nanoseconds.
  stop_time is an arm_int64_t that contains the number of milliseconds since Jan 1, 1970 using the Gregorian calendar. The time base is GMT (Greenwich Mean Time). There is one special value, -1 (ARM_USE_CURRENT_TIME), which means use the current time.

tran_id is a transaction ID returned in an out parameter from an arm_register_transaction() call in the same process.

tran_status indicates the status of the transaction. The following values are allowed:

(ARM_STATUS_GOOD) = transaction completed successfully
(ARM_STATUS_ABORTED) = transaction was aborted before it completed. For example, the user might have pressed "Stop" or "Back" on a browser while a transaction was in process, causing the transaction, as measured at the browser, to be aborted.
(ARM_STATUS_FAILED) = transaction completed in error
(ARM_STATUS_UNKNOWN) = transaction completed but the status was unknown. This would most likely occur if middleware or some other form of proxy instrumentation measured the transaction. This instrumentation may know enough to know when the transaction starts and stops, but does not understand the application-specific semantics sufficiently well to know whether the transaction was successful.


On success, the function returns ARM_SUCCESS. A non-zero value indicates an error.


If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging.

The following errors are recognized by this implementation, but may not be portable to other implementations:

The tran_id must not be null.
The app_handle provided is invalid.
An internal error has occurred that prevented the operation from completing. Check your system log for more details.


ARM Issue 4.0 C Language Bindings, Version 2




arm_generate_correlator(3), arm_register_transaction(3), arm_start_application(3), arm_start_transaction(3), arm_stop_transaction(3)