Documentation
¶
Index ¶
Constants ¶
const (
DefaultMatrixCapacity = 64
)
Variables ¶
This section is empty.
Functions ¶
func EnableTracking ¶
func EnableTracking(enabled bool)
EnableTracking enables performance tracking globally. HDR histogram for P95 latency is automatically enabled when tracking is enabled. By default, uses simple tracking mode (single global call stack) which is faster. This is sufficient for most Atmos commands which run in a single goroutine.
func ResetForTesting ¶
func ResetForTesting()
ResetForTesting clears the metrics registry. Intended for use in tests to ensure test isolation: this is process-wide state with no other reset path, so a test that enables tracking (and any real Track() calls it triggers, or that any other code in the same process makes while tracking happens to be on) permanently accumulates into the shared registry for the rest of the binary's run otherwise -- e.g. a heatmap-display test's own few tracked calls getting crowded out of the top-N display by hundreds of unrelated calls from whatever ran before it. Call this alongside EnableTracking, not as a replacement for disabling tracking when the test is done.
func Track ¶
func Track(atmosConfig *schema.AtmosConfiguration, name string) func()
Track returns a func you should defer to record duration for a Go function. Performance tracking is enabled via the `--heatmap` flag. Use `--heatmap` flag to display the collected metrics.
This function now tracks both total time (wall-clock) and self-time (excluding children). For recursive functions, each call is counted separately, but timing remains accurate. Example: ProcessYAML called 1,890 times recursively will show count=1,890 but accurate timing.
Note: `atmosConfig` parameter is reserved for future use.
func UseSimpleTracking ¶ added in v1.194.1
func UseSimpleTracking(enabled bool)
UseSimpleTracking enables or disables simple tracking mode. Simple mode uses a single global call stack (faster, no goroutine ID lookups). Use false for multi-goroutine scenarios to ensure accurate per-goroutine tracking.
Types ¶
type CallStack ¶ added in v1.194.1
type CallStack struct {
// contains filtered or unexported fields
}
CallStack tracks nested function calls for a single goroutine.
type Metric ¶
type Metric struct {
Name string
Count int64
Total time.Duration // Wall-clock time (includes children) - internal use only.
SelfTime time.Duration // Actual work time (excludes children) - used for all display metrics.
Max time.Duration // Max self-time (excludes children).
Hist *hdrhistogram.Histogram // Histogram for self-time percentiles (optional, nil if disabled).
}
Metric tracks performance data for a function. Total includes time spent in child function calls (wall-clock time) - used for internal tracking. SelfTime excludes time spent in child calls (actual work done in the function) - used for display. Display uses SelfTime to avoid double-counting time in nested/recursive calls.
type Row ¶
type Row struct {
Name string
Count int64
Total time.Duration // Sum of self-time across all calls (excludes children to avoid double-counting).
SelfTime time.Duration // Actual work time (excludes children) - same as Total for display purposes.
Avg time.Duration // Average self-time per call.
Max time.Duration // Max self-time (excludes children).
P95 time.Duration // 95th percentile of self-time (0 if HDR disabled).
}
Row represents a single function's performance metrics in the output.
type Snapshot ¶
func SnapshotTop ¶
func SnapshotTopFiltered ¶
SnapshotTopFiltered returns the top N functions sorted by the given field, filtering out functions with zero total time.
type StackFrame ¶ added in v1.194.1
type StackFrame struct {
// contains filtered or unexported fields
}
StackFrame represents a single frame in the call stack for tracking nested calls.
The childTime field is atomic (nanoseconds), not a plain time.Duration: simple-stack mode (trackWithSimpleStack) deliberately trusts goroutine ownership without verifying it for every nested call, for speed -- so when a second goroutine's calls do slip onto the shared simpleStack undetected (its documented "known limitation"), one goroutine's finish reading its own frame's childTime can race with a concurrently finishing call elsewhere in the (logically, at that point, shared) stack writing to what it resolves as its parent's childTime -- the same field on the same frame. That cross-goroutine mixing can still produce logically confused metrics (an accepted, pre-existing tradeoff -- see trackWithSimpleStack), but the field access itself must not be a data race regardless.
Source Files