@opentelemetry/propagator-aws-xray

What is @opentelemetry/propagator-aws-xray?

@opentelemetry/propagator-aws-xray is an npm package that provides context propagation for AWS X-Ray within the OpenTelemetry framework. It allows you to propagate trace context in a format compatible with AWS X-Ray, enabling distributed tracing across services that use AWS X-Ray.

What are @opentelemetry/propagator-aws-xray's main functionalities?

AWS X-Ray Trace Context Propagation

This feature allows you to register the AWS X-Ray propagator with the OpenTelemetry Node.js TracerProvider. This enables the propagation of trace context in a format compatible with AWS X-Ray, facilitating distributed tracing across services.

const { NodeTracerProvider } = require('@opentelemetry/node');
const { AwsXRayPropagator } = require('@opentelemetry/propagator-aws-xray');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register({
  propagator: new AwsXRayPropagator(),
});

registerInstrumentations({
  tracerProvider: provider,
});

console.log('AWS X-Ray Propagator registered with OpenTelemetry');

Other packages similar to @opentelemetry/propagator-aws-xray

@opentelemetry/propagator-b3

@opentelemetry/propagator-b3 is an npm package that provides context propagation using the B3 format. B3 is a set of HTTP headers used for distributed tracing, originally created by Twitter. It is commonly used with Zipkin. This package is similar to @opentelemetry/propagator-aws-xray in that it provides a way to propagate trace context, but it uses the B3 format instead of the AWS X-Ray format.

@opentelemetry/propagator-jaeger

@opentelemetry/propagator-jaeger is an npm package that provides context propagation using the Jaeger format. Jaeger is an open-source, end-to-end distributed tracing tool. This package is similar to @opentelemetry/propagator-aws-xray in that it provides a way to propagate trace context, but it uses the Jaeger format instead of the AWS X-Ray format.

@opentelemetry/propagator-ot-trace

@opentelemetry/propagator-ot-trace is an npm package that provides context propagation using the OpenTracing format. OpenTracing is a set of consistent, expressive, vendor-neutral APIs for distributed tracing. This package is similar to @opentelemetry/propagator-aws-xray in that it provides a way to propagate trace context, but it uses the OpenTracing format instead of the AWS X-Ray format.

README

OpenTelemetry Propagator AWS X-Ray

The OpenTelemetry Propagator for AWS X-Ray provides HTTP header propagation for systems that are using AWS X-Amzn-Trace-Id format. This propagator translates the OpenTelemetry SpanContext into the equivalent AWS header format, for use with the OpenTelemetry JS SDK. TraceState is currently not propagated.

This package was originally located in opentelemetry-js-contrib. It has been moved in order to make it a direct dependency of the Node SDK. As a result, versions from 1.4.0 to 1.22.0 have been skipped.

Installation

npm install --save @opentelemetry/propagator-aws-xray

Usage

In the global tracer configuration file, configure the following:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { AWSXRayPropagator } = require('@opentelemetry/propagator-aws-xray');
// ...

const provider = new NodeTracerProvider();

// Set the global trace context propagator to use X-Ray formatted trace header
provider.register({
  propagator: new AWSXRayPropagator()
});

Propagator Details

Example header:X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1

The header consists of three parts: the root trace ID, the parent ID and the sampling decision.

Root - The AWS X-Ray format trace ID

• Format: (spec-version)-(timestamp)-(UUID)
  • spec_version - The version of the AWS X-Ray header format. Currently, only "1" is valid.
  • timestamp - 32-bit number in base16 format, corresponds to the first 8 characters of the OpenTelemetry trace ID. Note, while X-Ray calls this timestamp, for the purpose of propagation it is opaque and any value will work.
  • UUID - 96-bit random number in base16 format, corresponds to the last 10 characters of the OpenTelemetry trace ID.

Root is analogous to the OpenTelemetry Trace ID, with some small format changes. For additional reading, see the AWS X-Ray Trace ID public documentation.

Parent - The ID of the AWS X-Ray Segment

• 64-bit random number in base16 format. Populated from the OpenTelemetry Span ID.

Sampled - The sampling decision

• Defined in the AWS X-Ray specification as a tri-state field, with "0", "1" and "?" as valid values. Only "0" and "1" are used in this propagator. If "?", a new trace will be started.
• Populated from the OpenTelemetry trace flags.

Useful links

• 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.