Skip to content

feat(develop-docs): Render span attributes from sentry-conventions - #20557

Closed
sentry-junior[bot] wants to merge 6 commits into
masterfrom
junior/convention-attributes-component
Closed

sentry-junior[bot] wants to merge 6 commits into
masterfrom
junior/convention-attributes-component

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

DESCRIBE YOUR PR

Render develop-docs attribute tables from @sentry/conventions instead of copying them, so type, description, and example can't drift from the source of truth.

  • Add @sentry/conventions dependency
  • Add <ConventionAttributes> MDX component (Attribute / Type / Description / Example), with a link to the attribute category in Sentry Conventions under each table
  • Unknown keys fail the build
  • Optional per-row notes for page-specific footnotes
  • Migrate Token Usage Data and Execute Tool Span tables in ai-agents.mdx

Note: descriptions now come from conventions, so wording fixes go upstream (e.g. the gen_ai.usage.total_tokens typo).

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

  • Urgent deadline (GA date, etc.): YYYY-MM-DD
  • Other deadline: YYYY-MM-DD
  • No deadline: Not urgent, can wait up to 1 week+

SLA

  • Teamwork makes the dream work, so please add a reviewer to your PRs.
  • Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

  • Checked Vercel preview for correctness, including links
  • PR was reviewed and approved by any necessary SMEs (subject matter experts)
  • PR was reviewed and approved by a member of the Sentry docs team

🤖 Generated with Claude Code

Add a ConventionAttributes MDX component that reads attribute type,
description, deprecation, and example from @sentry/conventions instead
of copying them into Markdown tables. Unknown keys fail the build.

Migrate the token usage and execute tool tables on the AI agents page.
@vercel

vercel Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
develop-docs Ready Ready Preview Nov 6, 2026 9:11am UTC
sentry-docs Ready Ready Preview Nov 6, 2026 9:11am UTC

Request Review

@github-actions github-actions Bot added sdk-develop-docs PRs touching develop-docs/sdk Priority: Normal Docs review has no urgent deadline labels Nov 5, 2026
Keep the table close to the Markdown tables it replaces. Drop the per-key
links, the deprecated prefix, and the InlineMarkdown wrapper, and shorten
the unknown-attribute error. Add one link under each table to the
attribute category page in Sentry Conventions instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sentry-junior

sentry-junior Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Preview: Token Usage Data table

After (<ConventionAttributes>, preview of d021e0c):

Token Usage Data rendered from sentry-conventions

Before (hand-written Markdown table on develop.sentry.dev):

Token Usage Data before

Differences reviewers will notice:

  • Types now use the conventions names (integer instead of int).
  • Descriptions come from conventions, including the "todkens" typo in gen_ai.usage.total_tokens. The fix belongs upstream.
  • Each example is defined on its own attribute in conventions, so the examples no longer add up across rows. The old table used one consistent set (60 input, 50 cached, 130 output, 190 total). Now input_tokens is 10 while cache_read.input_tokens is 50. This ties into open question 5 about examples.

@sentry-junior

sentry-junior Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Preview: Execute Tool Span table

After (<ConventionAttributes>, preview of d021e0c):

Execute Tool Span rendered from sentry-conventions

Before (hand-written Markdown table on develop.sentry.dev):

Execute Tool Span before

Differences reviewers will notice:

  • Descriptions and examples now come from conventions. For example, gen_ai.tool.call.arguments now says "It has to be a stringified version of the arguments to the tool." and the example is "{"location": "Paris"}" instead of '{"max":10}'.
  • The table is wider than before because the conventions descriptions and examples are longer.

…ttributes-component

# Conflicts:
#	develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx
Replace the hand-written notes prop with the additionalContext notes from
@sentry/conventions. Notes render as a numbered list under the table, and
attributes that share a note link to the same number, so pages no longer
maintain footnotes for attributes the component renders.
@cursor

cursor Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Getting ready to monitor this change · Rollout details

Status Service Environment
⏳ Getting ready to monitor this change

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 23302c9. Configure here.

…butes

String examples were wrapped in raw double quotes, so JSON strings such as
gen_ai.tool.call.arguments rendered as broken nested quotes. Single-quote
strings that contain double quotes, matching the Markdown tables, and use
JSON.stringify for everything else.

@sfanahata sfanahata left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Renders well!

@cleptric

cleptric commented Nov 9, 2026

Copy link
Copy Markdown
Member

replaced by #20638

@cleptric cleptric closed this Nov 9, 2026
cleptric added a commit that referenced this pull request Nov 10, 2026
…20638)

## DESCRIBE YOUR PR

Replaces #20557.

Adds a `<ConventionAttributes>` MDX component that renders span
attribute tables straight from
[`@sentry/conventions`](https://github.com/getsentry/sentry-conventions),
so the develop docs stop drifting from the conventions repo. The AI
agents module page is the first user.

- New `ConventionAttributes` component (with tests), registered in
`mdxComponents.ts`
- All attribute tables on the AI agents page now render from
conventions; footnotes the convention briefs already cover are dropped
- Depends on `@sentry/conventions@^0.33.0`, which ships
getsentry/sentry-conventions#784 through #788

Preview:
https://develop-docs-git-cleptric-featconvention-attributes-component.sentry.dev/sdk/telemetry/traces/modules/ai-agents/

## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the
due date. You can update this information later by editing the PR
description.

- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] No deadline: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
supplied a deadline.

Thanks in advance for your help!

## PRE-MERGE CHECKLIST

_Make sure you've checked the following before merging your changes:_

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Johannes Daxböck <johannes.daxboeck@sentry.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

2 active deployments
Preview – sentry-docs — f5522cbe Deployed Nov 6, 2026 by vercel[bot]
Preview – develop-docs — f5522cbe Deployed Nov 6, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Improvement Priority: Normal Docs review has no urgent deadline sdk-develop-docs PRs touching develop-docs/sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants