TRACE EVENTS
Connect spans with one trace ID and route label.
A trace is a group of ordinary TrafficWar events. Share one trace_id and label across the request and describe each tier with its normal event fields.
Example multi-tier trace
const trace_id = crypto.randomUUID();
const distinct_id = "usr_7f3a91c2";
const label = "/checkout";
const started_at = Date.now();
const at = (offset_ms) => new Date(started_at + offset_ms);
trafficwar.capture([
{ event: "database", label, trace_id, distinct_id, source: "db-primary",
operation_type: "postgres.select", span_kind: "client",
timestamp: at(20), latency_ms: 12.4 },
{ event: "external", label, trace_id, distinct_id, source: "payment-gateway",
operation_type: "payment.authorize", span_kind: "client",
timestamp: at(34), latency_ms: 13.0 },
{ event: "s3", label, trace_id, distinct_id, source: "receipts.ovh-s3",
operation_type: "s3.put_object", span_kind: "client",
timestamp: at(50), latency_ms: 18.3 },
{ event: "http", label, trace_id, distinct_id, source: "checkout-api",
operation_type: "route.handler", span_kind: "server",
timestamp: at(8), latency_ms: 96.1 },
{ event: "http", label, trace_id, distinct_id, source: "web", http_method: "POST",
operation_type: "http.request", span_kind: "client", latency_ms: 184.2,
timestamp: at(0), status_code: 200 },
]);Keep the hierarchy valid
Emit dependency spans before the backend and edge span when sending one array. Give every span its real start timestamp. Inclusive durations should nest: dependency time must not exceed backend time, and backend time must not exceed the edge request.
External service convention
Use event external for an outbound HTTP service such as Google Routes, OSRM, a payment gateway, or a tile origin. Keep span_kind client, put the stable provider alias in source, and use operation_type for the concrete API call. External stations are placed on the infrastructure tier and keyed by source rather than the shared request label.
Incoming callers remain event http. Use a trusted or allowlisted caller identity such as an HTTPS origin or web-direct; never substitute your own API Host header when Origin and Referer are absent.
S3 source convention
For S3, source is a provider alias such as ovh-s3, aws-s3, or minio. Use bucket.provider, such as receipts.ovh-s3, only when separate bucket stations are useful. The operation_type remains the operation dot.