Tracer

Distributed tracing backed by AWS X-Ray.

Fleet-wide + cost: tracing is presence-gated — constructing any Tracer in the app enables X-Ray Active mode on every compute (X-Ray is billed per trace recorded/retrieved). enabled: false on a Tracer only removes that Tracer's opt-in; if any other Tracer exists, X-Ray still turns on fleet-wide.

When to use: You need to trace request flow across services, debug latency issues, or visualize service dependencies. Good for identifying bottlenecks, understanding call chains, and correlating failures across Building Blocks.

When NOT to use: If you need structured log output, use Logging. If you need numeric measurements over time, use Metrics.

Design & mock parity details: DESIGN.md

Installation

npm install @aws-blocks/bb-tracer

Quick Usage

import { Tracer } from '@aws-blocks/bb-tracer';

const tracer = new Tracer(scope, 'my-tracer');

// Wrap an operation in a traced segment
const user = await tracer.startSegment('fetchUser', async (segment) => {
  segment.addAnnotation('userId', 'user-123');
  const result = await db.get('user-123');
  segment.setHttpStatus(200);
  return result;
});

// Add root-level annotations (attached to the Lambda facade segment)
tracer.addAnnotation('endpoint', '/api/users');

// Get the current trace ID for log correlation
const traceId = tracer.getTraceId();

API

const tracer = new Tracer(scope, id, options?)

Segment Methods

The segment object passed to startSegment's callback:

Options

Best Practices

• Use startSegment to wrap discrete units of work (DB calls, HTTP requests, business logic)
• Keep segment names short and descriptive (e.g., 'fetchUser', 'processPayment')
• Use annotations for values you want to filter/search by in the X-Ray console
• Use metadata for large or complex debugging data you don't need to search
• Keep annotation cardinality low (avoid user-specific values as annotation keys)
• Use AsyncJob for long-running work rather than tracing huge spans

Local Development

Mock data persists to disk at .bb-data/{fullId}/traces.json across dev server restarts. Nested segments are stored as a tree (children array). Wipe with rm -rf .bb-data.

The mock records all traces locally with full timing, annotations, metadata, and error data — matching the shape of what X-Ray would capture in production.

Sampling

• Local (mock): Controlled by the samplingRate option. A value of 0.1 means roughly 10% of local traces are recorded. Default is 1.0 (record everything).
• Production (AWS): Sampling is controlled by X-Ray sampling rules configured in the AWS console or via CDK. The samplingRate option is ignored in production — X-Ray's native sampling infrastructure takes precedence.

Pricing

• Free tier: 100,000 traces recorded per month, 1,000,000 traces scanned/retrieved per month
• Beyond free tier: $5.00 per million traces recorded, $0.50 per million traces retrieved or scanned
• Lambda daemon: No additional charge — the X-Ray daemon is built into the Lambda runtime
• Cost drivers: Number of traced invocations × sampling rate
• Cost optimization: Configure X-Ray sampling rules to keep recorded-trace volume (and cost) low for high-throughput functions (the samplingRate option only affects the local mock, not production)
• Disabled (enabled: false): Zero X-Ray cost — no traces are recorded or sent

See Also

• Types — Shared type definitions (Segment, TracerOptions, AnnotationValue)