[lzhao-sentry]

Changes

This PR adds a top level attribute list command to CLI as part of an effort to clean up and expose attributes for both users and agents.

Some design choices:

• --with instead of --query. The query param for attribute API doesn't use Sentry query syntax, rather it's just searching attribute keys that appear with the queried keys on same spans, logs, etc
• No --cursor for now as the attribute API pagination works differently from other APIs (see comments in list.ts), so it wouldn't be consistent to add pagination as is. Instead attribute filtering is encouraged with --with/--search/--type

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Oct 23, 2026 4:26pm UTC

[BYK]

Pre-emptively blocking to do a quick design review (mostly UX)

[nikkikapadia]

Suggested change

	# Add descriptions, example values, and deprecation info
	# Show descriptions, example values, and deprecation info

[nikkikapadia]

Suggested change

	# Add descriptions, example values, and deprecation info
	# Show descriptions, example values, and deprecation info

[BYK]

There's a bit too much slop in this PR, not sure if the agent followed the repo conventions. It also duplicated a lot of existing functionality.

Finally, I'd like to understand why this API is such a snowflake and how can we align its query and pagination system with the rest. CLI can (and should) normalize the pagination so provide a unified and consistent interface but ideally this should already be done on the API side.

[BYK]

I think this should match the default period for the rest of the CLI endpoints

[lzhao-sentry]

Is that 7d? I

[sentry-junior]

Yep, 7d. The shared default is LIST_PERIOD_FLAG in packages/cli/src/lib/list-command.ts (default: "7d"). span list, trace list, replay list, the event list commands, and agent-conversation list all use it.

Simplest fix: use the shared flag and drop the local constant:

import { LIST_PERIOD_FLAG, PERIOD_ALIASES, /* ... */ } from "../../lib/list-command.js";

// flags:
period: LIST_PERIOD_FLAG,

That way, if the CLI-wide default changes, this command changes with it.

Not every command uses 7d. log list defaults to 30d (14d in trace mode), feedback list and trace logs use 14d, issue list and release list use 90d, and explore uses 24h. Still, span list and trace list are the closest siblings to attribute discovery, and they're 7d. Anyone who wants the MCP-style 14d window can pass --period 14d.

[lzhao-sentry]

Nvm ignore my comment, I found it.

[BYK]

I think we had this mapping somewhere else already? Probably in explore? We should use a single, unified list.

[lzhao-sentry]

The issue with using the explore mapping (and by extension some of the helpers) is that errors and replays are included. They don't use attributes, but tags

[sentry-junior]

Fair point. explore's map shouldn't be reused as-is, since errors and replays use tags, not attributes. That's an argument for sharing it differently, not for keeping a second copy, though. The two copies have already drifted: this PR accepts metric and tracemetrics as aliases, and explore doesn't.

Suggestion: move the dataset aliases into a shared module (e.g. lib/datasets.ts). It would hold one alias table plus a list of which datasets are trace-item datasets, and both commands would build their parsing and validation from it:

// lib/datasets.ts
const DATASET_ALIASES = {
  errors: "errors", error: "errors",
  spans: "spans", span: "spans",
  logs: "logs", log: "logs",
  metrics: "tracemetrics", metric: "tracemetrics", tracemetrics: "tracemetrics",
  replays: "replays", replay: "replays",
} as const;

/** Datasets backed by trace items, which have attributes rather than tags. */
export const TRACE_ITEM_DATASETS = ["spans", "logs", "metrics"] as const;

export const EXPLORE_DATASETS = ["errors", ...TRACE_ITEM_DATASETS, "replays"] as const;

export function buildDatasetParser<T extends readonly string[]>(allowed: T) { /* resolve alias, validate against allowed, throw ValidationError */ }
export function toUserDataset(apiName: string): string { /* reverse map for hints */ }

Then attribute list uses buildDatasetParser(TRACE_ITEM_DATASETS) and explore uses buildDatasetParser(EXPLORE_DATASETS). Both get the same aliases, the same error wording, and the same reverse mapping for hints. explore would also pick up the metric and tracemetrics aliases for free.

