Bindings

This section describes the ARM language bindings supported by MyARM. It provides a more detailed description of the MyARM set of ARM features.

ARM 4.0 C Binding

The ARM 4.0 C Binding published by The Open Group defines a C API to instrument applications to measure performance data. MyARM implements this API and can be used with any standard conforming instrumented application. This section does not describe the C API as it is published by The Open Group (see ARM4C for an API description), it describes the concrete implementation and special characteristics of MyARM.

C versus C++

The ARM 4.0 standard defines only a C API which can be used in C++ as well. The reason why there is no real C++ API is due to the fact how ARM is deployed within a system.

One major goal of ARM is that any application which is instrumented with a certain version of ARM should be able to run with any installed ARM agent of that version. But currently there does not exist any real application binary interface (ABI) standard for the C++ language. A compiler vendor can choose its own model how the compiler layouts objects or mangles class/method names to linker symbol names. So different ARM implementations could have different object layouts and different linker symbol names. This problem does not arise with plain ANSI-C programs.

ARM 4.0 C++ framework

However, MyARM provides a complete ARM 4.0 C++ framework using the ARM 4.0 C binding (See https://api.myarm.com/arm40cpp/). This framework is provided as source code which can be inlined or separately compiled. Therefore the ABI problem can be solved by the user of the ARM 4.0 C++ framework.

ARM 4.0 Optional features

In the ARM 4.0 document many features defined in the standard are marked as optional and may or may not be implemented by an agent. Besides the mandatory features MyARM supports the following optional features:

• Transaction correlation with the arm_start_transaction(), arm_report_transaction() and arm_generate_correlator() function calls
• Error reporting support using the arm_get_error_message() call
• Support for adjusting the start time for a transaction using the arm_get_arrival_time() call and the ARM_SUBBUFFER_ARRIVAL_TIME sub-buffer
• Support for blocking transactions using the arm_block_transaction() and arm_unblock_transaction() calls
• Binding threads to a transaction using arm_bind_thread() and arm_unbind_thread() or the ARM_FLAG_BIND_THREAD
• ARM metrics are fully supported using the sub-buffers ARM_SUBBUFFER_METRIC_VALUES and ARM_SUBBUFFER_METRIC_BINDINGS
• Full support of ARM identity properties using the sub-buffers ARM_SUBBUFFER_APP_IDENTITY and ARM_SUBBUFFER_TRAN_IDENTITY
• Full support of ARM context properties using the sub-buffers ARM_SUBBUFFER_APP_CONTEXT and ARM_SUBBUFFER_TRAN_CONTEXT
• Support of diagnostic detail information for failed or aborted transactions using the ARM_SUBBUFFER_DIAG_DETAIL sub-buffer
• Support of ARM 4.1 ARM_SUBBUFFER_BLOCK_CAUSE sub-buffer
• Basic support of ARM 4.1 ARM_SUBBUFFER_MESSAGE_RCVD_EVENT sub-buffer indicating end of flow measurement. In conjunction with ARM_FLAG_TRACE_REQUEST flag which indicates to wait for event flow auto response messages (see Event flow auto response handler) it is possible to automatically stop one-way messages

ARM 4.0 unsupported features

As described in the previous section many features are optional. Currently MyARM does not provide the following features:

• Turning tracing on and off using the ARM_FLAG_TRACE_REQUEST flag. MyARM by default traces all transactions.

  If a ARM_FLAG_TRACE_REQUEST flag is encountered MyARM enables the event flow auto response feature (see Event flow auto response handler).

Agent details

C Agent shared library architecture

The main part of the ARM agent is the shared library (object) which implements the ARM 4.0 C API. Each ARM instrumented application is linked against this library. The library base name is arm4 and for example libarm4.so is used under Linux platforms, whereas libarm4.dll, is used on Windows platforms.

Figure "Agent shared library overview" also shows that the libarm4.so library in turn uses different datasink shared libraries which are loaded at runtime according to the current configuration. Here the mysql datasink library libmyarm_mysqlsink.so is shown which stores ARM data which originating in the libarm4.so library into a MySQL database.

Multi-threading versus Single-threading

The ARM 4.0 standard states that any ARM implementation has to be thread-safe. The MyARM implementation uses threads of their own to process measured data (Figure "Agent data processing thread pipeline"). Therefore if you use MyARM in a single-threaded program it is not really single-threaded but the interference between the instrumented application and the MyARM agent is reduced to a minimum regardless which configuration is used.

Response times

The ARM standard defines response times measured in nanoseconds. Not all systems today provide such a high granularity of time stamps. table Response time granularity shows on which platform MyARM provides which granularity of response time measurements.

Return codes

The ARM 4.0 C Binding describes that a negative return code for any of the API calls indicates an error, a zero return code a success and a positive return code a warning. The MyARM specific return codes are documented in the agent reference appendix.

Overhead

An overview of the performance impact by using the MyARM ARM 4.0 C Binding is documented in the appendix ARM 4.0 C Binding agent overhead.