Bindings

Bindings

This section describes the ARM language bindings supported by MyARM. It provides a more detailed description of 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 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 implementation could have different object layouts and different linker symbol names.

This problem does not arise within plain ANSI-C programs.

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

ARM 4.0 unsupported features

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

• Binding threads to a transaction using arm_bind_thread() and arm_unbind_thread().
• Turning tracing on and off using the ARM_FLAG_TRACE_REQUEST flag. MyARM by default traces all transactions.

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 and Solaris platforms, where as libarm4.dll used on Windows platforms.

"Agent shared library overview" also shows that the libarm4.so library in turn uses different data sink shared libraries which are loaded at runtime according to the current configuration. Here the MySQL data sink library libmyarm_mysqlsink.so is shown which stores any ARM data which is passed from 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 starts an own thread to communicate with the different backends. 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 backend data sink is configured.

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.

ARM 4.0 Java Binding

The ARM 4.0 Java Binding published by The Open Group defines a complete set of Java interfaces 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 Java interfaces as it is published by The Open Group (see ARM4J for a interface description) it describes the concrete implementation and special characteristics of MyARM for Java. Read also the creating ARM object appendix in the agent reference.

JNI Implementation

The current implementation of the ARM 4.0 Java binding makes use of the ARM 4.0 C implementation using the Java native interface (JNI). Therefore all features and characteristics of the C implementation apply to the MyARM for Java agent. The implementation is derived from the official ARM 4.0 SDK which was also developed by us for the ARM working group within The Open Group. If there is a high demand for a Java native ARM 4.0 implementation we consider implementing such a native Java agent.

ARM 4.0 CSharp Binding

Currently no official ARM 4.0 CSharp binding exists from The Open Group. But the Eclipse project derived ARM 4.0 CSharp interfaces from the official ARM 4.0 Java binding. With version 1.2.0 MyARM supports this ARM 4.0 CSharp interface.

The MyARM implementation of the ARM 4.0 CSharp interfaces are completely written in CSharp. Only some of the data sinks will use the an external DLL using platform invoke. Currently the following data sinks are written entirely in CSharp:

• File data sink

All other data sinks are supported using our C implementation. Thus if you want 100% managed code you have to use the data sinks described above.

CSharp MyARM ARM 4.0 assembly

CSharp uses so-called assemblies as its library concept. Due to the fact that there is currently no official OpenGroup technical standard describing the language binding for CSharp MyARM provides two different assemblies:

1. ARMInterface.dll -- Assembly which contains all interfaces of the ARM 4.0 C# binding.
2. ARMImplementation.dll -- Assembly which contains the MyARM C# ARM 4.0 agent.

An application which wants to use ARM needs to load the correct implementation assembly. This can be done by the C# Assembly.Load() method or by specifying an external type with its assembly name and version and calling the Type.GetType() method. When the ARM implementation assembly was loaded successfully. The application needs to create the appropriate ARM factories as described in the creating ARM object appendix in the agent reference.

Response times

The ARM standard defines response times measured in nanoseconds. Not all systems today provide such a high granularity of time stamps. For the CSharp binding we use the Stopwatch class of the .NET framework to measure response times. This class supports high resolution timing if the underlying hardware supports high resolution timers. Therefore the granularity depends on the hardware used.

Python ARM 4.0 binding

The ARM 4.0 python language binding is not an official OpenGroup ARM 4.0 binding. It was developed by David Carter using the ARM 4.0 C binding. See http://www.arm4.org/. MyARM has integrated this good peace of software in its MyARM environment. All features of the ARM 4.0 C binding applies to the python binding by the fact it uses directly the libarm4 agent implementation.

ARM 2.0 C Binding

The ARM 2.0 C Binding is one of the oldest and most used ARM APIs. For an easy transition and integration of old ARM 2.0 instrumented applications we provide an ARM 2.0 API wrapper for your real ARM 4.0 C implementation. Therefore any ARM 2.0 instrumented application can be mixed with newly instrumented ARM 4.0 applications.

The ARM 2.0 wrapper supports all features defined by the ARM 2.0 standard and maps it to the appropriate ARM 4.0 concepts. One exception is the ARM metric string 8 type which was dropped in the ARM 4.0 standard. The first string 8 metric type is mapped to an ARM string32 metric type.

But please use the new ARM 4.0 C API for instrumenting new applications. The ARM 2.0 API wrapper only exists for easy transition to the new ARM standard!