feat(traces): expose custom span attributes and improve agent guidance#623
Merged
Conversation
- span view: fetch full attributes from trace-items endpoint (all custom OTEL attributes like gen_ai.*, pi.* now visible in output) - trace view: pass --fields as additional_attributes query param - span list: --fields drives API field selection for custom attributes with gen_ai group alias for AI observability shortcuts - Add --since as alias for --period on all list commands - Filter zero-valued measurements from trace/span view JSON output - Add Quick Reference section to agent guidance docs with correct flag patterns, positional arg usage, and valid dataset names - Add shared EVENTS_API_DATASETS constant and document valid dataset names in api command docs
Contributor
Semver Impact of This PR🟡 Minor (new features) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨
Bug Fixes 🐛
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
Contributor
|
Contributor
Codecov Results 📊✅ 129 passed | Total: 129 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 85.39%. Project has 1335 uncovered lines. Files with missing lines (3)
Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
- Coverage 95.65% 95.56% -0.09%
==========================================
Files 204 204 —
Lines 29769 30037 +268
Branches 0 0 —
==========================================
+ Hits 28472 28702 +230
- Misses 1297 1335 +38
- Partials 0 0 —Generated by Codecov Action |
BYK
commented
Apr 1, 2026
- Replace OUTPUT_TO_API_FIELD mapping with flat KNOWN_SPAN_FIELDS set - Use native Set operations in extractExtraApiFields instead of array filter + spread dedup - Use Array.from(set) instead of spread for set-to-array conversion - Use Object.fromEntries() in attributesToDict - Use p-limit .map() helper in fetchSpanDetails - Use SPAN_FIELDS.concat() instead of spread in listSpans - Deduplicate hidden attribute sets: single REDUNDANT_DETAIL_ATTRS in traces.ts shared by span/view.ts and formatters/trace.ts - Rename INTERNAL_ATTRS to REDUNDANT_DETAIL_ATTRS with clearer category comments (timing/storage internals vs already-shown fields)
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Stricli AvailableAlias type is LowercaseLetter | UppercaseLetter, so multi-character keys like "since" are silently ignored at runtime. Updated agent guidance to only reference --period and -t.
Contributor
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
getNestedValue now checks for the path as a literal property name before falling back to dot-separated nested traversal. This fixes --fields gen_ai.usage.input_tokens on span list which stores custom attributes as flat dotted keys, not nested objects.
This was referenced Apr 1, 2026
betegon
added a commit
that referenced
this pull request
May 5, 2026
TraceItemAttribute and TraceItemDetail were defined twice: as plain TS types in traces.ts (PR #623) and as Zod schemas in sentry.ts (this branch). Remove the plain types from traces.ts and import from the types barrel instead, re-exporting for existing callers. Also: - Add .passthrough() to TraceItemDetailSchema so meta/links from the spans endpoint are preserved without failing validation - Add schema validation to getSpanDetails, matching getLogItemDetail - Rename SHOWN_IN_STANDARD_SECTIONS → REDUNDANT_LOG_DETAIL_ATTRS to mirror REDUNDANT_DETAIL_ATTRS naming in traces.ts Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
betegon
added a commit
that referenced
this pull request
May 5, 2026
`sentry log view` showed a fixed set of fields. Custom attributes users
attach to their logs — visible in the Sentry UI — were never fetched or
displayed.
`sentry log list` already supported custom attributes via `--fields`
before this work. No changes there.
**How it works**
The Sentry UI calls a trace-items detail endpoint when expanding a log
row:
```
GET /projects/{org}/{project}/trace-items/{itemId}/?item_type=logs&trace_id={traceId}
```
It returns every attribute on the log without needing to enumerate field
names. `log view` now does the same: after `getLogs` fetches standard
fields (including `trace`), `getLogItemDetail` is called in parallel for
each log. `formatLogDetails` renders all non-standard attributes in a
**Custom Attributes** section automatically. `--fields` filters that
section when you only want specific attributes.
The endpoint is `EXPERIMENTAL` in Sentry and not yet in `@sentry/api`
(generated from `getsentry/sentry-api-schema`), so it uses
`apiRequestToRegion` directly — same pattern as `listTraceLogs`.
Attribute types mirror `TraceItemResponseAttribute`:
https://github.com/getsentry/sentry/blob/8a4f150b21b/static/app/views/explore/hooks/useTraceItemDetails.tsx#L85-L89
If the endpoint is unavailable (no trace ID on the log, or request
fails), the formatter degrades gracefully and shows only standard
fields.
**Type consolidation**
PR #623 defined `TraceItemAttribute` and `TraceItemDetail` as plain TS
types in `traces.ts`. This PR moves them to `src/types/sentry.ts` with
Zod schemas (`.passthrough()` so `meta`/`links` from the spans endpoint
are preserved), exports them via the types barrel, and re-exports from
`traces.ts` for existing callers. `getSpanDetails` also gets schema
validation for parity with `getLogItemDetail`.
**Usage**
```bash
# Shows ALL custom attributes automatically — no config needed
sentry log view myorg/myproject <id>
# Limits the Custom Attributes section to specific fields
sentry log view myorg/myproject <id> --fields order.id,user.tier
# JSON output: unchanged
sentry log view myorg/myproject <id> --json
```
---------
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
Addresses feedback from an AI agent field report about Sentry CLI usability. The critical gap was that custom span attributes (like
gen_ai.usage.input_tokens,pi.session.id) were completely invisible via CLI — this PR fixes that across all three span/trace commands.Custom attribute access (critical)
span view: Fetches full attributes from thetrace-items/{itemId}/endpoint (same as Sentry frontend's span detail sidebar). All custom OTEL attributes now appear in both JSON and human output with no configuration needed.trace view:--fieldsvalues that aren't standard output fields are forwarded asadditional_attributesquery params to the trace detail API.span list:--fieldsnow drives API field selection — unknown field names are requested as additionalfieldparams from the events API. Includesgen_aigroup alias that expands to common AI observability fields.Agent guidance improvements
--sinceas an alias for--periodon all list commands (the most natural flag name for time filtering)Quality of life
trace viewJSON output (~40% size reduction for typical traces)EVENTS_API_DATASETSshared constant and documented valid dataset names in api command docsTraceSpantype to include all fields the trace detail API actually returns (measurements,additional_attributes,sdk_name,errors,occurrences, etc.)