Use stable event identities that stay useful at scale.

Canonical identity fields

• event: the category, normally http, database, redis, s3, or external.
• operation_type: the concrete work, such as route.handler, postgres.select, redis.get, s3.get_object, or google.routes.compute.
• source: the emitting host or dependency alias, such as backend-a, db-primary, redis-1, assets.ovh-s3, or google-routes.
• label: the human route or operation name shared across related spans.
• path and http_method: the URL path and normalized HTTP method for HTTP work.

Measurements and outcome

• latency_ms: non-negative duration in milliseconds.
• status_code: the HTTP or operation status when one exists.
• is_error: derived canonically by the server from status_code, error, or error_code.
• timestamp: RFC3339 or epoch milliseconds for presentation order; received time remains the operational axis.

Actors, traces, and custom data

• distinct_id identifies one stable, pseudonymous application actor across devices without changing the account-level metric grain. Prefer an opaque internal user ID or a backend-derived HMAC; do not send a raw email address.
• trace_id connects spans from one request.
• span_kind describes client or server trace role.
• properties carries tenant-owned JSON for investigation, including complete exception stack traces. Keep error, error_code, or an error status_code first class so the server still marks the event as an error.

Capture an application error

Properties are opaque and do not affect is_error. Always send a first-class error, error_code, or status_code of 400 or greater alongside diagnostic properties.

try {
  await submitOrder();
} catch (caught) {
  const error = caught instanceof Error ? caught : new Error(String(caught));

  trafficwar.capture({
    event: "http",
    label: "/checkout",
    http_method: "POST",
    status_code: 500,
    error: error.message,
    error_code: "CHECKOUT_FAILED",
    distinct_id: "usr_7f3a91c2",
    properties: {
      exception_type: error.name,
      stack_trace: error.stack ?? error.message,
      cause: "connection deadline exceeded",
    },
  });
}