X-ray emitter

Node and Typescript SDKs to emit request logs to Stainless X-ray.

Getting started

npm add @stainlessdev/xray-emitter

Then using it in Express, for example:

import express from 'express';
import { createEmitter } from '@stainlessdev/xray-emitter/express';
import { getXrayContext } from '@stainlessdev/xray-emitter/node';

const app = express();

const xray = createEmitter({ serviceName: 'my-service' });

app.use(xray);

app.use((req, _res, next) => {
  const ctx = getXrayContext(req);
  ctx?.setActor('tenant-123', 'user-123');
  next();
});

app.get('/', (_req, res) => {
  res.send('ok');
});

Supported frameworks

| Framework | Import | Docs | Example | |-----------|--------|------|---------| | Express | @stainlessdev/xray-emitter/express | README | example | | Fastify | @stainlessdev/xray-emitter/fastify | README | example | | Hono | @stainlessdev/xray-emitter/hono | README | example | | Next.js | @stainlessdev/xray-emitter/next | README | example | | Remix | @stainlessdev/xray-emitter/remix | README | example | | Effect | @stainlessdev/xray-emitter/effect | README | example |

Lower-level adapters:

| Adapter | Import | Docs | Example | |---------|--------|------|---------| | Node.js (node:http) | @stainlessdev/xray-emitter/node | README | example | | Fetch / Edge | @stainlessdev/xray-emitter/fetch | README | example | | Core | @stainlessdev/xray-emitter | README | — |

Configuration

X-ray does not read standard OTEL environment variables. Configure an endpoint by passing endpointUrl or setting STAINLESS_XRAY_ENDPOINT_URL. If both are set, endpointUrl wins. An error is thrown if no endpoint is configured.

The core module (@stainlessdev/xray-emitter) is runtime-agnostic; use it only if you supply a custom exporter instance to createEmitter.

Request IDs

X-ray resolves request IDs from response headers when the span is closed. Configure the header name with requestId.header (default: request-id, emitted as Request-Id). Resolution order is: explicit requestId on the normalized request → response header lookup → UUIDv7 when missing.

If the configured response header is missing when the response is finalized, X-ray will set it (using the explicit ID when provided, otherwise a generated UUIDv7). Existing response headers are not overwritten.

Fetch wrappers

wrapFetch may replace the request/response objects while capturing bodies. wrapFetchPreserve keeps the original request/response whenever possible, but it may replace the response if it needs to inject a missing Request-Id header.

Development

pnpm install
pnpm build
pnpm test