Configure Other Tracers

Application Performance Monitoring integrates with open-source tracing system tools (open-source tracers) such as Jaeger and Zipkin and enables you to upload trace data. It also supports context propagation between Application Performance Monitoring agents and open-source tracers.

This is especially useful if you have an existing Distributed Tracing system setup and want to switch to Application Performance Monitoring and use its features. To do so, you must perform the following tasks to ensure that the data collected using open-source tracers flows into Application Performance Monitoring.

  • Configure context propagation so the trace context information is propagated in the appropriate format, and add it to one or more HTTP request headers. The trace context enables the correlation of spans that come from different microservices but belong to the same transaction (trace) and are identified by a common Trace ID.

    Application Performance Monitoring uses the Zipkin format to propagate trace context so the Zipkin tracer does not require additional configuration. If you use Jaeger, then you must first configure Jaeger to consume and propagate trace context in the Zipkin format.

  • Configure the open-source tracers to report spans in the accepted format to Application Performance Monitoring.

    The supported span reporting format is the JSON-encoded Zipkin v2 format. For more information on the Zipkin v2 format, see Zipkin 2. If you use Jaeger, then you must first configure it to report in the Zipkin v2 format.

  • Configure the open-source tracers to connect to and send trace data to the Application Performance Monitoring collector URL.

Note that for trace sampling decisions, which are made to ensure that traces and spans are sampled to keep the trace data small but representative, Application Performance Monitoring complies with any sampling decision made by the open-source tracers if the root span is generated by the open-source tracer. If a trace involves the Application Performance Monitoring Browser Agent, every trace which originates in the Browser Agent is sampled.

Configure the Jaeger Client for Java

Here's information on the changes that must be made to the code of a Java application that uses the Jaeger client for distributed tracing, and use it to upload traces to Application Performance Monitoring.

To use the Jaeger tracer to upload traces from a Java application to Application Performance Monitoring, you must configure the Jaeger Java client for Zipkin compatibility and add the Application Performance Monitoring collector URL. To do so, you must make the following changes to your service's code:

  1. Along with the required Jaeger client dependencies, add the following dependencies to the pom.xml file.
    <dependency>
        <groupId>io.zipkin.reporter2</groupId>
        <artifactId>zipkin-sender-urlconnection</artifactId>
        <version>2.15.0</version>
    </dependency>
    <dependency>
        <groupId>io.jaegertracing</groupId>
        <artifactId>jaeger-zipkin</artifactId>
        <version>1.3.2</version>
    </dependency>
  2. Use the ZipkinV2Reporter to adapt a Zipkin 2 reporter to the Jaeger reporter interface and convert Jaeger spans to the JSON-encoded Zipkin v2 format. Ensure that you've specified the Application Performance Monitoring collector URL to upload spans to Application Performance Monitoring, and the name of your service or application.
    import io.jaegertracing.Configuration;
    import io.jaegertracing.zipkin.ZipkinV2Reporter;
    import zipkin2.reporter.AsyncReporter;
    import zipkin2.reporter.urlconnection.URLConnectionSender;
     
    /* .... */
     
    ZipkinV2Reporter reporter = new ZipkinV2Reporter(AsyncReporter.create(URLConnectionSender.create("<Application Performance Monitoring collector URL>")));
    JaegerTracer tracer = Configuration
        .fromEnv("<service-name>")
        .getTracerBuilder()
        .withReporter(reporter)
        .build();
     
    /* .... */
  3. Register B3TextMapCodec to use B3 propagation, which is a specification for the b3 header. These headers are used for trace context propagation across service boundaries.
    import io.jaegertracing.Configuration;
    import io.jaegertracing.internal.propagation.B3TextMapCodec;
    import io.opentracing.propagation.Format;
     
    /* .... */
     
    B3TextMapCodec b3Codec = new B3TextMapCodec.Builder().build();       
    JaegerTracer tracer = Configuration
        .fromEnv("<service-name>")
        .getTracerBuilder()
        .registerInjector(Format.Builtin.HTTP_HEADERS, b3Codec)
        .registerExtractor(Format.Builtin.HTTP_HEADERS, b3Codec)
        .build();
     
    /* .... */

    Note that if the Jaeger tracer is created using environment configuration (Configuration.fromEnv()) , setting the JAEGER_PROPAGATION environment variable to b3c sets the Zipkin (B3) context propagation mode without code changes.

