Skip to content

Commit 17e3326

Browse files
t3dotggclaude
andcommitted
refactor(cli): tidy t3 trace summary docs and tests
Drop a redundant Math.floor before date formatting, make the stream comment match what streaming bounds, assert that blank lines are not counted as skipped, and shorten the docs section. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 4b0897e commit 17e3326

3 files changed

Lines changed: 10 additions & 11 deletions

File tree

‎apps/server/src/cli/trace.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ it("reports count, rate, percentiles, and exits per span name", () => {
3838
),
3939
);
4040
const summarizer = makeTraceSpanSummary();
41-
[...refreshes, span("probe", 2_500, 10 * MINUTE_MS), ""].forEach(summarizer.addLine);
41+
[...refreshes, span("probe", 2_500, 10 * MINUTE_MS)].forEach(summarizer.addLine);
4242
const summary = summarizer.finish();
4343

4444
assert.strictEqual(summary.spanCount, 11);
@@ -71,6 +71,7 @@ it("drops spans that ended before the window and counts unreadable lines", () =>
7171
const summarizer = makeTraceSpanSummary(MINUTE_MS);
7272
[
7373
span("old", 1, 0),
74+
"",
7475
"{not json",
7576
JSON.stringify({ name: "no-duration" }),
7677
// Ends past the largest Date, so the report could not print it.

‎apps/server/src/cli/trace.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ function formatTraceSummary(
137137
]);
138138
const table = [header, ...rows];
139139
const widths = header.map((_, column) => Math.max(...table.map((row) => row[column]!.length)));
140-
const formatIso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(Math.floor(ms)));
140+
const formatIso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms));
141141
return [
142142
`${summary.spanCount} spans ended from ${formatIso(summary.firstEndMs)} to ${formatIso(summary.lastEndMs)} (${summary.minutes.toFixed(1)} min).`,
143143
...(summary.skippedLineCount > 0
@@ -187,8 +187,7 @@ const traceSummaryCommand = Command.make("summary", {
187187
? (yield* Clock.currentTimeMillis) - Duration.toMillis(flags.since.value)
188188
: undefined;
189189
const summarizer = makeTraceSpanSummary(sinceMs);
190-
// Stream each file line by line. Only one chunk of text is in memory at a
191-
// time, so memory does not grow with the size of the trace files.
190+
// Stream each file so only one chunk of text is in memory at a time.
192191
yield* Effect.forEach(
193192
toRotatedTracePaths(traceFilePath, yield* traceMaxFilesConfig),
194193
(path) =>

‎docs/operations/observability.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,18 +65,17 @@ request.
6565
#### Summarize the trace file
6666

6767
`t3 trace summary` reads the trace file and its rotated backups directly, so it works while the
68-
server is stalled or stopped. It prints one row per span name, busiest first: count, spans per
69-
minute, p50, p90, max, and the number of interrupted and failed exits. Use it to measure background
70-
work or to compare two builds.
68+
server is stalled or stopped. It prints counts, rates, and latency percentiles per span name. Use
69+
it to measure background work or to compare two builds.
7170

7271
```bash
7372
t3 trace summary --since 30m --limit 40
7473
```
7574

76-
It reads `T3CODE_TRACE_FILE` and `T3CODE_TRACE_MAX_FILES` if set, else
77-
`<home>/userdata/logs/server.trace.ndjson` for `--base-dir` or `T3CODE_HOME`. For a dev run or a
78-
copied file, set `T3CODE_TRACE_FILE`. `--since` keeps spans that ended in that window
79-
before now. The rate is per minute between the first and last span end.
75+
It reads `T3CODE_TRACE_FILE` if set, else `<home>/userdata/logs/server.trace.ndjson` for
76+
`--base-dir` or `T3CODE_HOME`, plus the `T3CODE_TRACE_MAX_FILES` rotated backups. For a dev run or
77+
a copied file, set `T3CODE_TRACE_FILE`. `--since 30m` keeps spans that ended in the last 30
78+
minutes. The rate is per minute between the first and last span end.
8079

8180
### Metrics
8281

0 commit comments

Comments
 (0)