Skip to content

feat(apidocs): Publish trace item details endpoint - #130373

Merged
BYK merged 4 commits into
masterfrom
byk/feat/apidocs-publish-trace-item-details
Nov 9, 2026
Merged

BYK merged 4 commits into
masterfrom
byk/feat/apidocs-publish-trace-item-details

Conversation

@sentry-junior

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

Copy link
Copy Markdown
Contributor

Part of the #130351 proposal to publish the endpoints the Sentry CLI calls today with raw API requests, so they reach the public schema and the generated @sentry/api SDK.

Owner: Data Browsing.

GET /projects/{org}/{project}/trace-items/{item_id}/ (ProjectTraceItemDetailsEndpoint) goes from EXPERIMENTAL to PUBLIC_EXPERIMENTAL. It stays experimental because the response shape is still changing (for example, rawName was added in #130132 on 2026-11-06).

Evidence

Changes

Commit 1: tooling, feat(apidocs): Add an opt-in JsonValue response field type

  • sentry.apidocs.formats.JsonValue (Annotated[object, ApiJsonValue()]) renders as an explicit anyOf of object, array, string, number and boolean, described as "Any JSON value".
  • The response-coverage ratchet treats a JsonValue field as typed and doesn't descend into it. Its x-sentry-json-value marker is only emitted under OPENAPIGENERATE and is stripped on deref, like the cycle marker.
  • It's opt-in. No existing operation changes: after this commit openapi-derefed.json is byte-identical to master.
  • Unit tests in tests/sentry/apidocs and a README paragraph.

Commit 2: the endpoint

  • PUBLIC_EXPERIMENTAL, Explore tag, retrieveProjectTraceItem / "Retrieve a Trace Item".
  • Documented params, checked against the serializer and the handler: item_id, trace_id (required), item_type (required; enum of the supported item types), routing_hint, timestamp, statsPeriod/start/end. referrer and the superuser-only debug stay undocumented.
  • TraceItemDetailsResponse and the nested TraceItemLink, TraceItemLinkAttribute and TraceItemEvent TypedDicts. The serializer helpers now return them.
  • JsonValue is used only for the free-form fields: the meta values (including the superuser meta.debug_info) and event.contexts/extra/breadcrumbs. Everything else is typed exactly.
  • TraceItemAttribute (sentry/search/eap/types.py) gets field descriptions. Its value is narrowed to ScalarValueType | list[ScalarValueType]: the only producer skips attributes without a value, so None was never returned. The skip check changed from and to or, which is the same at runtime (both are None or neither is) but lets mypy narrow the type.
  • 400s now use as_validation_errors(serializer), the same shape as the other published endpoints.
  • Span and log response examples, and an apidocs test for both (a log with event fields, a span with links).
  • Agent-token permission matrix: a real log stored in EAP backs the new row, because the matrix requires a 200.

Verification

  • make build-api-docs and a diff against master: only retrieveProjectTraceItem and its TraceItemDetailsResponse component are added. Nothing else changes.
  • Response-coverage ratchet: 0 fixed, 0 new entries.
  • pnpm run validate-api-examples: no errors.
  • pytest tests/apidocs 156 passed; tests/sentry/apidocs 170 passed.
  • Endpoint tests: tests/snuba/api/endpoints/test_project_trace_item_details.py 23 passed, 1 xpassed; tests/sentry/api/endpoints/test_project_trace_item_details.py 33 passed; test_organization_events_occurrences.py 20 passed, 1 xfailed; test_organization_events_span_indexed.py 181 passed, 3 skipped, 5 xfailed, 2 xpassed.
    • Snuba-backed tests failed under -n3 with different failures on each run, which is likely xdist flakiness. Every file passed when rerun on its own without xdist.
  • Agent-token matrix: 328 passed, 23 xfailed (the new row passes).
  • prek and mypy (pre-push) pass on the changed files.

The "(Optional) Shows the difference between the prod and dev schema" check is expected to fail on PRs that change the schema.

via @BYK.

--

View Session [Sentry]

sentry-junior Bot and others added 2 commits November 7, 2026 17:01
Some response fields hold data whose shape Sentry doesn't define, such as
the contexts an SDK sent. Typing them as `Any` or `dict[str, Any]` fails the
response coverage check, and there was no way to say that any JSON value is
intended.

`JsonValue` renders as an `anyOf` that lists every JSON type, and the
coverage check counts it as typed. The `x-sentry-json-value` marker that the
check reads is stripped on deref, like the other coverage extensions. No
existing field uses it, so the published schema doesn't change.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
Move GET /projects/{org}/{project}/trace-items/{item_id}/ from
EXPERIMENTAL to PUBLIC_EXPERIMENTAL with a typed, described response,
examples and an apidocs test. The response shape is still changing, so
it stays experimental.

Free-form fields (meta values, event contexts/extra/breadcrumbs) use the
opt-in JsonValue type. Everything else is typed exactly.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
@sentry-junior
sentry-junior Bot requested review from a team as code owners November 7, 2026 17:23
@github-actions github-actions Bot added Scope: Frontend Automatically applied to PRs that change frontend components Scope: Backend Automatically applied to PRs that change backend components labels Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

🚨 Warning: This pull request contains Frontend and Backend changes!

It's discouraged to make changes to Sentry's Frontend and Backend in a single pull request. The Frontend and Backend are not atomically deployed. If the changes are interdependent of each other, they must be separated into two pull requests and be made forward or backwards compatible, such that the Backend or Frontend can be safely deployed independently.

Have questions? Please ask in the #discuss-dev-infra channel.

serialize_event now returns TraceItemEvent, whose breadcrumbs are an
untyped JsonValue, so the tests check it's a dict before indexing it.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

@DominikB2014 DominikB2014 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.

Awesome, you might have already done this, but I would just make sure we're happy with where these endpoints end up in our api docs.

…blish-trace-item-details

# Conflicts:
#	src/sentry/apidocs/README.md
#	src/sentry/apidocs/formats.py
#	src/sentry/apidocs/spectacular_ports.py
#	tests/sentry/apidocs/test_spectacular_ports.py
BYK added a commit to getsentry/toolkit that referenced this pull request Nov 9, 2026
…eveApiIndex (#2118)

Bumps `@sentry/api` from 1.53.0 to 1.55.0 and moves the CLI's `GET
/api/0/` call onto the generated `retrieveApiIndex` operation.
getsentry/sentry#130369 published that endpoint, and 1.55.0 ships it.

## Change

`getCurrentAuthScopes` (`packages/cli/src/lib/api/auth.ts`) feeds scope
recovery. It used to call the raw
`apiRequestToRegion(getControlSiloUrl(), "")` helper. It now calls
`retrieveApiIndex` with `getSdkClientConfig(getControlSiloUrl())`, then
`unwrapValidatedResult` with the same valibot schema. This is the same
pattern as `org-auth-tokens.ts`.

Behavior is unchanged:
- It still goes to the control silo URL. That's the configured server
URL on self-hosted, so self-hosted works as before.
- `auth: null` still returns `null`. Sentry sends that for anonymous
requests, session requests and requests with no token, and scope
recovery treats it as `invalid`.
- A 401 still comes back as an `ApiError` with `status: 401`. That's the
case `scope-recovery.ts` checks. CLI errors thrown by the fetch layer,
such as `AuthError`, still pass through `unwrapResult` unchanged.

With this change, the API discovery step in `typecheck` no longer
reports `auth.ts` as "not in the public catalog".

## Bump

- `pnpm-workspace.yaml`: the catalog and `minimumReleaseAgeExclude` both
move to `@sentry/api@1.55.0`.
- `pnpm-lock.yaml`: the `@sentry/api` entries move to 1.55.0 and its
integrity. 1.55.0 has the same dependencies and peer dependencies as
1.53.0.
- `pnpm install --no-frozen-lockfile` wouldn't rewrite these entries.
pnpm's lockfile age check rejected the old 1.53.0 entry before it
resolved anything, even with 1.53.0 temporarily excluded, so I edited
the entries by hand.
- `pnpm install --frozen-lockfile` passes on the result, age policy
check included.
- 1.54.0 and 1.55.0 cause no other type errors. Neither the CLI docs nor
the skill references changed when regenerated.

## Still waiting on sentry
- dsn-lookup: getsentry/sentry#130367
- `/auth/` → `GET /users/me/`, falling back to `/auth/` on a 403 from
older self-hosted servers: getsentry/sentry#130368
- trace items (`traces.ts`, logs): getsentry/sentry#130373
- After those, the no-allowlist Oxlint rule.

## Gate (local sandbox)
- `pnpm run tsc`: passes.
- `pnpm run lint`: passes.
- Tests:
- These all pass: mcp-core, mcp-cloudflare, mcp-test-client,
toolkit-core, logger, apps/local, apps/docs-mcp, apps/games-api and
apps/cli-docs.
- CLI: 12952 pass and 5 fail. All 5 are the known sandbox-only
permission cases: completions ×2, upgrade lock, resilient DB and the
code-scanner unreadable-file test.
- `@sentry/cli3to4` can't run here, because its `codemod` binary needs
GLIBC 2.35.
- `test/lib/api/auth.test.ts` now mocks `retrieveApiIndex` and covers
scopes, `auth: null`, and the 401.

No UI change, so no screenshots.

Part of the `@sentry/api` migration that started in #2073 (tracking
issue: getsentry/sentry#130351).

<!-- junior-request-attribution:start -->
via @BYK.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3A80220b9d4c297e2a971f05dcb03af515 -->

--

[View
Session](https://junior-prod.sentry.dev/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515)
[[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515/?project=4510944073809921)

<!-- junior-session-footer:end -->

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Burak Yigit Kaya <126780+BYK@users.noreply.github.com>
@BYK

BYK commented Nov 9, 2026

Copy link
Copy Markdown
Member

We do use them in the CLI so they are already "public" 😅

@BYK
BYK merged commit 2231c37 into master Nov 9, 2026
100 of 101 checks passed
@BYK
BYK deleted the byk/feat/apidocs-publish-trace-item-details branch November 9, 2026 20:10

This branch was successfully deployed

1 active deployment
Preview — 53008e26 Deployed Nov 9, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Scope: Backend Automatically applied to PRs that change backend components Scope: Frontend Automatically applied to PRs that change frontend components

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants