Node.js (AWS SDK v3)

Install#

The package is @trailbeam/sdk (version 0.1.0-dev.0). It is marked "private": true and not on npm. Install it from a clone of the repository, which is private for now:

gh repo clone nick-lennox/trailbeam
npm install ./trailbeam/node   # run from your application's directory

Or run npm pack ./trailbeam/node and install the tarball. It is plain CommonJS with type declarations (index.d.ts); there is no build step.

Requirements: Node.js 20 or later, and @aws-sdk/client-sqs in your app. Runtime dependencies: @opentelemetry/api ~1.9.0, @opentelemetry/exporter-trace-otlp-proto ^0.223.2, @opentelemetry/resources and @opentelemetry/sdk-trace-base ^2.12.1.

Add the hooks#

Instrument every SQSClient you create. install() is optional; instrument() installs with defaults on first use.

const { SQSClient, SendMessageCommand, ReceiveMessageCommand, DeleteMessageCommand } = require('@aws-sdk/client-sqs');
const trailbeam = require('@trailbeam/sdk');

trailbeam.install({ receiptHashKey: process.env.TRAILBEAM_RECEIPT_HASH_KEY }); // optional
const sqs = trailbeam.instrument(new SQSClient({}));
const QueueUrl = process.env.QUEUE_URL;

await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: 'hello' }));
const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({ QueueUrl, WaitTimeSeconds: 5 }));
for (const m of Messages) {
  await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: m.ReceiptHandle }));
}

TypeScript:

import { SQSClient } from '@aws-sdk/client-sqs';
import * as trailbeam from '@trailbeam/sdk';

const sqs = trailbeam.instrument(new SQSClient({}));

For Lambda handlers use the wrapper instead. See AWS Lambda.

How the hooks attach#

instrument(client) adds one middleware, named trailbeamSqsMiddleware, to the client's middleware stack in the initialize step with priority: 'high' and override: true. Calling instrument twice on the same client is safe. A value without middlewareStack.add throws TypeError: trailbeam.instrument expects an AWS SDK v3 SQSClient.

The middleware looks up the current hooks on every call. After uninstall(), every instrumented client passes calls straight through.

• Trailbeam uses its own BasicTracerProvider with AlwaysOnSampler and a BatchSpanProcessor. It does not register anything globally, and your sampling never drops Trailbeam spans.
• Each Trailbeam span is a child of the active span. With @opentelemetry/instrumentation-aws-sdk that is the stock span for the same call, so both share a trace ID.
• Parent spans are only found if the app has an OpenTelemetry context manager. Any NodeSDK setup registers one.
• The hooks never change the result or error your code sees. Errors inside a hook go to diag.debug.

Options#

install(options)#

Returns the Trailbeam BasicTracerProvider. Calling it again replaces the previous installation and shuts its provider down.

Other exports#

Environment variables#

Warnings are emitted with process.emitWarning and code TRAILBEAM, once per process.

What it records#

A send that throws gets no span. A settle command that throws still gets one failed span per receipt handle, and the error is rethrown. Missing system attributes are omitted, never sent as empty strings or -1. Other SQS commands produce no Trailbeam span.

Common attributes on every span: trailbeam.schema_version = 3, trailbeam.kind, trailbeam.source = client, messaging.system.name = aws.sqs, messaging.operation.type, messaging.operation.name, messaging.client.id, process.pid, messaging.destination.name and aws.sqs.queue.url. Node.js spans have no thread.name.

Receive request attributes#

The middleware asks ReceiveMessage for ApproximateReceiveCount, SentTimestamp, ApproximateFirstReceiveTimestamp, AWSTraceHeader and DeadLetterQueueSourceArn. It works on a copy of your input; your object is never modified. If you ask for All, nothing is added. If you use only the deprecated AttributeNames, the names go there. Message attributes are never requested.

Settle error codes#

Handle map, timing and order#

• Handle map: receipt handle to message ID, at most 100,000 entries, 12-hour expiry, entry dropped after a successful delete. A failed delete keeps the entry.
• Timing: the span starts when the middleware runs (before serialization, signing and retries, so it is a lower bound) and ends when the response or error arrives. Times come from Date.now(), in milliseconds, rounded down.
• Order: trailbeam.order.issued and trailbeam.order.returned are ticks of one counter per realm, shared by every instrumented client and every async task in it. trailbeam.order.scope names it. Each worker_thread is its own realm, with its own scope. See Ordering.

Short-lived processes#

Spans are exported in batches. Spans still waiting in the batch processor when the process exits are lost, so before a script exits:

await trailbeam.forceFlush();   // or: await trailbeam.uninstall();

Verify it works#

In a test, export to memory:

const { InMemorySpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const exporter = new InMemorySpanExporter();
trailbeam.install({ receiptHashKey: 'test-key-at-least-16-bytes', spanProcessor: new SimpleSpanProcessor(exporter) });
const sqs = trailbeam.instrument(new SQSClient({}));
// ... send, receive, delete ...
console.log(exporter.getFinishedSpans().map((s) => s.name));
// [ 'trailbeam send', 'trailbeam receive', 'trailbeam delete' ]

With Trailbeam running:

curl -s http://127.0.0.1:4318/api/health
curl -s http://127.0.0.1:4318/api/messages/<message-id>

A healthy flow, with a Python producer and a Node.js consumer on the same key:

Common errors#

Related#

• Python (boto3)
• AWS Lambda
• Run Trailbeam
• Receipt-handle hashing
• Span contract