The other duplicated pieces I flagged (the type list, the parse/validate helpers) can live in the same module, or in a sibling module next to the existing trace-item API types.

[lzhao-sentry]

We could consolidate tags into this command? But I think the endgoal is to eventually only use attributes, and for the scope of the project this command falls under, we're focusing on the datasets that currently use attributes

[BYK]

Same as above

[BYK]

Again, all this is probably shared stuff between explore

[BYK]

Same as above, pretty sure we do this somewhere else.

[BYK]

I don't really understand the --with flag. It feels like a filter? We should standardise these. Also I think a better way might be to adopt what we are doing in #1575

We tend to stay away from flags and prefer positional arguments when it makes sense and I think here sentry attribute list org/ <filter> or just sentry attribute list <filter> feels more natural rather than having a --with or even --query flag.

[lzhao-sentry]

For --with, it takes attribute keys only and ignores values. So passing span.op will get all other attributes that occur with span.op, given that that span.op had any value. I think it's unique to attributes, so not sure how it would be best to handle it

I do think --search would fit better in sentry attribute list <filter> since it's substring matches for attribute keys

[BYK]

Again, this is existing functionality.

[BYK]

No idea what this tip is about?

[BYK]

This is not useful help. We need to tell what "attributes" are, where and how they might be useful. All this information, alias, examples etc has dedicated fields and the description/help/skills get auto generated from those. This is hacking and bypassing all that structured way.

[sentry-junior]

I re-reviewed at 2ebde76 against the earlier threads. Good progress. Fixed so far:

• --period now uses LIST_PERIOD_FLAG (7d).
• splitKeyList is gone in favor of parseFieldsList, which now keeps commas inside brackets and has a test. shellKey is gone in favor of shellQuote.
• The metrics tip is now a concrete sentry explore … -m <metric> -F <key> command, and the help now starts by saying what attributes are.

Still open:

• Examples are still hand-written. fullDescription has its own Examples: block, and fragments/commands/attribute.md has a ## Examples section. The "Generated Docs & Skills" section of packages/cli/AGENTS.md says examples belong in docs.examples ({ description, command }[], see agent-conversation/list.ts) so they show up in --help, the docs and the skill references. It also says fragments are only for prose the command metadata can't hold. Move both example lists into docs.examples and keep only the "Using Attribute Keys" prose in the fragment.
• Dataset handling is still a copy of explore's. DATASET_ALIASES, VALID_DATASETS, API_TO_USER_DATASET and parseDataset all exist in explore.ts too (around L92–122 and L168). The copies have already drifted: metric/tracemetrics work here but not in explore. I suggested a shared module with a trace-item subset in the L57 thread. That keeps this command limited to spans/logs/metrics without keeping a second copy.
• --with and --search are unchanged. That discussion is still going in the L145 thread. One more data point: buildWithQuery already turns --with k into has:k. Accepting has:<key> in a positional filter would therefore send the API the same query without a new flag. A plain positional term could replace --search, as long as it matches the way #1575's positional name filter matches.

On pagination: leaving out --cursor matches log list (noCursorFlag), and the comment explains why. Still, the per-type per_page plus trimming the extra look-ahead rows (dropLookAheadRows) works around the API's behavior. That's worth filing against the endpoint so the CLI can eventually page like the other list commands.

I didn't run the tests locally. The latest checks on this commit are green.

[sentry-junior]

Correction to my review above: I said the checks on 2ebde76 were green, but some were still running when I posted. Lint has since failed, in "Repository quality" and in "sentry". The test job only fails because those two did.

packages/cli/test/lib/api/trace-item-attributes.test.ts:49:9: Unexpected `await` of a non-Promise (non-"Thenable") value.

setAuthToken (src/lib/db/auth.ts) is synchronous now, so drop the await in that beforeEach, and the async along with it.

[BYK]

Please address Junior's comments.

[JoshuaKGoldberg]

