Skip to content

feat(cli): Stream logs with sentry log tail so -f always means --fresh - #2442

Merged
BYK merged 6 commits into
mainfrom
fix/cli-cache-hint-refresh-flag
Nov 20, 2026
Merged

BYK merged 6 commits into
mainfrom
fix/cli-cache-hint-refresh-flag

Conversation

@sentry-junior

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

Copy link
Copy Markdown
Contributor

log list bound -f to --follow, so its cached footer said "use -f to refresh" and pointed at the wrong flag (user feedback CLI-516). It also made -f mean something different in log list than in every other list command.

What changes

  • New log tail streams new logs until Ctrl+C, for a project or a trace, like tail -f and heroku logs --tail. It takes -i/--interval (poll seconds, default 2), --query, --limit, --json (JSONL), and --fields.
  • log list fetches once, and -f is --fresh there like in every other list command. A hidden --follow errors with a pointer to log tail. This also removes the follow-only validation and the dual output shape from log list.
  • The cached footer names each command's own refresh flag, and skips the suggestion for commands without --fresh, such as log tail.
  • Target parsing and rendering shared by list and tail moved to src/commands/log/shared.ts.
  • log tail and dashboard view share one poll-interval parser and abortableSleep() from src/lib/polling.ts. dashboard view --refresh now rejects values like 30s or 1.5 instead of truncating them.

