arm_report_transaction (3) - Linux Manuals

arm_report_transaction: report transaction statistics

NAME

arm_report_transaction - report transaction statistics

SYNOPSIS

#include <arm4.h>

arm_error_t
arm_report_transaction(

 const arm_app_start_handle_t app_handle, 

 const arm_id_t *tran_id, 

 const arm_tran_status_t tran_status, 

 const arm_response_time_t response_time, 

 const arm_stop_time_t stop_time, 

 const arm_correlator_t *parent_correlator, 

 const arm_correlator_t *current_correlator, 

 const arm_int32_t flags, 

 const arm_buffer4_t *buffer4);

DESCRIPTION

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:

1.

Call arm_generate_correlator() to get a correlator for this transaction.

2.

Invoke the child transaction, passing the correlator returned in step (1) to the child.

3.

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:
 

0

(ARM_STATUS_GOOD) = transaction completed successfully

1

(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.

2

(ARM_STATUS_FAILED) = transaction completed in error

3

(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.

RETURN VALUE

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

ERRORS

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:

ARM_FAILURE_NULL_ARGUMENT

The tran_id must not be null.

ARM_FAILURE_INVALID_ARGUMENT

The app_handle provided is invalid.

ARM_FAILURE_INTERNAL_ERROR

An internal error has occurred that prevented the operation from completing. Check your system log for more details.

CONFORMING TO

ARM Issue 4.0 C Language Bindings, Version 2

EXAMPLE

None.