The 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.
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.
The AppMon ADK is a small layer between your application and the 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.
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 avoids protocol changes. Therefore, Custom Tagging is also called Passive Tagging.
ADK package contents
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
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
- 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 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 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.
Make sure that the environment variable
DT_AGENTLIBRARY is set correctly and points to the Agent (
.so, depending on your platform). To get a list of defined environment variables, type set in the Windows command line.
For more details, set the environment variable
DT_DEBUGADK.To do this, type set DT_DEBUGADK=true, and run your application again. Additional output indicating the source of the error displays.
Error handling may not cover all possible error scenarios. If the debug output doesn't help identify the source of the problem, comment to this page to get assistance from the AppMon team.
Make sure the AppMon Server is up and running, and has an active license.
The binaries were built using Microsoft Visual Studio 2010.