AWS X-Ray Tools

Small, focused utilities for guarded AWS X-Ray capture of AWS SDK v3 clients.

This package is intended to be imported by other aws-*-tools packages so they can offer consistent, optional X-Ray instrumentation without duplicating guarded-import logic.

Install

npm i @karmaniverous/aws-xray-tools
Copy

This package is ESM-only (Node >= 20).

Public API

import {
  captureAwsSdkV3Client,
  shouldEnableXray,
  type Logger,
  type XrayMode,
  type XrayState,
} from '@karmaniverous/aws-xray-tools';
Copy

Quick start (capture an AWS SDK v3 client)

import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
import { captureAwsSdkV3Client } from '@karmaniverous/aws-xray-tools';

const base = new SecretsManagerClient({ region: 'us-east-1' });

// Guarded: does nothing unless capture is enabled and daemon is configured.
const client = captureAwsSdkV3Client(base, {
  mode: 'auto',
  daemonAddress: process.env.AWS_XRAY_DAEMON_ADDRESS,
  logger: console,
});
Copy

Capture mode semantics

• mode: 'off': never capture.
• mode: 'auto' (default): capture only when AWS_XRAY_DAEMON_ADDRESS is set.
• mode: 'on': force capture (throws if daemon address is missing).

aws-xray-sdk (optional peer dependency)

This package loads aws-xray-sdk only when capture is enabled.

To enable capture in your app/package, install the optional peer dependency:

npm i aws-xray-sdk
Copy

If capture is enabled but aws-xray-sdk is not installed, captureAwsSdkV3Client throws with a clear error message.

Documentation

• STAN assistant guide: guides/stan-assistant-guide.md
• Generated API reference: https://docs.karmanivero.us/aws-xray-tools

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.