AWS X-Ray

AWS X-Ray collects and visualizes distributed traces across AWS services and custom Node.js applications. PURISTA sends traces via OTLP — either directly to an ADOT Collector sidecar or to the X-Ray OTLP endpoint.

Install

npm install @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-trace-node

TypeScript setup

Option A — ADOT Collector sidecar (recommended for production)

Run the AWS Distro for OpenTelemetry Collector as a sidecar. Your application sends to it via OTLP HTTP; the collector forwards to X-Ray with the correct authentication and protocol translation.

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'

export function getSpanProcessor() {
  // ADOT Collector sidecar listens on port 4318
  return new SimpleSpanProcessor(
    new OTLPTraceExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318/v1/traces',
    })
  )
}

Option B — Direct OTLP to X-Ray (preview)

AWS offers a managed OTLP endpoint in supported regions. Send traces directly without a sidecar:

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'

export function getSpanProcessor() {
  return new SimpleSpanProcessor(
    new OTLPTraceExporter({
      // Replace <region> with your AWS region, e.g. us-east-1
      url: `https://xray.${process.env.AWS_REGION}.amazonaws.com/v1/traces`,
      headers: {
        // SigV4 signing is handled by the ADOT SDK or a custom interceptor
      },
    })
  )
}

Wire it into your application:

import { getSpanProcessor } from './tracing.js'
import { AmqpBridge } from '@purista/amqpbridge'

const spanProcessor = getSpanProcessor()

const eventBridge = new AmqpBridge({ spanProcessor })
await eventBridge.start()

const myService = await myV1Service.getInstance(eventBridge, { spanProcessor })
await myService.start()

IAM permissions

The IAM role running your application (or the ADOT Collector) needs:

{
  "Effect": "Allow",
  "Action": [
    "xray:PutTraceSegments",
    "xray:PutTelemetryRecords"
  ],
  "Resource": "*"
}

Environment variables

Viewing traces

Open the X-Ray console, select Traces, and use the service map to navigate the distributed call graph. Each PURISTA command and subscription appears as a named segment.

Resources

• AWS Distro for OpenTelemetry
• X-Ray documentation
• ADOT Collector configuration guide