feat(schema): Add `additional_context` field to attribute definitions by matejminar · Pull Request #393 · getsentry/sentry-conventions

matejminar · 2026-05-20T12:42:55Z

Adds a new optional additional_context field to attribute definitions — a list of freeform notes capturing query-time nuances, common pitfalls, or behavioral context that isn't covered by brief.

Motivation

Span attributes can have subtleties that trip up both users and AI agents when querying. For example, gen_ai.cost.total_tokens appears on both agent parent spans and LLM child spans, causing sum() queries to double-count. Today there's nowhere to capture this kind of context — brief describes what the attribute is, not how to use it correctly.

This is the foundation for surfacing attribute context to Explore UI (via Seer) and AI agent tooling. A follow-up PR will populate the field for gen_ai cost and usage attributes.

See proposal: https://www.notion.so/sentry/Proposal-Query-Guidance-for-Span-Attributes-3598b10e4b5d806d8c75e2a5b1caa42c

Changes

Schema: New optional additional_context property (array of strings) in attribute.schema.json
Types: Added to AttributeJson interface in types.ts
Codegen: Updated JS and Python generators to propagate the field into AttributeMetadata (as additionalContext in JS, additional_context in Python)
Generated code: Regenerated JS and Python packages with the new field

Closes TET-2319, TET-2315

Adds a new optional `additional_context` field to attribute definitions — a list of freeform notes capturing query-time nuances, common pitfalls, or behavioral context that isn't covered by `brief`. Span attributes can have subtleties that trip up both users and AI agents when querying. For example, `gen_ai.cost.total_tokens` appears on both agent parent spans and LLM child spans, causing `sum()` queries to double-count. Today there's nowhere to capture this kind of context — `brief` describes *what* the attribute is, not *how to use it correctly*. This is the foundation for surfacing attribute context to Explore UI (via Seer) and AI agent tooling. A follow-up PR will populate the field for gen_ai cost and usage attributes. See proposal: https://www.notion.so/sentry/Proposal-Query-Guidance-for-Span-Attributes-3598b10e4b5d806d8c75e2a5b1caa42c Changes: - Schema: New optional `additional_context` property (array of strings) in `attribute.schema.json` - Types: Added to `AttributeJson` interface in `types.ts` - Codegen: Updated JS and Python generators to propagate the field into `AttributeMetadata` (as `additionalContext` in JS, `additional_context` in Python) - Generated code: Regenerated JS and Python packages with the new field

github-actions · 2026-05-20T12:43:11Z

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

New Features ✨

Attributes

Add graphql.document attribute by ericapisani in #390
Add several measurement attributes by loewenheim in #362
Add gcp.function.context.* span attributes by chargome in #371
Add sentry.dsc.project_id as an attribute by constantinius in #358
Add trpc.* attributes by chargome in #370
Add angular.version attribute by chargome in #367
Add aws.lambda.* and aws.cloudwatch.logs.* attributes by chargome in #369
Add react.version attribute by chargome in #368
Add state.type attribute by chargome in #365
Add cloud.* span attributes by chargome in #364
Add calculated performance scores by loewenheim in #355
Add rpc.response.status_code attribute by alexander-alderman-webb in #352
Add rpc.method attribute by alexander-alderman-webb in #351
Add app vitals start attributes by buenaflor in #353
Add process.runtime.engine.* attributes by chargome in #347

Other

(docs) Add measurements page by Lms24 in #389
(measurements) Add attribute field by loewenheim in #388

(schema) Add additional_context field to attribute definitions by matejminar in #393

Bug Fixes 🐛

Attributes

Correct PR references in attribute changelogs by chargome in #384
Increase some PII values by loewenheim in #373
Change several deprecation statuses to normalize to align with ingestion paths by constantinius in #350

Other

(create) Replace angle brackets in file names by loewenheim in #356

Internal Changes 🔧

Deps

Bump astro from 6.1.6 to 6.1.10 by dependabot in #374
Bump svelte from 5.53.5 to 5.55.7 by dependabot in #381

Other

(gh) Remove myself from CODEOWNERS by lcian in #354
Bump vulnerable pytest by alexander-alderman-webb in #360
Bump vulnerable js packages by chargome in #359

_{🤖 This preview updates automatically when you update the PR.}

linear-code · 2026-05-20T12:50:38Z

TET-2319

TET-2315

Lms24

nice, LGTM! We most likely also want to show this field in our Astro docs but we can tackle that as a follow-up PR once we also add the field to some attributes.

