Span Modeling

Span Anatomy

A span represents a single operation within a trace. It has a name, start time, end time, parent span ID, status, and attributes. Spans form a tree that represents the request path through your system.

Span {
  traceId:      "abc123def456"
  spanId:       "a1b2c3"
  parentSpanId: "d4e5f6"
  operationName: "GET /api/v1/users"
  startTime:    2024-01-15T10:30:00.000Z
  endTime:      2024-01-15T10:30:00.045Z
  status:       OK
  attributes:   {http.method: "GET", http.status_code: 200}
  events:       [{name: "cache.miss", time: 10:30:00.010Z}]
}

Span Naming

Span names should be low-cardinality and describe the operation. Use the HTTP method and route template, not the specific request. A span named GET /api/v1/users/12345 is high-cardinality. GET /api/v1/users/:id is correct.

Span Attributes

Attributes add context to spans. Use semantic conventions for standard attributes (http.method, db.system). Custom attributes should be useful for debugging without creating high cardinality.

Span Events

Events are timestamped annotations within a span. They mark specific moments like cache misses, retries, or error occurrences. Events add detail without creating new spans.

Avoiding High Cardinality

• Do not use user IDs, request IDs, or UUIDs as span names.
• Do not use specific values as attribute keys.
• Use route templates instead of specific paths.
• Keep attribute values to bounded sets.
• Use events for variable data instead of attributes.

Best Practices