OpenTelemetry standardizes traces, metrics, and logs. This sheet focuses on traces.

Vocabulary

  • Trace: end-to-end request story.
  • Span: one timed operation (HTTP handler, DB query).
  • Context propagation: pass ids across services.

W3C Trace Context

Headers traceparent and tracestate carry trace + span ids. Middleware should extract incoming and inject outgoing.

Naming spans

Use low-cardinality names: GET /users/:id not GET /users/77291.

Attributes (examples)

http.method = GET
http.route = /users/{id}
db.system = postgresql
db.statement = SELECT ... (sanitized)

Span status

Mark ERROR on failures; record exceptions with stack hints (scrub PII).

Sampling

Head-based or tail-based sampling balances cost vs coverage; always sample errors if possible.