Skip to content

feat(examples): add expressjs-otel-zip with ADOT tracing - #929

Open
bnusunny wants to merge 2 commits into
mainfrom
feat/examples-expressjs-otel-zip
Open

bnusunny wants to merge 2 commits into
mainfrom
feat/examples-expressjs-otel-zip

Conversation

@bnusunny

Copy link
Copy Markdown
Contributor

Refs #568

In #568 we promised a runnable example of tracing a Lambda Web Adapter app with AWS Distro for OpenTelemetry. This adds examples/expressjs-otel-zip, based on expressjs-zip.

The adapter keeps the exec wrapper: a function gets one AWS_LAMBDA_EXEC_WRAPPER, and it must stay /opt/bootstrap. So OpenTelemetry is loaded from run.sh instead:

export NODE_OPTIONS="--require @aws/aws-distro-opentelemetry-node-autoinstrumentation/register"
export OTEL_SERVICE_NAME=expressjs-otel
export OTEL_METRICS_EXPORTER=${OTEL_METRICS_EXPORTER:-none}
export OTEL_LOGS_EXPORTER=${OTEL_LOGS_EXPORTER:-none}
exec node app.js
  • No ADOT layer is needed. The ADOT package ships in node_modules (no bundler, because it patches http/express when they are required). Inside Lambda it sends traces over UDP straight to the function's X-Ray endpoint. The ADOT Lambda layer only adds an /opt/otel-instrument exec wrapper, which can't run next to the adapter's, so the example attaches just the adapter layer. The layer used in the original LWA + OpenTelemetry collector + zip Lambda deployment - is it possible? #568 thread is the legacy collector layer, which is now deprecated.
  • Metrics and logs exporters are off because nothing in Lambda receives them over OTLP.
  • Tracing: Active; SAM adds AWSXrayWriteOnlyAccess.
  • Registered in .github/dependabot.yml, the README examples list and the docs overview. It isn't in the CI boot matrix.

Testing: sam validate --lint passes for all 47 templates and check-example-config.sh passes. npm ci and node --check pass. A local run (bound to 127.0.0.1, Lambda-like environment, a UDP listener in place of the X-Ray endpoint) returns Hi there!, and the exported trace has GET / plus express middleware and request handler - / spans under service.name=expressjs-otel. It hasn't been deployed to Lambda yet.

Known: npm audit reports 13 advisories (4 high, 9 moderate), all transitive through ADOT 0.13.0, the current release. The Dependabot entry will pick up the fix when ADOT releases it.

A runnable Express.js zip example that traces through AWS Distro for
OpenTelemetry while keeping the adapter's /opt/bootstrap exec wrapper,
as promised in #568.

- run.sh loads @aws/aws-distro-opentelemetry-node-autoinstrumentation
  through NODE_OPTIONS (shipped in node_modules, no bundler) and sets
  OTEL_SERVICE_NAME. Metrics and logs exporters default to none: in
  Lambda the SDK exports traces over UDP to the X-Ray endpoint and there
  is no OTLP collector for the other signals.
- template.yaml attaches the adapter layer and the ADOT Node.js layer
  (AdotLayerArn parameter: account and version differ by Region), with
  Tracing: Active (SAM adds AWSXrayWriteOnlyAccess).
- Registered in .github/dependabot.yml, README.md and the docs examples
  overview.

Refs #568
The ADOT package ships in node_modules and, inside Lambda, exports
traces over UDP straight to the function's X-Ray endpoint. Nothing
loads the AWSOpenTelemetryDistroJs layer: its only entry point is the
/opt/otel-instrument exec wrapper, and that slot belongs to the
adapter's /opt/bootstrap. Remove the layer and the region-specific
AdotLayerArn parameter, and say in the README that no ADOT layer is
needed. The metrics/logs exporter defaults stay.

Refs #568
@bnusunny
bnusunny requested a review from a team as a code owner November 13, 2026 19:51

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant