Configuration

The packages read their settings when install, instrument, wrap or wrapHandler creates the tracer provider; the Lambda wrappers read AWS_LAMBDA_LOG_STREAM_NAME on each invocation. Trailbeam reads its settings once, at start.

Environment variables read by both packages#

These apply to the client hooks and the Lambda wrappers, in Python and Node.js.

Python package (trailbeam)#

trailbeam.boto.install()#

import trailbeam.boto
provider = trailbeam.boto.install(receipt_hash_key=None, span_exporter=None, span_processor=None)

Returns the Trailbeam TracerProvider (always-on sampler, not registered globally). Calling install again replaces the previous installation. trailbeam.boto.uninstall() removes the hooks, flushes and shuts the provider down. If the application already called BotocoreInstrumentor().instrument(...), Trailbeam keeps that setup and its tracer provider, and runs the Trailbeam hooks first, then the application's. Otherwise it instruments botocore with the Trailbeam provider, so the stock botocore spans are exported to TRAILBEAM_OTLP_TRACES_ENDPOINT too; Trailbeam counts them as ignored.

trailbeam.aws_lambda.wrap#

@trailbeam.aws_lambda.wrap(receipt_hash_key=None, flush_timeout_millis=2000, report_batch_item_failures=True)
def handler(event, context): ...

The wrapped function has a trailbeam_tracer_provider attribute. Bare @trailbeam.aws_lambda.wrap uses every default.

Node.js package (@trailbeam/sdk)#

install(options) and instrument(client)#

const trailbeam = require('@trailbeam/sdk');
trailbeam.install({ receiptHashKey: process.env.TRAILBEAM_RECEIPT_HASH_KEY });
const sqs = trailbeam.instrument(new SQSClient({}));

install returns the Trailbeam BasicTracerProvider; calling it again replaces the installation and shuts the old provider down. All its options are optional. instrument adds the middleware trailbeamSqsMiddleware (step initialize, priority high) to one AWS SDK v3 client and returns the client. It calls install() with defaults if needed, is safe to call twice on the same client, and throws TypeError if the argument has no middleware stack. Every client you want recorded must be passed to instrument. forceFlush() flushes; uninstall() turns the middleware off on every client, flushes and shuts down. Both return a promise. The package also exports hashReceiptHandle(key, receiptHandle) and keyId(key), the two hash values of the span contract, plus version and SCHEMA_VERSION (3). Types are in node/index.d.ts.

wrapHandler(handler, options)#

The returned handler is always async (event, context) and has a trailbeamTracerProvider property. Async, sync and callback-style handlers are accepted. wrapHandler throws TypeError if handler is not a function.

Fixed values in the packages#

Not configurable in 0.1. Listed so you know the bounds.

Store (trailbeam-store)#

Each option has an environment variable. The command-line flag wins when both are set.

trailbeam-store --db /var/lib/trailbeam/trailbeam.sqlite --port 4319 \
  --lambda-timeout 60 --max-receive-count orders=5,payments=3

A malformed --max-receive-count stops Trailbeam at start with expected QUEUE=N with N from 1 to 1000, got '...'.

Container image#

The image in server/Dockerfile sets TRAILBEAM_STORE_DB=/data/trailbeam.sqlite, TRAILBEAM_STORE_HOST=0.0.0.0 and TRAILBEAM_STORE_PORT=4318, runs as UID 10001, declares the volume /data, and has a HEALTHCHECK on /api/health every 30 s. Set any option with -e:

docker run -d --name trailbeam -p 127.0.0.1:4318:4318 -v trailbeam-data:/data \
  -e TRAILBEAM_LAMBDA_TIMEOUT_S=60 -e TRAILBEAM_MAX_RECEIVE_COUNT=orders=5 trailbeam-store

Collector#

Environment variables used by collector/trailbeam-collector.yaml and collector/backend.yaml (otelcol-contrib required).

Fixed in the YAML (edit the file to change them):

Demo#

Related#

• HTTP API
• Span contract
• Set up Trailbeam, Set up the Collector, Lambda