AWS Lambda

The wrapper records one trailbeam receive per SQS record before your handler runs, and one trailbeam outcome per record after it returns or throws. Lambda's event source mapping makes the ReceiveMessage and DeleteMessage calls, so the wrapper cannot see them; Trailbeam infers what it can.

Install#

The wrapper ships in the same packages as the client hooks. Bundle them into your deployment package:

• Python: pip install ./trailbeam/python -t build/ into your deployment package directory. See Python.
• Node.js 20+: npm install ./trailbeam/node. See Node.js.

Set these on the function:

TRAILBEAM_RECEIPT_HASH_KEY=<the key every service on the queue uses>
TRAILBEAM_OTLP_TRACES_ENDPOINT=https://trailbeam-collector.internal:4318/v1/traces
OTEL_SERVICE_NAME=orders-lambda

The endpoint must be reachable from the function's network.

Wrap the handler#

Python#

import trailbeam.aws_lambda

@trailbeam.aws_lambda.wrap
def handler(event, context):
    failures = []
    for record in event["Records"]:
        try:
            process(record["body"])
        except Exception:
            failures.append({"itemIdentifier": record["messageId"]})
    return {"batchItemFailures": failures}

With options: @trailbeam.aws_lambda.wrap(receipt_hash_key=..., report_batch_item_failures=False).

Node.js#

const trailbeam = require('@trailbeam/sdk');

exports.handler = trailbeam.wrapHandler(async (event, context) => {
  const batchItemFailures = [];
  for (const record of event.Records) {
    try {
      await processBody(record.body);
    } catch {
      batchItemFailures.push({ itemIdentifier: record.messageId });
    }
  }
  return { batchItemFailures };
}, { reportBatchItemFailures: true });

Async, sync and callback-style (event, context, callback) handlers are accepted. The wrapper is always an async handler with two declared parameters, so the runtime treats it as async.

The wrapper creates its tracer provider when the module loads (once per execution environment), not per invocation.

Options#

The wrapped function exposes its provider as trailbeam_tracer_provider (Python) or trailbeamTracerProvider (Node.js).

What each invocation records#

1. The wrapper picks the records with eventSource = aws:sqs and a non-empty messageId. An event with none (API Gateway, a test event) goes to your handler untouched, with no spans.
2. It emits one trailbeam receive per record and flushes before calling your handler, so a timeout or out-of-memory kill cannot lose it.
3. It calls your handler.
4. It emits one trailbeam outcome per record and flushes again.

Each flush waits at most the flush timeout, so the wrapper adds up to two flush timeouts to an invocation when the endpoint is slow. A flush that fails never fails the invocation.

The trailbeam receive span#

The receive time is an upper bound: the real receive happened no later than the handler start. Whether Lambda records ever carry DeadLetterQueueSourceArn is not verified; the wrapper copies it if present.

The trailbeam outcome span#

One per record, zero-length, with trailbeam.order.issued = trailbeam.order.returned (one tick after the handler). Same faas.* attributes as the receive.

In Python only Exception is caught. SystemExit and KeyboardInterrupt pass through with no outcome, the same as a kill.

How Trailbeam reads it#

Trailbeam matches an outcome to its receive by faas.invocation_id.

• After a success outcome it adds an inferred step Deleted by Lambda, and the message state is deleted_inferred. The real delete is not observed.
• A Lambda receive with no outcome is processing while it is the latest receive and younger than --lambda-timeout (default 900 s, the Lambda maximum). After that, Trailbeam adds Lambda invocation ended without an outcome with a window of receive time to receive time plus the timeout.

A record whose first invocation timed out and was redelivered:

Client hooks inside a Lambda#

If your handler also calls SQS through an instrumented client (trailbeam.boto.install() or trailbeam.instrument(...)), those spans use a separate provider that the wrapper does not flush. Flush it before returning: in Node.js await trailbeam.forceFlush(); in Python call .force_flush() on the provider install() returned.

Verify it works#

Invoke the function with a sample SQS event that has a messageId, then:

curl -s http://127.0.0.1:4318/api/messages/<messageId>

Look for a received event with "consumer": {"source": "lambda", "faas_name": ..., "faas_invocation_id": ...} and a lambda_outcome event with outcome. In tests, pass span_processor=SimpleSpanProcessor(InMemorySpanExporter()) (Python) or spanProcessor (Node.js).

Common errors#

Related#

• Debug Lambda timeouts and crashes
• Recorded and inferred steps
• Run Trailbeam
• Span contract: Trailbeam outcome