AWS OpenTelemetry X-Ray IdGenerator

The OpenTelemetry IdGenerator for AWS X-Ray generates trace IDs with its first four bytes set to the start time of the trace followed by a unique identifier consisting of 12 bytes of randomly generated numbers. This enables compatibility with AWS X-Ray service for distributed tracing in cloud environments.

Package Information

• Package Name: @opentelemetry/id-generator-aws-xray
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save @opentelemetry/id-generator-aws-xray
• Peer Dependencies: @opentelemetry/api ^1.0.0
• Dependencies: @opentelemetry/sdk-trace-base ^2.0.0

Core Imports

import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";

For CommonJS:

const { AWSXRayIdGenerator } = require("@opentelemetry/id-generator-aws-xray");

Additional imports for advanced usage:

import { IdGenerator } from "@opentelemetry/sdk-trace-base";
import { INVALID_SPANID, INVALID_TRACEID } from "@opentelemetry/api";

Basic Usage

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";

// Configure tracer with AWS X-Ray ID generator
const tracerConfig = {
  idGenerator: new AWSXRayIdGenerator(),
  // other configuration options...
};

const tracerProvider = new NodeTracerProvider(tracerConfig);

// The ID generator will now create AWS X-Ray compatible trace and span IDs

Architecture

The AWS X-Ray IdGenerator implements the OpenTelemetry IdGenerator interface and provides platform-specific implementations for both Node.js and browser environments:

• Cross-platform Support: Automatic platform detection with optimized implementations
• AWS X-Ray Format Compliance: Trace IDs follow AWS X-Ray's timestamp + random format
• OpenTelemetry Integration: Implements the standard IdGenerator interface
• Unique ID Generation: Ensures generated IDs are never all zeros or invalid

Capabilities

AWSXRayIdGenerator Class

Main class that implements AWS X-Ray compatible ID generation for OpenTelemetry tracing systems.

/**
 * IdGenerator that generates trace IDs conforming to AWS X-Ray format.
 * Implements the OpenTelemetry IdGenerator interface.
 */
class AWSXRayIdGenerator implements IdGenerator {
  constructor();
  generateTraceId(): string;
  generateSpanId(): string;
}

Usage Example:

import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";

const idGenerator = new AWSXRayIdGenerator();

// Generate AWS X-Ray compatible trace ID
const traceId = idGenerator.generateTraceId();
console.log(traceId); // e.g., "58406520a006649127e371903a2de979"

// Generate span ID
const spanId = idGenerator.generateSpanId();
console.log(spanId); // e.g., "6e3b4749a8b7e2f3"

Trace ID Generation

Generates a random 16-byte trace ID formatted as a 32-character lowercase hexadecimal string. The first 4 bytes correspond to the current time in Unix epoch seconds (AWS X-Ray format requirement).

/**
 * Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex
 * characters corresponding to 128 bits. The first 4 bytes correspond to the current
 * time, in seconds, as per X-Ray trace ID format.
 * @returns 32-character hexadecimal trace ID string
 */
generateTraceId(): string;

Trace ID Format Details:

• Total Length: 32 hexadecimal characters (128 bits)
• Timestamp: First 8 hex characters represent Unix epoch time in seconds
• Random Part: Last 24 hex characters are randomly generated unique identifier
• Example: 58406520a006649127e371903a2de979
  • 58406520 = timestamp (1480615200 seconds = Dec 1, 2016 10:00 AM PST)
  • a006649127e371903a2de979 = random 24-character identifier

Span ID Generation

Generates a random 8-byte span ID formatted as a 16-character lowercase hexadecimal string. Includes validation to ensure the ID is never all zeros.

/**
 * Returns a random 8-byte span ID formatted/encoded as a 16 lowercase hex
 * characters corresponding to 64 bits.
 * @returns 16-character hexadecimal span ID string
 */
generateSpanId(): string;

Span ID Details:

• Total Length: 16 hexadecimal characters (64 bits)
• Validation: Automatically handles edge case of all-zero random generation
• Fallback: Uses 0000000000000001 if random generation produces all zeros
• Example: 6e3b4749a8b7e2f3

Types

/**
 * OpenTelemetry IdGenerator interface implemented by AWSXRayIdGenerator
 * Import from: @opentelemetry/sdk-trace-base
 */
interface IdGenerator {
  generateTraceId(): string;
  generateSpanId(): string;
}

Constants

Relevant OpenTelemetry constants used with ID validation:

/**
 * Constants from @opentelemetry/api for ID validation
 */
const INVALID_SPANID: string;   // "0000000000000000" - invalid span ID
const INVALID_TRACEID: string;  // "00000000000000000000000000000000" - invalid trace ID

Platform Support

• Node.js: Requires Node.js ^18.19.0 || >=20.6.0
• Browser: Compatible with modern browsers supporting ES modules
• TypeScript: Full TypeScript support with type definitions included
• Module Formats: Supports both CommonJS and ES modules