Boson logoBoson
Documentation/Guides (Tracing)/Span naming
1 min read

Span naming

Span names are the backbone of filtering, dashboards, and “diffing” traces across releases. The goal is to make names stable, small in number, and meaningful.

Principles

  • Stable: names should not change when code moves.
  • Comparable: the same step should have the same name in every service.
  • Compositional: names should encode the domain and action.

Use domain.action (or area.action) such as:

  • retrieval.query
  • retrieval.rerank
  • llm.completion
  • tool.execute
  • guardrails.validate
  • cache.lookup

Anti-patterns

  • Dynamic names: tool.execute.search_${provider}
  • Code-centric names: callOpenAI, fetchDocsFromDB
  • Too many variants: llm.call.openai, llm.call.anthropic (use metadata for provider/model)

Use metadata for variability

Keep span name constant and add:

  • provider: openai
  • model: gpt-4.1
  • tool: web.search
  • index: docs_v3

Next steps