Distributed tracing

Link requests across services with trace_id, span_id, and W3C traceparent.

Concepts

Term	Description
Trace	One logical request flow (many spans)
Span	One unit of work (HTTP handler, DB call, LLM call)
Session	End-user session (session_id / x-session-id)
User	End-user id (user_id / x-user-id)

Node.js — manual spans

import {
  createTraceContext,
  childSpan,
  applyTraceToEvent,
} from '@amlexiahq/node/tracing';
import { AmlexiaClient } from '@amlexiahq/node';

const client = AmlexiaClient.fromEnv();
const root = createTraceContext({
  environment: 'production',
  serviceName: 'api',
});

app.get('/orders', async (req, res) => {
  const span = childSpan(root, { operationName: 'list_orders' });
  await client.track(applyTraceToEvent({
    endpoint: 'GET /orders',
    method: 'GET',
    statusCode: 200,
    latencyMs: 45,
  }, span));
});

Middleware behavior

Express/FastAPI/Hono middleware automatically:

• Creates trace context per request
• Normalizes paths (/users/42 → /users/:id)
• Sets traceparent response header: 00-{traceId}-{spanId}-01
• Reads x-session-id, x-user-id

Propagate traceparent to downstream services for linked traces.

Python

from amlexia.tracing import create_trace_context, child_span

root = create_trace_context(environment="production")
child = child_span(root)
client.track(..., trace_id=child.trace_id, span_id=child.span_id)

Send trace batches

POST /v1/traces with sdk_key and span array — see Traces API.

OpenTelemetry

If you already emit OTEL spans:

import { exportOtelSpans } from '@amlexiahq/node/otel';

exportOtelSpans(client, otelSpans);

Guide: OpenTelemetry

Dashboard

Traces page → select trace → span waterfall + related events.

Requires events with trace_id / span_id populated.

Related

• Complete setup
• Event fields