Keeping it from drifting

  • design/sentry-cli.md states the rules: -f means --fresh wherever a command can bypass the cache; live output is its own command, not a mode flag; and the SDK returns an AsyncIterable for exactly the invocations that stream. dashboard view --refresh is listed as the remaining gap.
  • Commands declare streaming themselves with streams in buildCommand: true on log tail, { flag: "refresh" } on dashboard view. The SDK generator reads the marker directly. sdk.run() must pick a return shape before it loads any command, so a generator step writes the markers (with each flag's alias, read from the command) to src/generated/streaming-commands.json. There is no hand-kept list. sdk.run() used to match streaming flags by name across all commands, which treated -f as streaming even where it meant --fresh, and missed dashboard view -r (it returned a Promise for a command that never ends).
  • A route-tree check runs every flag and alias of every registered command, hidden alias routes included, through sdk.run()'s streaming detector and compares the answer with that command's marker, and requires the generated file to match the commands. It also rejects any command that adds a stream-like flag (follow, watch, live, stream, tail, poll, refresh) without being a listed gap.
  • buildListCommand drops its noFreshAlias opt-out.

Breaking changes

  • Streaming moves from log list -f/--follow to log tail; the interval moves to --interval.
  • SDK: sdk.log.list({ follow }) becomes sdk.log.tail({ interval }).

Open question

  • Should dashboard view --refresh also get its own command? It doesn't conflict with -f, so it stays a documented gap for now.

via @BYK.

--

View Session [Sentry]

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
cli Ready Ready Preview Nov 20, 2026 9:12pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Nov 20, 2026 9:12pm UTC

Request Review

@sentry-junior
sentry-junior Bot marked this pull request as ready for review November 19, 2026 23:42
@sentry-junior
sentry-junior Bot requested a review from BYK November 19, 2026 23:43
@github-actions github-actions Bot added the risk: low PR risk score: low label Nov 19, 2026

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

Can we find another short version for --follow and keep -f more predictable here? Mostly a research question. Check all common unix tools for reference like curl, wget, tail, cat, less etc for inspiration

@sentry-junior

sentry-junior Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

Can we find another short version for --follow and keep -f more predictable here?

Here's what I found.

How other tools spell "follow"

Tool Follow / stream flag Notes
tail -f, --follow -F = --follow=name --retry
journalctl -f, --follow
docker logs / kubectl logs -f, --follow
less +F / F key "Forward forever; like tail -f"
heroku logs -t, --tail
aws logs tail, wrangler tail, gcloud … logs tail tail subcommand
watch -n, --interval repeats instead of following
curl -L (follow redirects), -N (no buffering) different meaning
wget, cat none

So for logs, -f = follow is close to universal. The only common alternatives are -F (tail), -t/--tail (heroku), and a tail subcommand.

What's free in sentry

  • -t is --period everywhere, and -w is --web, so --tail -t and --watch -w are out.
  • -F is free in log list. Elsewhere it's already --field (api, explore) and --format (local run/server), so it isn't globally unique either.
  • -L and -T aren't used by any command.

Options

  1. -F, --follow, then -f becomes --fresh like every other read command. It has the tail -F precedent and is the smallest change. I'd go with this one.
  2. A sentry log tail subcommand (the aws/wrangler/gcloud style). It can keep --follow/-F as an alias, and it gets streaming out of list's flags entirely.
  3. Leave -f as follow. That matches every log tool above, and this PR's hint already says --fresh there.

Breaking-change risk with 1 and 2

  • --follow takes an optional interval, but --fresh is a boolean. After the flip, sentry log list -f 5 would parse 5 as the target positional and fail confusingly, instead of streaming every 5s.
  • That pattern is in our docs, the generated skill reference, the command examples, and the "or -f to follow" hint. Agents copy those.
  • So I'd do the flip in two steps: first add -F and warn when -f is used in log list, then make -f mean --fresh in the next major.

Which way do you want to go? If it's option 1 or 2, should that live in this PR or a follow-up? This PR stands on its own either way: whatever alias ends up on --fresh, the footer follows it automatically.

@BYK

BYK commented Nov 20, 2026

Copy link
Copy Markdown
Member

I'm leaning towards option 2 but then we need to find some other places where we do this and document it properly. If option 2 makes things easier for log list then definitely go with that. If not I'm fine with sentry logs -F

sentry-junior Bot and others added 2 commits November 20, 2026 20:32
The cached-result footer hardcoded "use -f to refresh", but log list binds
-f to --follow, so the hint pointed at the wrong flag. buildCommand now
derives the flag from the command's final flags and aliases: the alias
that maps to --fresh, else --fresh, else no refresh suggestion at all.

Co-Authored-By: BYK <[email protected]>
Co-Authored-By: BYK <[email protected]>
`log list` bound `-f` to `--follow`, so the cached footer's "use -f to
refresh" pointed at the wrong flag there, and `-f` meant something
different in `log list` than in every other list command.

Live output now has its own command, like `tail -f` and `heroku logs
--tail`: `sentry log tail [target] [-i/--interval N]` covers project and
trace mode. `log list` fetches once, and `-f` is `--fresh` there too. A
hidden `--follow` on `log list` errors with a pointer to `log tail`.

To keep the rule from drifting:
- design/sentry-cli.md states it: `-f` is `--fresh` wherever a command
  can bypass the cache, and live output is its own command. It lists
  `dashboard view --refresh` as the remaining gap.
- A route-tree test fails when a command with `--fresh` binds `-f` to
  anything else, when a new command streams through a flag, or when a
  visible `--follow` comes back.
- `src/lib/streaming-commands.ts` is the one list of streaming commands
  and flags. The SDK generator types `sdk.log.tail()` as an
  AsyncIterable from it, and `sdk.run()` picks the same return shape
  from it. That also fixes `sdk.run(..., "-f")` streaming on commands
  where `-f` is `--fresh`.
- `buildListCommand` drops its `noFreshAlias` opt-out.

Co-Authored-By: BYK <[email protected]>
@sentry-junior

sentry-junior Bot commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

Went with option 2, since it does make log list simpler. It's in f3015ed:

  • sentry log tail [target] [-i N] streams for a project or a trace. log list fetches once, and -f is --fresh there like everywhere else. --follow is hidden on log list and errors with a pointer to log tail.
  • Dropping streaming from log list also drops the follow-only checks (--sort oldest, absolute --period), the bare-item vs. envelope output union, and the noFreshAlias opt-out in buildListCommand.

Other places that do this: I walked the route tree. dashboard view -r/--refresh is the only other command that switches to live output through a flag. It doesn't fight over -f, so I left it alone and listed it as a gap in design/sentry-cli.md. Happy to move it to its own command in a follow-up if you want. local run/server and monitor run are long-running by design, not list commands with a stream mode.

The search also turned up a second copy of the same bug: sdk.run() kept its own streaming-flag list that included -f, so sdk.run("issue", "list", "-f") returned an AsyncIterable. Now one module (src/lib/streaming-commands.ts) feeds both the SDK generator and sdk.run().

Documented / enforced:

  • design/sentry-cli.md rules: -f is --fresh wherever a command can bypass the cache, and live output is its own command, not a mode flag.
  • test/lib/short-flag-conventions.test.ts checks the real route tree. It fails if a command with --fresh binds -f elsewhere, if a new command streams through a flag (only the listed gap is allowed), or if a visible --follow returns.
  • Docs, the skill references, library-usage.md (sdk.log.tail({ interval: 5 })), and the README now point at log tail.

@github-actions github-actions Bot added risk: medium PR risk score: medium and removed risk: low PR risk score: low labels Nov 20, 2026
@sentry-junior sentry-junior Bot changed the title fix(cli): Name each command's own refresh flag in the cached footer feat(cli): Stream logs with sentry log tail so -f always means --fresh Nov 20, 2026
@sentry-junior
sentry-junior Bot requested a review from BYK November 20, 2026 20:34

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

Stale Bugbot comment from a previous run.

The route scanner accepts global flags before or between route segments
(`--json log tail`, `log --json tail`), but the streaming check only
looked at the first two arguments, so those layouts returned a Promise
for a command that never ends. Skip global flags the same way, from
`buildTopLevelFlags()`.

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

The search also turned up a second copy of the same bug: sdk.run() kept its own streaming-flag list that included -f, so sdk.run("issue", "list", "-f") returned an AsyncIterable. Now one module (src/lib/streaming-commands.ts) feeds both the SDK generator and sdk.run().

We should make this class of errors impossible either via lint rule or some tests on SDK generation etc.

Comment thread packages/cli/src/commands/log/tail.ts Resolved
Comment thread packages/cli/src/commands/log/tail.ts Resolved
Comment thread packages/cli/src/commands/log/tail.ts Resolved
{ description: "Stream logs (2-second poll interval)", run: "log tail" },
{
description: "Poll every 5 seconds",
run: "log tail --interval 5",

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.

Should we reuse the -r flag from the dashboard command for this? Or do we have any other precedent for the short version?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I looked for precedent. In the CLI, dashboard view -r/--refresh <seconds> is the only other poll interval. In Unix tools there's ping -i, watch -n, and tail -s/--sleep-interval, and vmstat/iostat take the interval as a positional. -n is already --limit here, so watch -n is out.

I kept -i/--interval for two reasons:

  • --refresh sitting next to --fresh (-f) is easy to mix up, and that's the kind of confusion this PR exists to fix.
  • In dashboard view, -r does two jobs: it turns streaming on and sets the interval. log tail always streams, so its flag only sets the interval, the same as ping -i.

If dashboard view gets its own live command (the gap in design/sentry-cli.md), I'd give it -i/--interval too so the two match. Your call though: switching log tail to -r/--refresh is a one-line change.

sdk.run() decided streaming from a global flag-name list, so a streaming
flag's short alias could collide with another command's alias. It also
missed `dashboard view -r`, which returned a Promise for a command that
never finishes.

STREAMING_COMMANDS is now a per-command table (always, or one flag plus
its alias). A test walks the whole route tree, hidden aliases included,
and checks every flag and alias of every command against
isStreamingInvocation(), and checks each table entry against the
command's own flag and alias definitions.

Also share the poll-interval parser and abortableSleep between log tail
and dashboard view, merge the two log tail item yielders, and name the
backfill and poll windows.

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

Reviewed by Cursor Bugbot for commit 3cd24d5. Configure here.

@sentry-junior
sentry-junior Bot requested a review from BYK November 20, 2026 21:01
--refresh streams only on dashboard view now, so issue list --refresh no
longer returns an AsyncIterable. Cover both --refresh and -r there.
@BYK
BYK enabled auto-merge (squash) November 20, 2026 21:05
Commands now mark themselves with `streams` in buildCommand: `true` for
log tail, `{ flag: "refresh" }` for dashboard view. The SDK generator
reads the marker directly. sdk.run() must choose a return shape before it
loads any command, so a new generator step writes the markers, with each
flag's alias read from the command, to src/generated/streaming-commands.json.
The hand-kept STREAMING_COMMANDS table is gone.

The route-tree test now checks sdk.run()'s answer for every flag and alias
of every command against that command's own marker, and that the
generated file is current.
@vercel
vercel Bot temporarily deployed to Preview – sentry-local November 20, 2026 21:12 Inactive
@BYK
BYK merged commit bc3b382 into main Nov 20, 2026
36 checks passed
@BYK
BYK deleted the fix/cli-cache-hint-refresh-flag branch November 20, 2026 21:24
Comment on lines +309 to +324
export function jsonTransformLogOutput(
data: LogOutput,
fields?: string[],
): ListEnvelope<LogLike> | Partial<LogLike> {
if (isLogListResult(data)) {
// Batch (single-fetch): return envelope with data + hasMore
const logList = data;
const items =
fields && fields.length > 0
? logList.logs.map((log) => filterFields(log, fields))
: logList.logs;
return { data: items, hasMore: logList.hasMore };
}
// Single item (follow mode): return bare object for JSONL
return fields && fields.length > 0 ? filterFields(data, fields) : data;
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

log tail --json emits a list envelope then bare JSONL objects

jsonTransformLogOutput turns any LogListResult into a { data, hasMore } envelope, but log tail also yields that shape for the first batch (trace mode or --fields), so --json is not uniform JSONL and pipelines like the documented jq 'select(.severity == "error")' drop the backfill. Yield bare items in tail (or only envelope for log list) so every JSON line is one log object.

Evidence
  • jsonTransformLogOutput maps every isLogListResult(data) path to { data, hasMore } and only bare LogLike values to single JSONL objects (comment claims that split is list vs follow).
  • yieldLogItems in tail.ts sets contextSent = !(context.traceId || context.extraFields?.length) and yields { ...context, logs: batch, hasMore: false } for the first non-empty batch when tracing or --fields is set.
  • Docs/skill example is log tail --json | jq 'select(.severity == "error")', which requires each line to be a log object; an envelope line has no .severity and drops the initial batch.
  • tail.test.ts locks the mixed shape in ("first batch as array, then bare items"), so the regression is currently asserted rather than prevented.
Also found at 1 additional location
  • packages/cli/src/commands/log/tail.ts:224-239

Identified by Warden · code-review · YGQ-QQ6

Comment on lines +206 to +209
if (newLogs && newLogs.length > 0) {
yield [...newLogs].reverse();
lastTimestamp = maxTimestamp(newLogs) ?? lastTimestamp;
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Poll cursor skips logs when more than --limit arrive between polls

Each poll advances lastTimestamp to the max timestamp of the returned page while fetches use the default newest-first sort, so a burst larger than --limit permanently drops the older new logs instead of catching up on later polls.

Evidence
  • After a non-empty poll, generateFollowLogs sets lastTimestamp = maxTimestamp(newLogs) ?? lastTimestamp.
  • Project-mode polls pass that value as afterTimestamp (timestamp_precise:>...); trace mode filters with timestamp_precise > lastTs.
  • listLogs / listTraceLogs default sort is newest-first (toApiSort(undefined) → -timestamp) with limit default 100 and no sort: "oldest" from log tail.
  • If >limit matching logs exist after the cursor, only the newest page is returned, the cursor jumps to that page’s max, and the unreturned older new logs never match a later poll.

Identified by Warden · code-review · FPW-46E

This branch was successfully deployed

1 active and 1 inactive deployments
Preview – cli — f5a29e27 Deployed Nov 20, 2026 by vercel[bot]
Preview – sentry-local — f5a29e27 Deployed Nov 20, 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.

1 participant