LightStep is happy to announce the v1.1.1 release of the OpenTracing SpecialAgent — a Java agent that automatically instruments Java applications, using the OpenTracing plugins that would normally be installed by hand. SpecialAgent allows application developers to automatically instrument Java applications running on JVM versions 1.7, 1.8, 9, 10 and 11.
Why Java?
Java is one of the most commonly used application platforms, powering mobile, desktop, and enterprise solutions of all varieties. With the growing adoption of the OpenTracing standard, the SpecialAgent offers the reference integration of OpenTracing to the Java platform. With LightStep’s support, the SpecialAgent project presents an open tracing architecture for the development of instrumentation plugins by the OpenTracing community.
What’s “special”?
The SpecialAgent was “special” from inception — an open-source initiative to invent an extensible standard for automated tracing technology. With the OpenTracing community at its foundation, the development, maintenance, and contribution model for the SpecialAgent project provides an extensible alternative to the many existing proprietary solutions. With its ease of integration into Java applications, the SpecialAgent seamlessly connects to OpenTracing-compliant tracers — such as the Jaeger and LightStep tracers — to immediately start observing and propagating distributed traces. Providing a general solution for all Java applications, the SpecialAgent requires no more than a one-line command-line entry for installation. And if restarting your application is not an option, the SpecialAgent supports “dynamic attach” to running applications.
The SpecialAgent is architected to be a compatible, resilient, and stable agent solution. Established at its core are complex algorithms that:
- Ensure bytecode compatibility is asserted before instrumentation occurs, to prevent unintentional consequences due to mismatched 3rd-party library versions, instrumentation plugin versions, or class spec versions. This compatibility test provides a gateway activation or deactivation for instrumentation plugins as the SpecialAgent attaches to a target application.
- Guarantee that 3rd-party libraries will be successfully instrumented regardless in which class loader the library is loaded. Even if the 3rd-party library is loaded in a class loader that is isolated from the system loader, the SpecialAgent is able to detect the target loader, and thereafter dynamically inject instrumentation code where needed. This general solution to all class loader challenges allows instrumentation plugin code to never worry about class loader complexities, and thus focus solely on instrumentation logic.
- Provide a comprehensive testing framework for plugin developers to implement bulletproof instrumentation logic, that thus attributes the qualities of compatibility, resilience, and stability to each of the plugins themselves.
Supported Plugins
SpecialAgent is engineered to be a “pluggable” platform, allowing individual developers to contribute to the project and to the greater OpenTracing community. In fact, most instrumentation plugins that are currently included in the opentracing-contrib organization have been the result of community effort.
We encourage developers to implement and to submit instrumentation plugins for 3rd-party libraries.
After the development of the instrumentation plugin, the plugin must be accompanied by an implementation of an AgentRule that connects the plugin to the SpecialAgent. We openly welcome contributions of AgentRule implementations for the integration of instrumentation plugins to the SpecialAgent.
For a reference of the AgentRule and integration API, please refer to the SpecialAgent API.
The v1.1.1 release of the SpecialAgent supports a set of instrumentation plugins, including:
- OkHttp3
- JDBC API (java.sql)
- Concurrent API (java.util.concurrent)
- Java Web Servlet API (javax.servlet)
- Mongo Driver
- Apache Camel
- AWS SDK
- Cassandra Driver
- JMS API (javax.jms v1 & v2)
- Elasticsearch6 Client
- RxJava 2
- Kafka Client
- AsyncHttpClient
- RabbitMQ Client
- RabbitMQ Spring
- Thrift
- GRPC
- Jedis Redis Client
- Apache HttpClient
- Lettuce Redis Client
- Spring Web
- Spring Web MVC
- Spring WebFlux
- Redisson Redis Client
For a reference of the current list of supported plugins, please refer to the
Supported Plugins.
Development of the next instrumentation plugins is underway, with focus set on the most popular third-party libraries, as well as those for which traces would be most valuable.
Is there a 3rd-party library you’d like to see instrumented and integrated with SpecialAgent?
Please let us know by filing an issue in the SpecialAgent’s GitHub project.
Demo
We have implemented a demo of the SpecialAgent, providing an example use-case of a real-world application. The demo is available here.
Next Steps
The SpecialAgent v1.1.1 has been released, and we are excited to get it into the hands of developers and organizations. Your feedback, thoughts, and suggestions will point our way toward the next milestone. If you’re already a LightStep customer and you’d like to start using the SpecialAgent, please get in touch with us to learn more or check it out on GitHub.
