Fix problem in xray-lambda propagator definition (#778)

Co-authored-by: Raphael Philipe Mendes da Silva <rapphil@gmail.com>
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>

.chloggen/778.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: bug_fix
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: aws-lambda
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Fix problem in `xray-lambda` propagator definition
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [778]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

docs/faas/aws-lambda.md

@@ -70,37 +70,49 @@ Users MUST be able to [configure the propagator](#xray-lambda-propagator-configu
 
 SDK's that have instrumentation for AWS Lambda SHOULD provide an additional propagator alongside the X-Ray propagator
 that can [be configured](#xray-lambda-propagator-configuration) via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`.
-This propagator ignores the provided carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable
-(and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set).
-
-To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified.
-
-Example pseudo implementation:
+This propagator is expected to replace the `xray` propagator in the `OTEL_PROPAGATORS` list. The behavior for this propagator is described in pseudo code below.
 
 ```
 extract(context, carrier) {
+    xrayContext = xrayPropagator.extract(context, carrier)
+
+    // To avoid potential issues when extracting with an active span context (such as with a span link),
+    // the `xray-lambda` propagator SHOULD check if the provided context already has an active span context.
+    // If found, the propagator SHOULD just return the extract result of the `xray` propagator.
     if (Span.fromContext(context).getSpanContext().isValid())
-      return context
+      return xrayContext
 
-    traceHeader = getEnvironment("_X_AMZN_TRACE_ID");
+    // If xray-lambda environment variable not set, return the xray extract result.
+    traceHeader = getEnvironment("_X_AMZN_TRACE_ID")
     if (isEmptyOrNull(traceHeader))
-      return context
+      return xrayContext
 
-    return xrayPropagator.extract(context, ["_X_AMZN_TRACE_ID": traceHeader])
+    // Apply the xray propagator using the span context contained in the xray-lambda environment variable.
+    return xrayPropagator.extract(xrayContext, ["X-Amzn-Trace-Id": traceHeader])
 }
 ```
 
+*Note:* Java implementations should use the system property value of the key `com.amazonaws.xray.traceHeader`
+instead of the environment variable if the system property is not empty.
+
 #### `xray-lambda` Propagator Configuration
 
-Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable:
+**When reporting spans to AWS X-Ray** from AWS Lambda, the `xray-lambda` propagator SHOULD replace the `xray` propagator in the `OTEL_PROPAGATORS` configuration. Including both will prevent `xray-lambda` from functioning properly.
+
+Example valid configuration when reporting spans to AWS X-Ray:
+
+- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda`
+
+Example invalid configurations:
 
-`OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda`
+- `OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda`
+- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda,xray`
 
-To avoid broken traces, if OpenTelemetry is reporting traces to another system besides AWS X-Ray, users should either omit `xray-lambda` or add it to the beginning:
+**When OpenTelemetry is reporting traces to another system besides AWS X-Ray**, users SHOULD NOT use `xray-lambda` or reported traces will be broken.
 
-`OTEL_PROPAGATORS=xray-lambda,tracecontext,baggage,xray`
+Example valid configuration when OpenTelemetry is reporting traces to another system besides AWS X-Ray:
 
-*Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.*
+- `OTEL_PROPAGATORS=tracecontext,baggage,xray`
 
 ## API Gateway