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();
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
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
License
Apache 2.0 - See LICENSE for more information.