Java Trace SDK

Using the Instana Java Trace SDK (github), it is possible to manually instrument Entries and Exits that Instana does not yet know, as well as markup interesting sections of custom code. It also supports creating custom correlation across binary protocols and adding custom defined key value pairs to spans (for extracting relevant information).

Exits and Entries for a Custom Binary Protocol

The published example app ( contains a CustomTCP server and client, illustrating how the SDK can be used for marking entries, exits, and performing correlations.

Using the instana-java-sdk

The Java Trace SDK requires you to add a small jar file to your application. This jar file contains the annotations and helper classes used to markup the sections of code that Instana should handle. When using Maven, the dependency can be easily added with:


The instana-java-sdk artifact is available from the default Maven central repository.

When no agent is monitoring the JVM, which includes the above library and has sections marked with annotations, then they act as No-Op. It is safe to use the annotations, they do not have any impact at all as long as no agent is monitoring the JVM. To have an Instana agent actually make use of the annotations, you have to tell it which Java package names have those annotations. This is because scanning for annotations is a heavyweight process, and scanning the complete classpath of big applications can take a long time.

The required configuration.yaml section looks like this:

# Java Tracing
    # By default no packages are scanned for SDK annotations.
        - 'com.mycompany.backend'
        - 'com.mycompany.frontend'

The packages are scanned recursively. That is, if the com.mycompany.backend is configured to be scanned for annotations, com.mycompany.backend.impl and other sub-packages will be scanned as well.

Marking an Entry

To mark a method in an Entry span, just add the following annotation, as shown in this example

@Span(type = Type.ENTRY, value = "custom-tcp-server")

As soon as Instana sees code entering this method, a trace is started.

Marking an Exit

To mark a method in an Exit span, just add the following annotation, as shown in this example:

@Span(type = Type.EXIT, value = "custom-tcp-client", capturedStackFrames = 5)

Whenever this method is encountered, Instana will record a Span labeling this as an Exit call.

Correlating Exit and Entry

In many cases where an Exit and Entry are not yet known to Instana, applications use them to perform some kind of remote communication. When an Exit is encountered and no correlation is performed, the trace "breaks," meaning two traces would be observed, one ending at the Exit, and a new one starting at the Entry.

It is possible to help Instana perform a correlation by manually transporting correlation information across the remote communication. On the exit side, the exit annotation will make sure that the required correlation identifiers exist. One can simply invoke (

SpanSupport.addTraceHeadersIfTracing(Type.EXIT, params);

to fill the given params map with the required IDs. Should the protocol support other means of transporting other data, it is possible to get the IDs with: 



On the entry side, it is important to read the parameters and set them for the Entry Span, before the span is created by annotations:


SpanSupport.inheritNext(SpanSupport.stringAsId(trace), SpanSupport.stringAsId(span));

By doing so, the Entry Span will automatically join the remote trace and add itself as child span of the calling Exit.

Conversion and Naming

In certain situations it might be beneficial to transform SDK spans into a different type such as HTTP or RPC, to better represent the origin of these spans. This can be done by making use of the fields as defined in the Open Tracing Semantic Conventions. Conversions to the following types are possible:

  • HTTP: depends on http.url, optional are http.method and http.status_code
  • Database: depends on db.instance and db.statement, optional are db.type and db.user
  • RPC: depends on (not defined by Open Tracing) and one of the Open Tracing peer.address, peer.hostname or peer.service fields
  • MESSAGING: depends on message_bus.destination
  • BATCH: depends on batch.job (not defined by Open Tracing)

These fields can be set using the SpanSupport.annotate(type, name, key, value) method.

Instana will treat these fields the way automatic agent instrumentation works as soon as these fields are nested under the tags. key. So, for example, to set the http.url field, the method call would look like this:

SpanSupport.annotate(<type>, <name>, "tags.http.url", "service://my-awesome-service/some/path")

When semantic OpenTracing fields are correctly tagged, the respective rules will be used for Service and Endpoint naming as defined in Application & Service Management.

You can use the special tags service, endpoint and call to explicitly set the Service, Endpoint and/or Call name. Those tags take precedence over any other Service and Endpoint naming rules:

  • SpanSupport.annotate(<type>, <name>, "tags.service", "My Service Name")
  • SpanSupport.annotate(<type>, <name>, "tags.endpoint", "My Endpoint Name")
  • SpanSupport.annotate(<type>, <name>, "", "My Call Name")

When no specific fields are provided, the name of the Service for all SDK spans will be SDK. The Endpoint and Call name will be the given name in either the @Span annotation or the SpanSupport.annotate() method.


Should the SDK traces not show up in the UI, several items are worth checking:

  • Is the instana-java-sdk jar shipped with the application? If not, the agent will silently do nothing, as it is in no-op mode.
  • Does the configuration.yaml file reference all the packages with annotations?
  • Is tracing active?
  • Is the YAML syntax correct?
  • Are other APM agents active? Most other APM agents are known to interfere with Instana, thus Instana's agent will not perform tracing if it detects other agents. If this is the case, the following will appear in the logs:

    JVM <PID> is running the <3rdParty> agent, which is known to be causing problems for the Instana Agent. Tracing will not be enabled for this JVM.
  • Turn on DEBUG logging and look for a message like:

    2016-09-05T08:26:14.094+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403). Successfully instrumented class com.acme.resources.HelloWorldResource [[email protected]]`
    2016-09-05T08:26:14.145+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403) - Spent 188ms and 124kb transforming SDK classes. 
  • Are the annotated methods actually hit by a user/load driver? The Instana agent will interact with each JVM shortly after it has been started. As a result, transactions that happen before the agent attached are not captured. Make sure to annotate methods that are normally hit during the lifetime of the application.


Why do captured parameter and return values only show class names and hashed memory addresses?

The instrumentation will call toString() on each captured parameter and return value. This means that the values visible within Instana directly depend on the specific toString() method implementations of the parameter and return value classes.

When toString() is not overridden, then java.lang.Object#toString() is eventually used. This method returns getClass().getName() + '@' + Integer.toHexString(hashCode()) and results in the format you are seeing.

To improve visibility into captured parameters and return values, we recommend to properly override toString().

Why are return values sometimes not available?

Return values may not be available even though captureReturn=true is set, when…

  • an exception is thrown by the method,
  • the method has a void return type or when
  • the method returns null.