Core logic and general usage LGTM! And the docs are nicely aligned too.

The @internal Exported for testing comments can go IMO, much of the logic they describe is in fact already tested on its own.

[JoshuaKGoldberg]

[Style] Nit: the past test had blank lines between AAA parts and this one doesn't. That one also did capturedUrl! while this one does capturedUrl?. Do you have a preference? It was just a little confusing for it not to be the same (I was wondering if that was intentional for some reason I was missing).

[JoshuaKGoldberg]

[Types] Nitty nit, I'm more posting this for fun than anything else ~ I'd use a type predicate to avoid the as assertions.

function isTraceAttributeValueType(
  value: string,
): value is TraceItemAttributeValueType {
  return VALID_TYPES.includes(value as TraceItemAttributeValueType);
}

Suggested change

	types.add(value as TraceItemAttributeValueType);
	if (!isTraceAttributeValueType(value)) {
	throw new ValidationError(
	`Invalid attribute type "${raw}". Must be one of: ${VALID_TYPES.join(", ")}`,
	"type",
	);
	}
	types.add(value);

There might be some benefit to the AIs to putting this in, so they prefer this pattern over less safe assertions... maybe? 🤷 definitely not a blocker at all IMO.

[JoshuaKGoldberg]

@internal Exported for testing

[Refactor] I don't generally believe in the concept of an "exported internal" helper. If it's such an important implementation detail that it needs to be replicated in tests, I think it deserves to be its own separately tested unit.

[sentry-junior]

I re-reviewed at 72773a3. This addresses the earlier design feedback:

• Datasets: lib/datasets.ts is now the single alias table, and explore and attribute list both build their parser from it with their own allowed list. That fixes the alias drift too.
• Filter: --with and --search are now one positional filter, parsed by the shared parseSearch (free text becomes substringMatch, has:<key> becomes query). Unsupported syntax, including globs, gets a clear error rather than being sent as a literal. Glob/fuzzy matching like #1575's can come later, per the TODO.
• Pagination: -c next/prev now works through the standard cursor stack and paginationHint, with a compound cursor holding one entry per type. I checked the hand-built 0:<offset>:0 resume cursor against TraceItemAttributesNamesPaginator in getsentry/sentry, which uses Cursor(0, offset ± limit, …) and reads only cursor.offset. So resuming at start + shownOfType is correct, and the test for rows cut by --limit covers it.
• Docs: the examples now live in docs.examples, and the fragment keeps only the "Using Attribute Keys" prose.

One thing still blocks: Repository quality is still failing on packages/cli/test/lib/api/trace-item-attributes.test.ts:49, the same await setAuthToken(...) as before. setAuthToken is synchronous, so drop the await, and the async on that beforeEach. Some other checks (sentry, warden, the NPM package) were still running when I posted.

[lzhao-sentry]

Not to sure about this part, is it better to wait for #1575 to land first and then rebase and add globbing/fuzzy search functionality?

[sentry-junior]

0fd8f82 drops the await and async from that beforeEach, which is what the lint error asked for. Nothing else changed since 72773a3, so I have nothing new to add on top of my previous review. Lint, tests and the macOS asset-catalog job were still running when I posted.

[sentry-warden]

Text filter rejects typed attribute keys containing brackets

parseAttributeFilter uses isGlobFilter, which treats [/] as glob metacharacters, so valid substring searches like tags[ or tags[cart.total,number] throw instead of querying the API. Restrict the glob check to */? (or skip it for attribute keys).

Evidence

• listCommand.func calls parseAttributeFilter(filter) for the positional text term.
• parseAttributeFilter rejects any name where isGlobFilter(name) is true (list.ts ~156–160).
• isGlobFilter matches [ and ] (list-filter.ts GLOB_CHARS_RE = /[*?[\]{}]/).
• This command’s own docs/examples use typed keys like tags[cart.total,number], and the attributes API accepts substringMatch values such as tags[.

_{Identified by Warden · code-review · WG7-2TA}