Repository navigation
feat(cli): Stream logs with sentry log tail so -f always means --fresh - #2442
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
BYK
left a comment
There was a problem hiding this comment.
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
Here's what I found. How other tools spell "follow"
So for logs, What's free in
Options
Breaking-change risk with 1 and 2
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 |
|
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 |
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 <126780+BYK@users.noreply.github.com> Co-Authored-By: BYK <burak.kaya@sentry.io>
`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 <burak.kaya@sentry.io>
00229c7 to
f3015ed
Compare
|
Went with option 2, since it does make
Other places that do this: I walked the route tree. The search also turned up a second copy of the same bug: Documented / enforced:
|
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
left a comment
There was a problem hiding this comment.
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.
| { description: "Stream logs (2-second poll interval)", run: "log tail" }, | ||
| { | ||
| description: "Poll every 5 seconds", | ||
| run: "log tail --interval 5", |
There was a problem hiding this comment.
Should we reuse the -r flag from the dashboard command for this? Or do we have any other precedent for the short version?
There was a problem hiding this comment.
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:
--refreshsitting next to--fresh(-f) is easy to mix up, and that's the kind of confusion this PR exists to fix.- In
dashboard view,-rdoes two jobs: it turns streaming on and sets the interval.log tailalways streams, so its flag only sets the interval, the same asping -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.
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.
Reviewed by Cursor Bugbot for commit 3cd24d5. Configure here.
--refresh streams only on dashboard view now, so issue list --refresh no longer returns an AsyncIterable. Cover both --refresh and -r there.
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.
| 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; | ||
| } |
There was a problem hiding this comment.
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
jsonTransformLogOutputmaps everyisLogListResult(data)path to{ data, hasMore }and only bareLogLikevalues to single JSONL objects (comment claims that split is list vs follow).yieldLogItemsintail.tssetscontextSent = !(context.traceId || context.extraFields?.length)and yields{ ...context, logs: batch, hasMore: false }for the first non-empty batch when tracing or--fieldsis 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.severityand drops the initial batch. tail.test.tslocks 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
| if (newLogs && newLogs.length > 0) { | ||
| yield [...newLogs].reverse(); | ||
| lastTimestamp = maxTimestamp(newLogs) ?? lastTimestamp; | ||
| } |
There was a problem hiding this comment.
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,
generateFollowLogssetslastTimestamp = maxTimestamp(newLogs) ?? lastTimestamp. - Project-mode polls pass that value as
afterTimestamp(timestamp_precise:>...); trace mode filters withtimestamp_precise > lastTs. listLogs/listTraceLogsdefault sort is newest-first (toApiSort(undefined)→-timestamp) withlimitdefault 100 and nosort: "oldest"fromlog 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

log listbound-fto--follow, so its cached footer said "use -f to refresh" and pointed at the wrong flag (user feedback CLI-516). It also made-fmean something different inlog listthan in every other list command.What changes
log tailstreams new logs until Ctrl+C, for a project or a trace, liketail -fandheroku logs --tail. It takes-i/--interval(poll seconds, default 2),--query,--limit,--json(JSONL), and--fields.log listfetches once, and-fis--freshthere like in every other list command. A hidden--followerrors with a pointer tolog tail. This also removes the follow-only validation and the dual output shape fromlog list.--fresh, such aslog tail.listandtailmoved tosrc/commands/log/shared.ts.log tailanddashboard viewshare one poll-interval parser andabortableSleep()fromsrc/lib/polling.ts.dashboard view --refreshnow rejects values like30sor1.5instead of truncating them.Keeping it from drifting
design/sentry-cli.mdstates the rules:-fmeans--freshwherever a command can bypass the cache; live output is its own command, not a mode flag; and the SDK returns anAsyncIterablefor exactly the invocations that stream.dashboard view --refreshis listed as the remaining gap.streamsinbuildCommand:trueonlog tail,{ flag: "refresh" }ondashboard 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) tosrc/generated/streaming-commands.json. There is no hand-kept list.sdk.run()used to match streaming flags by name across all commands, which treated-fas streaming even where it meant--fresh, and misseddashboard view -r(it returned a Promise for a command that never ends).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.buildListCommanddrops itsnoFreshAliasopt-out.Breaking changes
log list -f/--followtolog tail; the interval moves to--interval.sdk.log.list({ follow })becomessdk.log.tail({ interval }).Open question
dashboard view --refreshalso get its own command? It doesn't conflict with-f, so it stays a documented gap for now.via @BYK.
--
View Session [Sentry]