Configure the Zipkin Client for Node.js

Here's information on the changes that must be made to the code of a Node.js application that uses the Zipkin client for distributed tracing, and use it to upload traces to Application Performance Monitoring.

To do so, make the following changes to the Zipkin tracer initialization code:

  1. Ensure that you've made the necessary changes to report spans in the JSON-encoded Zipkin v2 format.
  2. Add the Application Performance Monitoring collector URL, to upload spans to Application Performance Monitoring, and the name of your service or application.
  3. Disable the Zipkin "span joining" feature, if it's enabled. OpenTracing specification does not allow Span ID sharing between different spans within the same trace and this feature must be disabled.

Here's a sample of the Zipkin tracer initialization code, and the changes detailed in the procedure are in bold:

const {
  Tracer,
  BatchRecorder,
  jsonEncoder: {JSON_V2}
} = require('zipkin');
 
const CLSContext = require('zipkin-context-cls');
const {HttpLogger} = require('zipkin-transport-http');
 
// Setup the tracer
const tracer = new Tracer({
  ctxImpl: new CLSContext('zipkin'), // implicit in-process context
  recorder: new BatchRecorder({
    logger: new HttpLogger({
      endpoint: '<Application Performance Monitoring collector URL>', //Span collection endpoint URL setting
      jsonEncoder: JSON_V2 //Span format and encoding setting
    })
  }), // batched http recorder
  localServiceName: '<service-name>', // name of the application/service
  supportsJoin: false //Span join disable setting
});

APM Collector URL Format

The Application Performance Monitoring collector URL is required when configuring open-source tracers to communicate with Application Performance Monitoring service. This topic provides details about the APM Collector URL format.

The Application Performance Monitoring collector URL has the following format:

<apm-domain-short-id>.<apm-collector-domain>/<API version>/observations/<observationType>?dataFormat=<dataFormat>&dataFormatVersion=<dataFormatVersion>&dataKey=<dataKey>
Parameter Description Value

<apm-domain-short-id>.<apm-collector-domain>

This is the same value as the "dataUploadEndpoint" value from APM Domain. User can obtain this value from the APM Domain details page. String value.

For example: https://aaaabbbb.apm-agt.us-ashburn-1.oci.oraclecloud.com

<API version> API version number. String value.

For example: 20200101

<observationType> The type of the observation to retrieve.

Available values:

public-span

private-span

<dataFormat> The observation's data format.

For example: zipkin

Available values:

zipkin

<dataFormatVersion> The observation's data-format version.

Zipkin V2 format is only supported.

String value.

For example: 2

<dataKey> The observation's data key.

You can obtain this value from the APM Domain details page.

String value.

For example: 2C6YOLQSUZ5Q7IGN

The following APM collector URL uses observation type public-span, data format zipkin, data format version 2 and data key 2C6YOLQSUZ5Q7IGN:

https://aaaabbbb.apm-agt.us-ashburn-1.oci.oraclecloud.com/20200101/observations/public-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=2C6YOLQSUZ5Q7IGN

Configure APM Java Agent/Tracer to Interoperate with Other Tracers

The APM Java Agent/Tracer can be configured to work with other OpenTracing tracers (such as Jaeger and Zipkin) in order to form a complete trace.

When a HTTP call occurs, the APM Java Agent/Tracer will attempt to add HTTP headers to the call which can then be read on the other end to help connect spans together.

You can change this format via the com.oracle.apm.agent.tracer.propagation.type property, which can be found in the AgentConfig.properties file of the agent's config directory.

You can utilize the following propagation types by setting the property to the name:

Set the appropriate propagation type in order to have your various tracers being able to work together to form a complete trace.