OpenTelemetry Instana Propagator

component owners: @basti1302, @kirrg001

The OpenTelemetry Propagator for Instana provides HTTP header propagation for systems that are using IBM Observability by Instana. This propagator translates the Instana trace correlation headers (X-INSTANA-T/X-INSTANA-S/X-INSTANA-L) into the OpenTelemetry SpanContext, and vice versa. It does not handle TraceState.

This package is compatible with the OpenTelemetry JS API >= 1.0.0.

Installation

npm install --save @opentelemetry/propagator-instana

Usage

In the global tracer configuration file, configure the following:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
// ...

const provider = new NodeTracerProvider();

// Set the global trace context propagator to use X-INSTANA-T/-S/-L trace headers.
provider.register({
  propagator: new InstanaPropagator()
});

Propagator Details

There are three headers that the propagator handles: X-INSTANA-T (the trace ID), X-INSTANA-S (the parent span ID), and X-INSTANA-L (the sampling level).

Example header triplet:

• X-INSTANA-T: 80f198ee56343ba864fe8b2a57d3eff7,
• X-INSTANA-S: e457b5a2e4d86bd1,
• X-INSTANA-L: 1.

A short summary for each of the headers is provided below. More details are available at https://www.ibm.com/docs/en/obi/current?topic=monitoring-traces#tracing-headers.

X-INSTANA-T -- trace ID

• A string of either 16 or 32 characters from the alphabet 0-9a-f, representing either a 64 bit or 128 bit ID.
• This header corresponds to the OpenTelemetry TraceId.
• If the propagator receives an X-INSTANA-T header value that is shorter than 32 characters when extracting headers into the OpenTelemetry span context, it will left-pad the string with the character "0" to length 32.
• No length transformation is applied when injecting the span context into headers.

X-INSTANA-S -- parent span ID

• Format: A string of 16 characters from the alphabet 0-9a-f, representing a 64 bit ID.
• This header corresponds to the OpenTelemetry SpanId.

X-INSTANA-L - sampling level

• The only two valid values are 1 and 0.
• A level of 1 means that this request is to be sampled, a level of 0 means that the request should not be sampled.
• This header corresponds to the sampling bit of the OpenTelemetry TraceFlags.

Useful links

• For more information on Instana, visit https://www.instana.com/ and Instana' documentation.
• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.