Repository navigation
feat(apidocs): Publish trace item details endpoint - #130373
Merged
Merged
Conversation
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>
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 |
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
approved these changes
Nov 9, 2026
DominikB2014
left a comment
Contributor
There was a problem hiding this comment.
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>
Member
|
We do use them in the CLI so they are already "public" 😅 |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/apiSDK.Owner: Data Browsing.
GET /projects/{org}/{project}/trace-items/{item_id}/(ProjectTraceItemDetailsEndpoint) goes fromEXPERIMENTALtoPUBLIC_EXPERIMENTAL. It stays experimental because the response shape is still changing (for example,rawNamewas added in #130132 on 2026-11-06).Evidence
trace_idbecame required in feat(trace-item-details): Add a required trace_id argument for performance #87905 (2025-03-25).static/app/views/explore/hooks/useTraceItemDetails.tsx), the logs table rows and the trace drawer's "view JSON" links, plus the Sentry CLI.Changes
Commit 1: tooling,
feat(apidocs): Add an opt-in JsonValue response field typesentry.apidocs.formats.JsonValue(Annotated[object, ApiJsonValue()]) renders as an explicitanyOfof object, array, string, number and boolean, described as "Any JSON value".JsonValuefield as typed and doesn't descend into it. Itsx-sentry-json-valuemarker is only emitted underOPENAPIGENERATEand is stripped on deref, like the cycle marker.openapi-derefed.jsonis byte-identical to master.tests/sentry/apidocsand a README paragraph.Commit 2: the endpoint
PUBLIC_EXPERIMENTAL,Exploretag,retrieveProjectTraceItem/ "Retrieve a Trace Item".item_id,trace_id(required),item_type(required; enum of the supported item types),routing_hint,timestamp,statsPeriod/start/end.referrerand the superuser-onlydebugstay undocumented.TraceItemDetailsResponseand the nestedTraceItemLink,TraceItemLinkAttributeandTraceItemEventTypedDicts. The serializer helpers now return them.JsonValueis used only for the free-form fields: themetavalues (including the superusermeta.debug_info) andevent.contexts/extra/breadcrumbs. Everything else is typed exactly.TraceItemAttribute(sentry/search/eap/types.py) gets field descriptions. Itsvalueis narrowed toScalarValueType | list[ScalarValueType]: the only producer skips attributes without a value, soNonewas never returned. The skip check changed fromandtoor, which is the same at runtime (both areNoneor neither is) but lets mypy narrow the type.as_validation_errors(serializer), the same shape as the other published endpoints.Verification
make build-api-docsand a diff against master: onlyretrieveProjectTraceItemand itsTraceItemDetailsResponsecomponent are added. Nothing else changes.pnpm run validate-api-examples: no errors.pytest tests/apidocs156 passed;tests/sentry/apidocs170 passed.tests/snuba/api/endpoints/test_project_trace_item_details.py23 passed, 1 xpassed;tests/sentry/api/endpoints/test_project_trace_item_details.py33 passed;test_organization_events_occurrences.py20 passed, 1 xfailed;test_organization_events_span_indexed.py181 passed, 3 skipped, 5 xfailed, 2 xpassed.-n3with different failures on each run, which is likely xdist flakiness. Every file passed when rerun on its own without xdist.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]