Skip to content

feat(cli): add explore time series - #1657

Open
betegon wants to merge 4 commits into
mainfrom
bt/cli-explore-time-series
Open

betegon wants to merge 4 commits into
mainfrom
bt/cli-explore-time-series

Conversation

@betegon

@betegon betegon commented Oct 25, 2026 •

Copy link
Copy Markdown
Member

Add explore --time-series <auto|interval> (-b) to inspect when an aggregate changes using the existing target, dataset, filters, and time range. auto selects a supported bucket width for the requested range; an explicit duration fixes the width. Each invocation returns a snapshot and exits. Omitting the flag preserves tabular queries, and --period (-t) continues to control the overall range.

sentry explore my-org/my-project -t 1h -b 15m
sentry explore my-org/my-project --dataset spans -F "p95(span.duration)" --time-series auto --period 24h --json

Human output shows a UTC table per aggregate and marks incomplete buckets. JSON preserves values, units, sampling, completeness, and ingestion metadata, including string and null values. The initial scope covers ungrouped aggregates for errors, spans, logs, and metrics; table-only flags are rejected in temporal mode. Automatic intervals grow when needed to stay within the bucket budget, while explicit intervals are never silently changed.

Includes generated documentation and coverage through the public SDK and real CLI HTTP flow. The SDK exposes timeSeries: "auto" or a duration string. Time series retain existing boolean-query scoping, metric-expression validation, and field-error recovery.

Validation: workspace typechecks and lint passed. The focused command, interval, SDK, and E2E checks passed (98 tests), including -b combined with -t, automatic and explicit intervals, missing/invalid values, JSON metadata, and --fields projection.

The full workspace run passed all non-CLI suites and 11,438 CLI tests, but is not fully green locally. The musl installer fixture has an established macOS baseline failure, and asset-catalog integration requires the unavailable Xcode actool. An unchanged issue-integration test also failed in the broad run; its entire 63-test suite passed on an isolated retry without edits. No live production query was repeated for this flag-only revision.

@vercel

vercel Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

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

1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Oct 26, 2026 7:50pm UTC

Request Review

Comment thread packages/cli/src/commands/explore.ts
Comment thread packages/cli/src/lib/explore-timeseries.ts Outdated
@betegon
betegon marked this pull request as ready for review October 26, 2026 15:07
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Oct 26, 2026

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

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 85eace2. Configure here.

Comment thread packages/cli/src/lib/formatters/explore-timeseries.ts
@betegon
betegon force-pushed the bt/cli-explore-time-series branch from 85eace2 to 93f1f55 Compare October 26, 2026 15:24

@BYK BYK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Sorry but this is bad API design as the new flags make no sense on their own. So we should have a single flag, something like --time-buckets/-b which accepts what --interval takes now and enables time series mode (so dropping --time-series).

LMK if I'm missing anything.

@betegon

betegon commented Oct 26, 2026

Copy link
Copy Markdown
Member Author

@BYK not missing anything, I get your point but I wanted to use the time-series naming to adhere to Sentry's UI.

i could see:

sentry explore org/project --time-series auto
sentry explore org/project --time-series 15m

and using -b as -t is already taken

@BYK

BYK commented Oct 26, 2026

Copy link
Copy Markdown
Member

Fine with --time-series too. I'm just against 2 flags that require each other and cannot be used independently.

@betegon
betegon requested a review from BYK October 26, 2026 20:14
@betegon
betegon force-pushed the bt/cli-explore-time-series branch from d03a3a4 to fd9eeea Compare October 26, 2026 20:15

@BYK BYK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think we should use our built-in graphing engine that we use over at dasboard rendering for this btw.


## Time series

Use `--time-series auto` (`-b auto`) to see how an aggregate changes over time. The target,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Would it be possible to make auto optional so one can simply do --time-series or -b?

type Bucket = TimeSeries["values"][number];

/** Format an epoch-millisecond timestamp without depending on local timezone. */
function formatUtcTimestamp(timestamp: number): string {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Don't we have shared helpers for this stuff?

This branch was previously deployed

1 inactive (outdated) deployment
Preview — d03a3a45 Deployed Oct 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants