Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Span Specifications

Open
  • Is something wrong?
#659 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Domain
backend-api-design, documentation

Research direction

Review the existing attribute database, span description and naming rules, span ops, and the metrics precedent in issue #649. The work is done when the desired span-specification model and its ownership or location are agreed, including how conventions validation and develop documentation should relate to it.

Written by the indexing model from the issue text.

Description

Today, we collect a few building blocks for spans, but we're missing overall recipes or specifications, what data exactly spans should carry.
Span specifications today either don't exist or live in develop docs. Sometimes they're rather implicit, like the specs we wrote for prebuilt dashboards (formerly known as Insight Modules). The reason this is coming up because we often talk about which attributes a span should hold and how this currently differs across SDKs. There's a lot of implicit/shared knowledge today that isn't written down properly.

Today, we have:

  • a database of attributes (mostly without hints on which spans/telemetry they belong, which IMHO is correct)
  • rules for span descriptions and names
  • span ops

All of these are already fine but ideally we can define a schema that describes how spans with a certain op should carry data:

A span specification should include:

  • a list of span ops for which the specification applies
  • a description of the span
  • additional context if necessary (i.e. when to (not) start a span)
  • requirement level (span should always be started by default, recommended to be started by default, as opt-in)
  • a list of attributes the span should carry
    • attribute key (canonical)
    • requirement level
    • notes (e.g. "MUST be gated by dataCollection.httpHeaders", "MUST hold the outgoing request URL, not the current window location", etc.)
  • a list of links the span should include
    • (less important than attributes but might be neat in some cases)
  • a version and changelog to record spec changes

Benefits:

  • Today, our develop docs specs are outdated. They reference attributes we deprecated in conventions ([example](https://develop.sentry.dev/sdk/telemetry/traces/modules/requests/, which calls for http.query, which is deprecated in favour of url.query). We can test against this in conventions, by checking if referenced attributes in a span spec are 1. entered in conventions, 2. deprecated or still up to date
  • Conventions are easily machine-readable. We can easily generate LLM specific versions of these specs, or just point llms to the respective models.
  • There's (soon to be) precedence for metrics via #649

Drawbacks:

  • Develop docs loose a bit of content (though as I said, they're outdated already)
  • Requires work (duh)

Alternatives:

  • We do nothing. Technically also fine BUT we don't have reliable specs today which IMHO is a larger issue than we think.
  • Specs live in develop docs in dedicated, new pages. Probably requires more work than having them in conventions, especially if we want testing to be brought over as well. If we care about specs being accessible via develop, we can inject conventions pages into develop docs (cheap via iframes, or more sophisticated at build time).
Dominant language
TypeScript
Stars
16
Forks
7
Avg merge
2d 9h
Merged PRs (30d)
63

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from getsentry/sentry-conventions

All issues in getsentry/sentry-conventions

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.