Java Agent for OpenTracing
NOTE: This project is no longer being actively developed. Please see the special agent project as an alternative.
Java Agent for instrumenting Java applications using an OpenTracing compliant Tracer.
The instrumentation is performed in a non-intrusive manner leveraging the ByteMan project to define a set of rules. These rules can be used to:
Install a framework integration (e.g. OkHttp, Servlet)
Define custom rules specific to an application (e.g. create spans to scope important internal units of work, or add tags to an existing span to identify business relevant properties)
The Java Agent for OpenTracing obtains an OpenTracing compliant Tracer using the GlobalTracer from the opentracing util project. If a tracer has not been registered, it will then use the TracerResolver mechanism to attempt to access one from the maven dependencies.
The Java Agent can be used in two ways:
Prepackaged Agent, Tracer and Dependencies
This approach is to build an uber jar, using the maven assembly or shade plugins, to package together
opentracing-agent.jar, the OpenTracing compliant
Tracer, any framework integrations, rules, etc.
The important point to remember is that, because the resulting jar will still be used as a javaagent, it needs the
manifest entries copied from the manifest in the
This approach is useful when wanting to instrument applications where modification of the classpath is not possible (e.g. executable jars), or wanting to maintain separation between the application and the tracing mechanism. It also benefits from being able to selective choose the framework integrations (and versions) that are required.
NOTE: An issue has been created to discuss providing tool support for this option.
Tracer and Framework Integrations on Classpath
This approach uses the plain
opentracing-agent.jar provided by this project, and obtains the OpenTracing
Tracer and any required framework integrations, rules, etc. from the classpath.
java -javaagent path/to/opentracing-agent.jar ...
This section lists examples of using the OpenTracing Java Agent.
- Spring Boot services (OpenTracing Tracer: Hawkular APM)
Creating custom rules
Custom rules are defined using the ByteMan rule format. These rules use a helper class (io.opentracing.contrib.agent.OpenTracingHelper) that provides access to the OpenTracing Tracer, as well as some additional support capabilities.
The custom rules should be placed in a file on the classpath called
Some example rules are:
RULE Custom instrumentation rule sayHello entry CLASS example.MyClass METHOD sayHello() HELPER io.opentracing.contrib.agent.OpenTracingHelper AT ENTRY IF TRUE DO getTracer().buildSpan("MySpan").startActive(); ENDRULE
The first line defines the name of the rule. The second identifies the target class, although it is also possibly to specify an interface (using the INTERFACE keyword). The third line identifies the method name (optionally specifying the parameter types).
The AT clause identifies the point at which the identified method will be instrumented. ENTRY means that the rule should be applied at the beginning of the method (see ByteMan documentation for other locations).
The IF statement enables a predicate to be defined to guard whether the rule is performed.
The DO clause identifies the actions to be performed when the rule is triggered.
getTracer() method (provided by the OpenTracingHelper) is used to access the OpenTracing
RULE Custom instrumentation rule sayHello normal exit CLASS io.opentracing.contrib.agent.custom.CustomRuleITest METHOD sayHello HELPER io.opentracing.contrib.agent.OpenTracingHelper BIND span : io.opentracing.ActiveSpan = getTracer().activeSpan(); AT EXIT IF span != null DO span.setTag("status.code","OK"); span.deactivate(); ENDRULE
This rule will trigger AT EXIT, so when the method is finished. The IF statement checks whether there
is an active span (assigned to the bound variable
span), so will only trigger if an active span exists.
The actions performed in this case are to set a tag status.code on the active span, and then finally the active span needs to be deactivated.
Supported framework integrations and directly instrumented technologies
NOTE: Currently the ByteMan rules for installing tracing filters/interceptors into the following frameworks is contained in this repository. However in the future the aim would be to move the rules to their associated framework integration projects, meaning that the rules would be detected only when the integration artifact is added to the classpath.
Framework integration repo: Web Servlet Filter
Currently supported containers:
Framework integration repo: OkHttp
Library integration repo: Mongo Driver
./mvnw clean install
If using JDK9, you will need to set the MAVEN_OPTS as follows:
MAVEN_OPTS="--add-modules java.se.ee" ./mvnw clean install
Follow instructions in RELEASE