Use case description

This feature automatically instruments your AWS Lambda functions with OpenTelemetry from a single line of Serverless Framework config. No code changes required.

Proposed solution

Minimal setup

stages:
  default:
    otel: true

This enables:

• Auto-instrumentation via the runtime wrapper
• Active tracing (X-Ray by default)
• OTel resource attributes for consistent labeling
• The SDK exporting to the local Collector extension

Uses the AWS Distro for OpenTelemetry (ADOT) managed layer and an embedded Collector (Lambda extension); the OTel SDK exports to this local Collector with sensible defaults.

Customize as needed

You can enable instrumentation per stage, or override names, sampling, propagators, resource attributes and provide custom collector config.

stages:
  default:                                               # Stage-level switch so you can enable/disable OTel by environment
    otel: false
  prod:
    otel:
      serviceName: My-Service                            # -> maps to OTEL_SERVICE_NAME. Overrides default (service property).
      traces:
        sampler:
          type: traceidratio
          arg: 0.5
      propagators: xray,tracecontext,baggage             # -> maps to OTEL_PROPAGATORS
      resourceAttributes:                                # -> joined as OTEL_RESOURCE_ATTRIBUTES (key=value,comma-separated)
        namespace: My-App                                # -> OTel 'service.namespace'
        version: ${env:VERSION, 'unknown'}               # -> OTel 'service.version'
      collectorConfig: collector.yml                     # -> maps to OPENTELEMETRY_COLLECTOR_CONFIG_URI 

What gets set automatically

1) Function environment variables

# Auto-instrument runtime wrapper (per runtime)
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler           # Node.js
# AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument      # Python
# Identity & resources
OTEL_SERVICE_NAME=${self:service}
OTEL_RESOURCE_ATTRIBUTES=service.namespace=${self:app},deployment.environment=${sls:stage},service.version=${env:GIT_SHA,'unknown'},cloud.provider=aws,cloud.platform=aws_lambda,cloud.region=${AWS::Region},cloud.account.id=${AWS::AccountId}
# Propagation
OTEL_PROPAGATORS=xray,tracecontext,baggage
# Collector config file (if a custom collector config file is provided)
OPENTELEMETRY_COLLECTOR_CONFIG_URI=/var/task/collector.yml

Key → OTel attribute mapping

• Service → service.name (via OTEL_SERVICE_NAME)
• Application → service.namespace (from self:app if set)
• Environment → deployment.environment
• cloud.region → AWS region
• cloud.account.id → AWS account ID
• cloud.provider → aws
• cloud.platform → aws_lambda
• service.version → Git commit SHA

2) Lambda layer

aws-otel-<runtime>-<amd64|arm64>-ver-1-32-0

The plugin resolves the exact ARN per region, architecture, and runtime (with an option to pin or override the version).

3) Lambda tracing (when using the zero-config defaults)

tracing:
  lambda: true

(Enables X-Ray context propagation.)

4) IAM for X-Ray (when using the zero-config defaults)

role:
  statements:
    - Effect: Allow
      Action:
        - xray:PutTraceSegments
        - xray:PutTelemetryRecords
      Resource: "*"

5) Stage-aware sampling defaults

prod

traces:
  sampler:
    type: parentbased_traceidratio
    arg: 0.1

non-prod

traces:
  sampler:
    type: parentbased_traceidratio
    arg: 1

6) Collector config packaging

If you include collector.yml in your service, it is automatically packaged. You can also use s3:// or https:// URIs via collectorConfig.

Example collector.yml (fan-out: X-Ray + custom OTLP backend):

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
      grpc:
        endpoint: 127.0.0.1:4317
processors:
  batch: {}
exporters:
  awsxray: {}
  otlphttp:
    endpoint: ${env:OTLP_BACKEND_ENDPOINT}
    headers:
      Authorization: Bearer ${env:OTLP_TOKEN}
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [awsxray, otlphttp]