Agent Development Kit (ADK)

The AppMon Agent Development Kit (ADK) extends the capability of the AppMon APM solution to areas and scenarios that are not supported by default sensors. For example, you can use the ADK for a proprietary protocol or for instrumenting native applications. The ADK enables you to trace transactions across different platforms and technology types and to correlate the parts of the transaction from all tiers into one PurePath.

Purpose

The AppMon ADK provides:

  • Following transactions across all tiers.
  • End-to-end tracing through Java, .NET, and native applications (C/C++, JNI, and others) in production.
  • Support for proprietary protocols. Sensors are available that allow AppMon to follow transactions across system boundaries more or less automatically, by tagging. If proprietary protocols are used, the Tagging ADK (available for Java, .NET, and C/C++) traces transactions even across those boundaries.
  • Visibility into native applications. The Native ADK can be used to instrument the source code for native applications.

Components and platforms

From the technology perspective, the AppMon ADK has the following components:

The Tagging ADK provides support for tagging across custom protocols.

The Native ADK provides both tagging and source-code instrumentation for all supported platforms and all applications that can load and call C/C++ libraries.

The CICS and IMS ADK provides an interface to the zOS Agent for tagging in COBOL, PL1, Assembler, and C/C++ in the z/OS CICS and IMS message processing region environments.

Concept

The AppMon ADK is a small layer between your application and the AppMon Agent that handles the communication to the AppMon Server. It provides an interface that enables applications to send necessary transactional information to the AppMon Server. The Server uses these pieces of information, or tags, to combine sub-paths into a real end-to-end PurePath.

ADK architecture
ADK architecture

Tagging concepts

The Tagging ADK enables you to retrieve the AppMon Trace Tag for the current transaction. This Trace Tag then needs to be sent through the proprietary protocol from the client side to the server side. On the server side, the Trace Tag is placed again. It enables the AppMon Server to link sub-paths of the same transaction together.

Types of tags

The ADK distinguishes between these different types of tags:

  • The Trace Tag consists of structured data that defines the unique identifier for a specific remote call.
  • The Custom Tag can be any user-defined, unstructured piece of data. Its content does not matter as long as it is unique for each remote call.

AppMon tagging (active tagging)

Using the Trace Tag is the recommended and most efficient way of tracing transactions across proprietary protocols. It's also called Active Tagging, because it actively retrieves a tag from the ADK at the client side and sends it over the protocol to the server side. The AppMon tag can be represented either as a byte array or as a character string, depending on the needs of the client-server protocol to which it has to be attached.

Custom tagging (passive tagging)

When AppMon tagging is technically not possible (the protocol cannot be expanded by adding the AppMon tag information), Custom Tagging might be an option. Custom Tagging uses an arbitrary identifier for linking paths together. This identifier must be unique for each invocation.

If a message sent from the client to the server has a unique message ID, this ID can be used as a custom tag instead of using the AppMon tag. Using the ID avoides protocol changes. Therefore, Custom Tagging is also called Passive Tagging.

Using existing message ID to link PurePaths
Using existing message ID to link PurePaths

ADK package contents

Package structure

After you install the ADK, the dynatrace-<version> folder has the following contents:

dynatrace-<version>
+--adk
|  +--doc
|  |  +--c-c++      Interface documentation of the open-source, reference language
                    bindings for C and C++
|  +--include       All necessary header files
|  +--lib           32-bit dynaTrace ADK libraries for specific platform
|  +--lib64         64-bit dynaTrace ADK libraries for specific platform
+--agent
|  +--lib           32-bit dynaTrace Agent for specific platform
|  +--lib64         64-bit dynaTrace ADK libraries for specific platform
+--samples
+--HelloWorld C++   C++ application showing how to use the ADK's basic functionality
+--Java and JNI     Sample application demonstrating tagging java call to JNI functions
+--MultiApp         Sample application implemented in C++, Java and .NET demonstrating
                    tagging over sockets.
+--ADK.profile.xml  System Profile used in all samples 

Sample applications

After installation, the samples subdirectory contains these sample applications:

  • HelloWorld C++: C++ application that starts and stops transactions, captures arguments, and traces across thread boundaries.
  • Java and JNI: Sample application that demonstrates tagging Java call to JNI functions.
  • MultiApp: Sample application implemented in C++, Java, and .NET, which demonstrates tagging over sockets using different technologies. The application can be run as client or server, where the client sends a request to the server to multiply two numbers.

To build the samples, add the Agent ADK library to the lib directory (Java) or to the referenced build path (.NET). For detailed information, refer to the readme files.

Licensing

  • All ADKs are royalty-free with the exception of use on z/OS. AppMon customers can integrate the ADKs into products and deploy as many instances as needed, without charge except on the IBM Mainframe (z/OS).
  • To collect data from deployed ADK applications, deploy and license one AppMon Agent for each application instance to be monitored. Java and .NET ADKs require the standard Java / .NET Agent with no licensing specifics. The Native ADK and CICS ADK require a special build of the AppMon Agent — the ADK Agent — that is licensed separately from the Java / .NET Agent on a per-Agent basis. The Native ADK requires its own license if running on z/OS. The CICS ADK (Agent) licensing is MSU-based.

Troubleshooting