…ributes Populates the `additional_context` field (introduced in #393) for all 11 gen_ai cost and usage attributes. Each attribute gets notes about: - Double-counting: all cost/usage attributes appear on both agent parent spans (aggregated totals) and LLM child spans (per-call values). Summing without filtering to gen_ai.operation.type:ai_client will over-report. - Naming confusion: cost attributes contain USD values despite having "tokens" in the name. - Subset relationships: cached input tokens are a subset of input tokens, reasoning tokens are a subset of output tokens, and total tokens is the sum of input + output. These should not be summed together. Attributes updated: - gen_ai.cost.input_tokens, gen_ai.cost.output_tokens, gen_ai.cost.total_tokens - gen_ai.usage.input_tokens, gen_ai.usage.input_tokens.cached, gen_ai.usage.input_tokens.cache_write - gen_ai.usage.output_tokens, gen_ai.usage.output_tokens.reasoning - gen_ai.usage.total_tokens - gen_ai.usage.completion_tokens (deprecated), gen_ai.usage.prompt_tokens (deprecated)

…ributes (#397) Populates the `additional_context` field (introduced in #393) for all 11 gen_ai cost and usage attributes. Each attribute gets notes about: - Double-counting: all cost/usage attributes appear on both agent parent spans (aggregated totals) and LLM child spans (per-call values). Summing without filtering to gen_ai.operation.type:ai_client will over-report. - Naming confusion: cost attributes contain USD values despite having "tokens" in the name. - Subset relationships: cached input tokens are a subset of input tokens, reasoning tokens are a subset of output tokens, and total tokens is the sum of input + output. These should not be summed together. Attributes updated: - gen_ai.cost.input_tokens, gen_ai.cost.output_tokens, gen_ai.cost.total_tokens - gen_ai.usage.input_tokens, gen_ai.usage.input_tokens.cached, gen_ai.usage.input_tokens.cache_write - gen_ai.usage.output_tokens, gen_ai.usage.output_tokens.reasoning - gen_ai.usage.total_tokens - gen_ai.usage.completion_tokens (deprecated), gen_ai.usage.prompt_tokens (deprecated)

Surfaces the `additional_context` field (added in #393, populated in #397) in the Astro docs site and the plain text LLM export. Changes: - content.config.ts: Added additional_context to the Zod schema - AttributeCard.astro: Renders notes as a collapsible section (open by default) above the changelog, matching the existing disclosure pattern - llms-full.txt.ts: Includes additional_context as nested list items in the plain text export for LLM consumption

…rt (#399) Surfaces the `additional_context` field (added in #393, populated in #397) in the Astro docs site and the plain text LLM export. Changes: - content.config.ts: Added additional_context to the Zod schema - AttributeCard.astro: Renders notes as a collapsible section (open by default) above the changelog, matching the existing disclosure pattern - llms-full.txt.ts: Includes additional_context as nested list items in the plain text export for LLM consumption

matejminar requested review from a team, Lms24, cleptric, mjq and nsdeschenes as code owners May 20, 2026 12:42

Lms24 approved these changes May 20, 2026

View reviewed changes

matejminar merged commit bbda8cc into main May 21, 2026
17 checks passed

matejminar deleted the feat/additional-context-field branch May 21, 2026 08:27

This was referenced May 21, 2026

feat(attributes): Add additional_context to gen_ai cost and usage attributes #397

Merged

feat(docs): Render additional_context in attribute cards and LLM export #399

Merged

sentry-release-bot Bot mentioned this pull request May 21, 2026

publish: getsentry/sentry-conventions@0.9.0 getsentry/publish#8237

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(schema): Add `additional_context` field to attribute definitions#393

feat(schema): Add `additional_context` field to attribute definitions#393
matejminar merged 1 commit into
mainfrom
feat/additional-context-field

matejminar commented May 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 20, 2026 •

edited

Loading

New Features ✨

Attributes

Other

Bug Fixes 🐛

Attributes

Other

Internal Changes 🔧

Deps

Other

Uh oh!

linear-code Bot commented May 20, 2026 •

edited

Loading

Uh oh!

Lms24 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

matejminar commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Uh oh!

github-actions Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Semver Impact of This PR

New Features ✨

Attributes

Other

Bug Fixes 🐛

Attributes

Other

Internal Changes 🔧

Deps

Other

Uh oh!

linear-code Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lms24 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matejminar commented May 20, 2026 •

edited

Loading

github-actions Bot commented May 20, 2026 •

edited

Loading

linear-code Bot commented May 20, 2026 •

edited

Loading