Add documentation.

Author: phipag

aws_lambda_powertools/tracing/otel/tracer.py

@@ -46,7 +46,7 @@ class TracerOpenTelemetry:
     ----------
     mode : Literal["auto", "manual"]
         Instrumentation mode. "auto" uses global TracerProvider from OTel SDK (e.g., ADOT).
-        "manual" uses provided TracerProvider or creates vanilla one.
+        "manual" uses provided TracerProvider or creates default one.
     service : str, optional
         Service name for spans. Falls back to POWERTOOLS_SERVICE_NAME or Lambda function name.
     tracer_provider : TracerProvider, optional
@@ -117,11 +117,11 @@ def _resolve_tracer_provider(self, tracer_provider: SDKTracerProvider | None) ->
                 raise ValueError("tracer_provider cannot be provided in auto mode")
             return None  # Will use global provider
 
-        # Manual mode: use provided or create vanilla
+        # Manual mode: use provided or create default
         if tracer_provider is not None:
             return tracer_provider
 
-        # Create vanilla TracerProvider
+        # Create default TracerProvider
         from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
 
         return SDKTracerProvider()

docs/core/tracer-otel.md

@@ -0,0 +1,187 @@
+---
+title: Tracer (OpenTelemetry)
+description: Core utility
+---
+
+TracerOpenTelemetry is an OpenTelemetry-native tracer for AWS Lambda, providing distributed tracing with the [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/python/){target="_blank" rel="nofollow"}.
+
+## Key features
+
+* Two modes: **auto** (ADOT Layer) and **manual** (custom TracerProvider)
+* Auto capture cold start as span attribute
+* Auto-disable when `POWERTOOLS_TRACE_DISABLED` is set
+* Support tracing async methods, generators, and context managers
+* SQS context propagation helpers
+
+## Getting started
+
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/examples){target="_blank"}.
+
+### Install
+
+!!! info "This is not necessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../index.md#lambda-layer){target="_blank"}"
+
+Add `aws-lambda-powertools[otel]` as a dependency in your preferred tool: _e.g._, _requirements.txt_, _pyproject.toml_. This will ensure you have the required dependencies before using TracerOpenTelemetry.
+
+### Auto mode (ADOT Layer)
+
+Use **auto mode** when deploying with the [AWS Distro for OpenTelemetry (ADOT) Lambda Layer](https://aws-otel.github.io/docs/getting-started/lambda){target="_blank" rel="nofollow"}. The ADOT Layer configures a global TracerProvider that exports spans automatically.
+
+```python hl_lines="1 3 7" title="Auto mode with ADOT Layer"
+--8<-- "examples/tracer_otel/src/getting_started_auto_mode.py"
+```
+
+`capture_lambda_handler` performs these additional tasks to ease operations:
+
+* Adds a `faas.coldstart` attribute to easily filter traces that have had an initialization overhead
+* Adds a `service.name` attribute if `service` parameter or `POWERTOOLS_SERVICE_NAME` is set
+* Captures any response, or full exceptions generated by the handler, and includes as span attributes
+
+### Manual mode
+
+Use **manual mode** when you want full control over the TracerProvider configuration, or when not using the ADOT Layer.
+
+```python hl_lines="1-3 8-9 11" title="Manual mode with custom TracerProvider"
+--8<-- "examples/tracer_otel/src/getting_started_manual_mode.py"
+```
+
+If you don't provide a `tracer_provider`, a default TracerProvider is created that respects OpenTelemetry SDK environment variables.
+
+### Synchronous functions
+
+You can trace synchronous functions using the `capture_method` decorator.
+
+```python hl_lines="7-8 12" title="Tracing an arbitrary function with capture_method"
+--8<-- "examples/tracer_otel/src/capture_method.py"
+```
+
+### Asynchronous functions
+
+You can trace asynchronous functions using `capture_method`.
+
+```python hl_lines="8-10" title="Tracing async functions"
+--8<-- "examples/tracer_otel/src/capture_method_async.py"
+```
+
+### Creating custom spans
+
+Use `add_span` context manager to create child spans with custom attributes:
+
+```python hl_lines="8-11" title="Creating custom spans with add_span"
+--8<-- "examples/tracer_otel/src/add_span.py"
+```
+
+### Environment variables
+
+The following environment variables are available to configure TracerOpenTelemetry at a global scope:
+
+| Setting               | Description                                      | Environment variable                 | Default       |
+|-----------------------|--------------------------------------------------|--------------------------------------|---------------|
+| **Disable Tracing**   | Explicitly disables all tracing.                 | `POWERTOOLS_TRACE_DISABLED`          | `false`       |
+| **Service Name**      | Sets the service name for spans.                 | `POWERTOOLS_SERVICE_NAME`            | Function name |
+| **Response Capture**  | Captures Lambda or method return as attribute.   | `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | `true`        |
+| **Exception Capture** | Records exceptions in spans.                     | `POWERTOOLS_TRACER_CAPTURE_ERROR`    | `true`        |
+
+## Advanced
+
+### Disabling response auto-capture
+
+Use **`capture_response=False`** parameter in both `capture_lambda_handler` and `capture_method` decorators to instruct Tracer **not** to serialize function responses as span attributes.
+
+???+ info "Info: This is useful in two common scenarios"
+    1. You might **return sensitive** information you don't want it to be added to your traces
+    2. You might return **more than 1KB** of data which exceeds span attribute limits
+
+```python hl_lines="6" title="Disabling response capture"
+--8<-- "examples/tracer_otel/src/disable_capture_response.py"
+```
+
+### SQS context propagation
+
+Propagate trace context through SQS messages to maintain distributed traces across services. This requires two separate Lambda functions: a **producer** that sends messages and a **consumer** that processes them.
+
+The producer injects trace context into the message payload before sending to SQS. The consumer extracts this context to continue the same trace, linking both functions in your distributed trace.
+
+=== "Producer Handler"
+
+    ```python hl_lines="4 15-16" title="Inject trace context before sending to SQS"
+    --8<-- "examples/tracer_otel/src/sqs_propagation_producer.py"
+    ```
+
+=== "Consumer Handler"
+
+    ```python hl_lines="4 16" title="Extract trace context from SQS message"
+    --8<-- "examples/tracer_otel/src/sqs_propagation_consumer.py"
+    ```
+
+### Cold start detection
+
+TracerOpenTelemetry automatically adds a `faas.coldstart` attribute to the handler span:
+
+* `true` on the first invocation after a cold start
+* `false` on subsequent warm invocations
+
+### Accessing the current span
+
+You can use `get_current_span` method to access the current active span and add custom attributes.
+
+```python
+span = tracer.get_current_span()
+if span:
+    span.set_attribute("custom_key", "custom_value")
+```
+
+## Testing your code
+
+TracerOpenTelemetry is disabled by default when `POWERTOOLS_TRACE_DISABLED` environment variable is set to `true`. This means you can disable tracing during tests without code changes.
+
+## Comparison with X-Ray Tracer
+
+| Feature | Tracer (X-Ray) | TracerOpenTelemetry |
+|---------|---------------|---------------------|
+| Backend | AWS X-Ray | Any OTel-compatible backend |
+| SDK | AWS X-Ray SDK | OpenTelemetry SDK |
+| Auto-patching | Yes (boto3, requests, etc.) | Via OTel instrumentation packages |
+| Annotations | `put_annotation()` | `span.set_attribute()` |
+| Metadata | `put_metadata()` | `span.set_attribute()` |
+| Cold start | Annotation | Span attribute |
+| Context propagation | X-Ray header | W3C Trace Context |
+
+## API Reference
+
+### TracerOpenTelemetry
+
+```python
+TracerOpenTelemetry(
+    mode: Literal["auto", "manual"] = "manual",
+    service: str | None = None,
+    tracer_provider: TracerProvider | None = None,
+    disabled: bool | None = None,
+)
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `mode` | `"auto"` or `"manual"` | Instrumentation mode |
+| `service` | `str` | Service name for spans |
+| `tracer_provider` | `TracerProvider` | Custom provider (manual mode only) |
+| `disabled` | `bool` | Disable tracing |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `capture_lambda_handler` | Decorator for Lambda handlers |
+| `capture_method` | Decorator for methods |
+| `add_span(name)` | Context manager for custom spans |
+| `get_current_span()` | Get the current active span |
+
+### Context propagation
+
+| Function | Description |
+|----------|-------------|
+| `inject_trace_context(carrier)` | Inject trace context into a dict |
+| `create_span_from_context(name, carrier)` | Create span from extracted context |

examples/tracer_otel/src/add_span.py

@@ -0,0 +1,14 @@
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    with tracer.add_span("process_order") as span:
+        span.set_attribute("order_id", event.get("order_id", "unknown"))
+        span.set_attribute("customer_tier", "premium")
+        # Process order logic here
+        result = {"order_id": event.get("order_id"), "status": "completed"}
+
+    return {"statusCode": 200, "body": result}

examples/tracer_otel/src/capture_method.py

@@ -0,0 +1,14 @@
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_method
+def process_payment(payment_id: str) -> dict:
+    return {"payment_id": payment_id, "status": "processed"}
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    result = process_payment(event.get("payment_id", "123"))
+    return {"statusCode": 200, "body": result}

examples/tracer_otel/src/capture_method_async.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_method
+async def async_get_user(user_id: str) -> dict:
+    await asyncio.sleep(0.1)  # Simulate async I/O
+    return {"user_id": user_id, "name": "John Doe"}
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    user = asyncio.run(async_get_user(event.get("user_id", "123")))
+    return {"statusCode": 200, "body": user}

examples/tracer_otel/src/disable_capture_response.py

@@ -0,0 +1,9 @@
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_lambda_handler(capture_response=False)
+def lambda_handler(event, context):
+    # Response won't be captured in span attributes
+    return {"statusCode": 200, "body": "sensitive data"}

examples/tracer_otel/src/getting_started_auto_mode.py

@@ -0,0 +1,8 @@
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return {"statusCode": 200, "body": "Hello, World!"}

examples/tracer_otel/src/getting_started_manual_mode.py

@@ -0,0 +1,16 @@
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+
+# Configure custom TracerProvider with OTLP exporter
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+
+tracer = TracerOpenTelemetry(mode="manual", tracer_provider=provider, service="my-service")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return {"statusCode": 200, "body": "Hello, World!"}

examples/tracer_otel/src/sqs_propagation_consumer.py

@@ -0,0 +1,20 @@
+import json
+
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+from aws_lambda_powertools.tracing.otel.propagation import create_span_from_context
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    """Consumer: Extract trace context from SQS message."""
+    for record in event.get("Records", []):
+        message = json.loads(record["body"])
+
+        # Continue the trace from the producer
+        with create_span_from_context("process_order", message) as span:
+            span.set_attribute("order_id", message.get("order_id"))
+            # Process the order
+
+    return {"statusCode": 200}

examples/tracer_otel/src/sqs_propagation_producer.py

@@ -0,0 +1,19 @@
+import json
+
+from aws_lambda_powertools.tracing.otel import TracerOpenTelemetry
+from aws_lambda_powertools.tracing.otel.propagation import inject_trace_context
+
+tracer = TracerOpenTelemetry(mode="auto")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    """Producer: Inject trace context into SQS message."""
+    message = {"order_id": "12345", "amount": 99.99}
+
+    # Inject trace context for downstream consumers
+    message_with_context = inject_trace_context(message)
+
+    # Send to SQS with: sqs.send_message(QueueUrl=queue_url, MessageBody=json.dumps(message_with_context))
+
+    return {"statusCode": 200, "body": json.dumps(message_with_context)}