README
¶
bldr trace
bldr trace reads a Go runtime trace file and prints text-first timing analysis
for user-defined trace tasks. It was tracetool in the instrument repo. The
same command is spacewave-dev trace in an app built on spacewave.
It is designed for the cases where the default go tool trace UI is too heavy
or too interactive for the question at hand. Instead of hunting through the web
UI, you can get a compact hot-path summary directly in the terminal.
What It Outputs
bldr trace produces two complementary views:
- A hot path table showing task name, count, total wall time, and min / p50 / p99 / max.
- A critical path tree showing how the slowest path is nested.
Those two views answer different questions:
- "What consumed the most time overall?"
- "Inside the slow operation, what was it actually blocked on?"
The table is useful for spotting amplification, contention, and heavy singleton work. The tree is useful for finding the actual blocking chain inside an end-to-end slow operation.
bldr trace streams the trace once and keeps only the recorded tasks, so memory
grows with the task count rather than the trace size. Use -task on large traces
to keep that count small.
If a task shows a large (untraced) gap, that usually means the instrumentation
inside that region is still too coarse and should be refined.
Build
From the spacewave repo root:
go build -o ~/company/bin/bldr ./bldr/cmd/bldr
You can also run it directly without building:
go run ./bldr/cmd/bldr trace <trace-file>
Usage
bldr trace [flags] <trace-file>
Current flags:
-tableShow the hot path table. Default:true.-treeShow the critical path tree. Default:true.-logsShow runtime/trace log events grouped by category and message. Default:false.-task stringRecord only tasks whose name has the given prefix, plus their descendants. Child tasks keep their own names, so-task "db/"also reports the tasks adb/task starts.-min durationOnly include task types withmax >= duration.-top intShow the top N task types in the table. Default:30. Use0for all.-allShow all task types in the table, overriding the top-N limit.-root stringRoot the tree at the first task matching the given name prefix. By default, the tree is rooted at the trace's slowest critical-path task.
Common Examples
Show the default summary:
bldr trace trace.out
Show only the table and include every task type:
bldr trace -all -tree=false trace.out
Focus on one subsystem by task prefix:
bldr trace -task "storage/" trace.out
Only show slower task types:
bldr trace -min 100ms trace.out
Show only the tree and root it at a specific task:
bldr trace -table=false -root "app/request" trace.out
Show only runtime/trace log events:
bldr trace -table=false -tree=false -logs trace.out
How To Read The Output
Hot path table
The table includes:
CountTotalMinP50P99Max
Typical patterns:
- High
Count+ highTotalUsually amplification. The task is individually cheap but runs too many times. - Small
P50+ much largerP99/MaxUsually contention, queuing, or intermittent blocking. - Low
Count+ highP50Usually one expensive operation that needs direct optimization.
Critical path tree
The tree shows nested tasks with parent-relative percentages. Follow the highest-percentage chain downward to find the actual blocking path.
This is especially useful when the table tells you a subsystem is expensive, but you still need to know which nested child actually dominates the slow user action or request.
Why Use It
The main benefit of bldr trace is iteration speed.
It makes it easy to:
- inspect a trace without opening a browser UI
- compare before/after traces during optimization work
- paste findings into notes, issues, or reviews
- identify whether the problem is amplification, contention, one heavy commit, or missing instrumentation
It does not replace other profiling tools. It complements them by making Go runtime trace data much easier to inspect in normal development workflows.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WriteLogs ¶
func WriteLogs(w io.Writer, result *TraceResult)
WriteLogs writes runtime/trace log events grouped by category and message.
func WriteTable ¶
func WriteTable(w io.Writer, result *TraceResult, topN int)
WriteTable writes the hot path table to w. Shows at most topN task types (0 = no limit).
Types ¶
type Options ¶
type Options struct {
// TaskPrefix keeps only tasks whose name has this prefix, plus their
// descendants. Empty keeps every task.
TaskPrefix string
}
Options selects the tasks Analyze records.
type TaskNode ¶
type TaskNode struct {
Name string
Duration time.Duration
ParentPct float64 // duration / parent.Duration * 100
TaskID parser.TaskID // original task ID
Children []*TaskNode
}
TaskNode represents a single task instance in the critical path tree.
type TaskTypeStats ¶
type TaskTypeStats struct {
Name string
Count int
Complete int
Total time.Duration
Min time.Duration
Max time.Duration
P50 time.Duration
P99 time.Duration
}
TaskTypeStats holds aggregated statistics for all instances of a task type.
type TraceResult ¶
type TraceResult struct {
// Duration is the total trace duration.
Duration time.Duration
// TaskCount is the total number of task instances.
TaskCount int
// IncompleteCount is the number of tasks without an End event.
IncompleteCount int
// TypeStats holds per-task-type aggregated statistics, sorted by TotalTime desc.
TypeStats []*TaskTypeStats
// Logs holds runtime/trace log events grouped by category and message.
Logs []*LogStats
// CriticalPath is the tree rooted at the slowest complete root task.
CriticalPath *TaskNode
}
TraceResult holds the parsed and analyzed trace data.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
raw
Package raw provides an interface to interpret and emit Go execution traces.
|
Package raw provides an interface to interpret and emit Go execution traces. |
|
tracev2
Package tracev2 contains definitions for the v2 execution trace wire format.
|
Package tracev2 contains definitions for the v2 execution trace wire format. |