diff --git a/experimental/packages/opentelemetry-propagator-aws-xray-lambda/README.md b/experimental/packages/opentelemetry-propagator-aws-xray-lambda/README.md index 551834ed1fb..61ded20a56e 100644 --- a/experimental/packages/opentelemetry-propagator-aws-xray-lambda/README.md +++ b/experimental/packages/opentelemetry-propagator-aws-xray-lambda/README.md @@ -3,63 +3,18 @@ [![NPM Published Version][npm-img]][npm-url] [![Apache License][license-image]][license-image] -The OpenTelemetry Propagator for AWS X-Ray Lambda 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. - -## Status - -| Maturity | [Component Owner](../../.github/component_owners.yml) | Compatibility | -| ----------------------------------------- | ----------------------------------------------------- | --------------------- | -| [Stable](../../../CONTRIBUTING.md#stable) | @carolabadeer | API 1.0+
SDK 1.0+ | - -## Installation - -```sh -npm install --save @opentelemetry/propagator-aws-xray-lambda -``` +The OpenTelemetry Propagator for AWS X-Ray Lambda provides propagation based on the X-Ray `_X_AMZN_TRACE_ID` environment +variable in addition to the AWS X-Ray HTTP headers. This propagator should be used only for an AWS Lambda instrumentation. ## Usage -In the [global tracer configuration file](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/#setup), configure the following: - -```js -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() -}); -``` +The preferred method for using this propagator is by using the `OTEL_PROPAGATORS` environment variable. For more details, +see the [semantic conventions specification for AWS Lambda](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/faas/aws-lambda.md). ## 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](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext), with some small format changes. -For additional reading, see the [AWS X-Ray Trace ID](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids) public documentation. - -### Parent - The ID of the AWS X-Ray Segment - -* 64-bit random number in base16 format. Populated from the [OpenTelemetry Span ID](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext). - -### 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](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext). +The propagator extracts context from the `_X_AMZN_TRACE_ID` environment variable, except when there is already another +context active. It also automatically uses the [AWS X-Ray propagator](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/propagators/opentelemetry-propagator-aws-xray). ## Useful links