added context propagation documentation and examples

Author: martinkuba

plugins/node/opentelemetry-instrumentation-aws-lambda/README.md

@@ -85,11 +85,23 @@ The `lambdaHandler` should be specified as a string in the format `<file>.<handl
 
 One way to determine if the `lambdaHandler` option should be used is to check the handler defined on your Lambda. This can be done by determining the value of the `_HANDLER` environment variable or by viewing the **Runtime Settings** of your Lambda in AWS Console. If the handler is what you expect, then the instrumentation should work without the `lambdaHandler` option. If the handler points to something else, then the `lambdaHandler` option should be used to explicitly specify the handler that should be instrumented.
 
-### Active Tracing Context Propagation
+### Context Propagation
 
-AWS Active Tracing can provide a parent context for the span generated by this instrumentation. In order to use this context, please use the [xray-lambda](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/propagator-aws-xray-lambda) propagator.
+AWS Active Tracing can provide a parent context for the span generated by this instrumentation. Note that the span generated by Active Tracing is always reported only to AWS X-Ray. Therefore, if the OpenTelemetry SDK is configured to export traces to a backend other than AWS X-Ray, this will result in a broken trace.
 
-Example usage:
+If you use version `<=0.45.0` of this package, then the Active Tracing context is used as the parent context by default if present. In this case, in order to prevent broken traces, set the `disableAwsContextPropagation` option to `false`.
+Additional propagators can be added in the TracerProvider configuration.
+
+If you use version `>0.45.0`, the Active Tracing context is no longer used by default. In order to enable it, include the [AWSXRayLambdaPropagator](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/propagator-aws-xray-lambda) propagator in the list of propagators provided to the TracerProvider via its configuration, or by including `xray-lambda` in the OTEL_PROPAGATORS environment variable (see the example below on using the env variable).
+
+Note that there are two AWS-related propagators: [AWSXRayPropagator](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/propagators/propagator-aws-xray) and [AWSXRayLambdaPropagator](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/propagators/propagator-aws-xray-lambda). Here is a guideline for when to use one or the other:
+
+- If you export traces to AWS X-Ray, then use the `AWSXRayLambdaPropagator` or the `xray-lambda` value in the OTEL_PROPAGATORS environment variable. This will handle the active tracing lambda context as well as X-Ray HTTP headers.
+- If you export traces to a backend other than AWS X-Ray, then use the `AWSXrayPropagator` or `xray` in the environment variable. This propagator only handles the X-Ray HTTP headers.
+
+Examples:
+
+1. Active Tracing is enabled and the OpenTelemetry SDK is configured to export traces to AWS X-Ray. In this case, configure the SDK to use the `AWSXRayLambdaPropagator`.
 
 ```js
 const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
@@ -101,7 +113,7 @@ provider.register({
 });
 ```
 
-Alternatively, you can use the [auto-configuration-propagators](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-configuration-propagators/README.md) package, which makes it possible to configure propagators via the `OTEL_PROPAGATORS` environment variable. In order to use the `AWSXRayLambdaPropagator`, set the env variable value to `xray-lambda`.
+Alternatively, use the `getPropagators()` function from the [auto-configuration-propagators](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-configuration-propagators/README.md) package, and set the OTEL_PROPAGATORS environment variable to `xray-lambda`.
 
 ```js
 const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
@@ -113,6 +125,22 @@ provider.register({
 });
 ```
 
+2. The OpenTelemetry SDK is configured to export traces to a backend other than AWX X-Ray, but the lambda function is invoked by other AWS services which send the context using the X-Ray HTTP headers. In this case, include the `AWSXRayPropagator`, which extracts context from the HTTP header but not the Lambda Active Tracing context.
+
+```js
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { AWSXRayLambdaPropagator } = require('@opentelemetry/propagator-aws-xray-lambda');
+
+const provider = new NodeTracerProvider();
+provider.register({
+  propagator: new AWSXRayPropagator()
+});
+```
+
+Alternatively, use the `auto-configuration-package` as in example #1 and set the OTEL_PROPAGATORS environment variable to `xray`.
+
+For additional information, see the semantic conventions for lambda.
+
 ## Semantic Conventions
 
 This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)