Skip to content

Commit

Permalink
updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
martinkuba committed Mar 18, 2024
1 parent fea325d commit 08e0383
Showing 1 changed file with 6 additions and 51 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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+<br/>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

Expand Down

0 comments on commit 08e0383

Please sign in to comment.