Documentation ¶
Index ¶
- Constants
- Variables
- func IsSystemGoroutine(entryFn string) bool
- func MutatorUtilizationV2(events []Event, flags UtilFlags) [][]MutatorUtil
- func RelatedGoroutinesV2(events []Event, goid GoID) map[GoID]struct{}
- type Event
- func (e Event) Experimental() ExperimentalEvent
- func (e Event) Goroutine() GoID
- func (e Event) Kind() EventKind
- func (e Event) Label() Label
- func (e Event) Log() Log
- func (e Event) Metric() Metric
- func (e Event) Proc() ProcID
- func (e Event) Range() Range
- func (e Event) RangeAttributes() []RangeAttribute
- func (e Event) Region() Region
- func (e Event) Stack() Stack
- func (e Event) StateTransition() StateTransition
- func (e Event) String() string
- func (e Event) Task() Task
- func (e Event) Thread() ThreadID
- func (e Event) Time() Time
- type EventKind
- type ExperimentalBatch
- type ExperimentalData
- type ExperimentalEvent
- type Frame
- type GoID
- type GoState
- type GoroutineExecStats
- type GoroutineSummary
- type Label
- type Log
- type MMUCurve
- type Metric
- type MutatorUtil
- type ProcID
- type ProcState
- type Range
- type RangeAttribute
- type Reader
- type Region
- type ResourceID
- type ResourceKind
- type Stack
- type StackFrame
- type StateTransition
- type Summarizer
- type Summary
- type Task
- type TaskID
- type ThreadID
- type Time
- type UserRegionSummary
- type UserTaskSummary
- type UtilFlags
- type UtilWindow
- type Value
- type ValueKind
Constants ¶
const ( // NoTask indicates the lack of a task. NoTask = TaskID(^uint64(0)) // BackgroundTask is the global task that events are attached to if there was // no other task in the context at the point the event was emitted. BackgroundTask = TaskID(0) )
const ( // Special P identifiers: FakeP = 1000000 + iota TimerP // depicts timer unblocks NetpollP // depicts network unblocks SyscallP // depicts returns from syscalls GCP // depicts GC state ProfileP // depicts recording of CPU profile samples )
const ( EvNone = 0 // unused EvBatch = 1 // start of per-P batch of events [pid, timestamp] EvFrequency = 2 // contains tracer timer frequency [frequency (ticks per second)] EvStack = 3 // stack [stack id, number of PCs, array of {PC, func string ID, file string ID, line}] EvGomaxprocs = 4 // current value of GOMAXPROCS [timestamp, GOMAXPROCS, stack id] EvProcStart = 5 // start of P [timestamp, thread id] EvProcStop = 6 // stop of P [timestamp] EvGCStart = 7 // GC start [timestamp, seq, stack id] EvGCDone = 8 // GC done [timestamp] EvSTWStart = 9 // GC mark termination start [timestamp, kind] EvSTWDone = 10 // GC mark termination done [timestamp] EvGCSweepStart = 11 // GC sweep start [timestamp, stack id] EvGCSweepDone = 12 // GC sweep done [timestamp, swept, reclaimed] EvGoCreate = 13 // goroutine creation [timestamp, new goroutine id, new stack id, stack id] EvGoStart = 14 // goroutine starts running [timestamp, goroutine id, seq] EvGoEnd = 15 // goroutine ends [timestamp] EvGoStop = 16 // goroutine stops (like in select{}) [timestamp, stack] EvGoSched = 17 // goroutine calls Gosched [timestamp, stack] EvGoPreempt = 18 // goroutine is preempted [timestamp, stack] EvGoSleep = 19 // goroutine calls Sleep [timestamp, stack] EvGoBlock = 20 // goroutine blocks [timestamp, stack] EvGoUnblock = 21 // goroutine is unblocked [timestamp, goroutine id, seq, stack] EvGoBlockSend = 22 // goroutine blocks on chan send [timestamp, stack] EvGoBlockRecv = 23 // goroutine blocks on chan recv [timestamp, stack] EvGoBlockSelect = 24 // goroutine blocks on select [timestamp, stack] EvGoBlockSync = 25 // goroutine blocks on Mutex/RWMutex [timestamp, stack] EvGoBlockCond = 26 // goroutine blocks on Cond [timestamp, stack] EvGoBlockNet = 27 // goroutine blocks on network [timestamp, stack] EvGoSysCall = 28 // syscall enter [timestamp, stack] EvGoSysExit = 29 // syscall exit [timestamp, goroutine id, seq, real timestamp] EvGoSysBlock = 30 // syscall blocks [timestamp] EvGoWaiting = 31 // denotes that goroutine is blocked when tracing starts [timestamp, goroutine id] EvGoInSyscall = 32 // denotes that goroutine is in syscall when tracing starts [timestamp, goroutine id] EvHeapAlloc = 33 // gcController.heapLive change [timestamp, heap live bytes] EvHeapGoal = 34 // gcController.heapGoal change [timestamp, heap goal bytes] EvTimerGoroutine = 35 // denotes timer goroutine [timer goroutine id] EvFutileWakeup = 36 // denotes that the previous wakeup of this goroutine was futile [timestamp] EvString = 37 // string dictionary entry [ID, length, string] EvGoStartLocal = 38 // goroutine starts running on the same P as the last event [timestamp, goroutine id] EvGoUnblockLocal = 39 // goroutine is unblocked on the same P as the last event [timestamp, goroutine id, stack] EvGoSysExitLocal = 40 // syscall exit on the same P as the last event [timestamp, goroutine id, real timestamp] EvGoStartLabel = 41 // goroutine starts running with label [timestamp, goroutine id, seq, label string id] EvGoBlockGC = 42 // goroutine blocks on GC assist [timestamp, stack] EvGCMarkAssistStart = 43 // GC mark assist start [timestamp, stack] EvGCMarkAssistDone = 44 // GC mark assist done [timestamp] EvUserTaskCreate = 45 // trace.NewTask [timestamp, internal task id, internal parent id, name string, stack] EvUserTaskEnd = 46 // end of task [timestamp, internal task id, stack] EvUserRegion = 47 // trace.WithRegion [timestamp, internal task id, mode(0:start, 1:end), name string, stack] EvUserLog = 48 // trace.Log [timestamp, internal id, key string id, stack, value string] EvCPUSample = 49 // CPU profiling sample [timestamp, real timestamp, real P id (-1 when absent), goroutine id, stack] EvCount = 50 )
Event types in the trace. Verbatim copy from src/runtime/trace.go with the "trace" prefix removed.
const NoGoroutine = GoID(-1)
NoGoroutine indicates that the relevant events don't correspond to any goroutine in particular.
const NoProc = ProcID(-1)
NoProc indicates that the relevant events don't correspond to any P in particular.
const NoThread = ThreadID(-1)
NoThread indicates that the relevant events don't correspond to any thread in particular.
Variables ¶
var NoStack = Stack{}
NoStack is a sentinel value that can be compared against any Stack value, indicating a lack of a stack trace.
Functions ¶
func IsSystemGoroutine ¶ added in go1.19
func MutatorUtilizationV2 ¶ added in go1.22.0
func MutatorUtilizationV2(events []Event, flags UtilFlags) [][]MutatorUtil
MutatorUtilizationV2 returns a set of mutator utilization functions for the given v2 trace, passed as an io.Reader. Each function will always end with 0 utilization. The bounds of each function are implicit in the first and last event; outside of these bounds each function is undefined.
If the UtilPerProc flag is not given, this always returns a single utilization function. Otherwise, it returns one function per P.
func RelatedGoroutinesV2 ¶ added in go1.22.0
RelatedGoroutinesV2 finds a set of goroutines related to goroutine goid for v2 traces. The association is based on whether they have synchronized with each other in the Go scheduler (one has unblocked another).
Types ¶
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event represents a single event in the trace.
func (Event) Experimental ¶ added in go1.23.0
func (e Event) Experimental() ExperimentalEvent
Experimental returns a view of the raw event for an experimental event.
Panics if Kind != EventExperimental.
func (Event) Goroutine ¶ added in go1.23.0
Goroutine returns the ID of the goroutine that was executing when this event happened. It describes part of the execution context for this event.
Note that for goroutine state transitions this always refers to the state before the transition. For example, if a goroutine is just starting to run on this thread and/or proc, then this will return NoGoroutine. In this case, the goroutine starting to run will be can be found at Event.StateTransition().Resource.
func (Event) Label ¶ added in go1.23.0
Label returns details about a Label event.
Panics if Kind != EventLabel.
func (Event) Log ¶ added in go1.23.0
Log returns details about a Log event.
Panics if Kind != EventLog.
func (Event) Metric ¶ added in go1.23.0
Metric returns details about a Metric event.
Panics if Kind != EventMetric.
func (Event) Proc ¶ added in go1.23.0
Proc returns the ID of the proc this event event pertains to.
Note that for proc state transitions this always refers to the state before the transition. For example, if a proc is just starting to run on this thread, then this will return NoProc.
func (Event) Range ¶ added in go1.23.0
Range returns details about an EventRangeBegin, EventRangeActive, or EventRangeEnd event.
Panics if Kind != EventRangeBegin, Kind != EventRangeActive, and Kind != EventRangeEnd.
func (Event) RangeAttributes ¶ added in go1.23.0
func (e Event) RangeAttributes() []RangeAttribute
RangeAttributes returns attributes for a completed range.
Panics if Kind != EventRangeEnd.
func (Event) Region ¶ added in go1.23.0
Region returns details about a RegionBegin or RegionEnd event.
Panics if Kind != EventRegionBegin and Kind != EventRegionEnd.
func (Event) Stack ¶ added in go1.23.0
Stack returns a handle to a stack associated with the event.
This represents a stack trace at the current moment in time for the current execution context.
func (Event) StateTransition ¶ added in go1.23.0
func (e Event) StateTransition() StateTransition
StateTransition returns details about a StateTransition event.
Panics if Kind != EventStateTransition.
func (Event) String ¶ added in go1.11
String returns the event as a human-readable string.
The format of the string is intended for debugging and is subject to change.
func (Event) Task ¶ added in go1.23.0
Task returns details about a TaskBegin or TaskEnd event.
Panics if Kind != EventTaskBegin and Kind != EventTaskEnd.
func (Event) Thread ¶ added in go1.23.0
Thread returns the ID of the thread this event pertains to.
Note that for thread state transitions this always refers to the state before the transition. For example, if a thread is just starting to run, then this will return NoThread.
Note: tracking thread state is not currently supported, so this will always return a valid thread ID. However thread state transitions may be tracked in the future, and callers must be robust to this possibility.
type EventKind ¶ added in go1.23.0
type EventKind uint16
EventKind indicates the kind of event this is.
Use this information to obtain a more specific event that allows access to more detailed information.
const ( EventBad EventKind = iota // EventKindSync is an event that indicates a global synchronization // point in the trace. At the point of a sync event, the // trace reader can be certain that all resources (e.g. threads, // goroutines) that have existed until that point have been enumerated. EventSync // EventMetric is an event that represents the value of a metric at // a particular point in time. EventMetric // EventLabel attaches a label to a resource. EventLabel // EventStackSample represents an execution sample, indicating what a // thread/proc/goroutine was doing at a particular point in time via // its backtrace. // // Note: Samples should be considered a close approximation of // what a thread/proc/goroutine was executing at a given point in time. // These events may slightly contradict the situation StateTransitions // describe, so they should only be treated as a best-effort annotation. EventStackSample // EventRangeBegin and EventRangeEnd are a pair of generic events representing // a special range of time. Ranges are named and scoped to some resource // (identified via ResourceKind). A range that has begun but has not ended // is considered active. // // EvRangeBegin and EvRangeEnd will share the same name, and an End will always // follow a Begin on the same instance of the resource. The associated // resource ID can be obtained from the Event. ResourceNone indicates the // range is globally scoped. That is, any goroutine/proc/thread can start or // stop, but only one such range may be active at any given time. // // EventRangeActive is like EventRangeBegin, but indicates that the range was // already active. In this case, the resource referenced may not be in the current // context. EventRangeBegin EventRangeActive EventRangeEnd // EvTaskBegin and EvTaskEnd are a pair of events representing a runtime/trace.Task. EventTaskBegin EventTaskEnd // EventRegionBegin and EventRegionEnd are a pair of events represent a runtime/trace.Region. EventRegionBegin EventRegionEnd // EventLog represents a runtime/trace.Log call. EventLog // EventStateTransition represents a state change for some resource. EventStateTransition // EventExperimental is an experimental event that is unvalidated and exposed in a raw form. // Users are expected to understand the format and perform their own validation. These events // may always be safely ignored. EventExperimental )
type ExperimentalBatch ¶ added in go1.23.0
type ExperimentalBatch struct { // Thread is the ID of the thread that produced a packet of data. Thread ThreadID // Data is a packet of unparsed data all produced by one thread. Data []byte }
ExperimentalBatch represents a packet of unparsed data along with metadata about that packet.
type ExperimentalData ¶ added in go1.23.0
type ExperimentalData struct { // Batches contain the actual experimental data, along with metadata about each batch. Batches []ExperimentalBatch }
ExperimentalData represents some raw and unparsed sidecar data present in the trace that is associated with certain kinds of experimental events. For example, this data may contain tables needed to interpret ExperimentalEvent arguments, or the ExperimentEvent could just be a placeholder for a differently encoded event that's actually present in the experimental data.
type ExperimentalEvent ¶ added in go1.23.0
type ExperimentalEvent struct { // Name is the name of the event. Name string // ArgNames is the names of the event's arguments in order. // This may refer to a globally shared slice. Copy before mutating. ArgNames []string // Args contains the event's arguments. Args []uint64 // Data is additional unparsed data that is associated with the experimental event. // Data is likely to be shared across many ExperimentalEvents, so callers that parse // Data are encouraged to cache the parse result and look it up by the value of Data. Data *ExperimentalData }
ExperimentalEvent presents a raw view of an experimental event's arguments and their names.
type GoID ¶ added in go1.23.0
type GoID int64
GoID is the runtime-internal G structure's goid field. This is unique for each goroutine.
type GoState ¶ added in go1.23.0
type GoState uint8
GoState represents the state of a goroutine.
New GoStates may be added in the future. Users of this type must be robust to that possibility.
const ( GoUndetermined GoState = iota // No information is known about the goroutine. GoNotExist // Goroutine does not exist. GoRunnable // Goroutine is runnable but not running. GoRunning // Goroutine is running. GoWaiting // Goroutine is waiting on something to happen. GoSyscall // Goroutine is in a system call. )
type GoroutineExecStats ¶ added in go1.22.0
type GoroutineExecStats struct { // These stats are all non-overlapping. ExecTime time.Duration SchedWaitTime time.Duration BlockTimeByReason map[string]time.Duration SyscallTime time.Duration SyscallBlockTime time.Duration // TotalTime is the duration of the goroutine's presence in the trace. // Necessarily overlaps with other stats. TotalTime time.Duration // Total time the goroutine spent in certain ranges; may overlap // with other stats. RangeTime map[string]time.Duration }
GoroutineExecStats contains statistics about a goroutine's execution during a period of time.
func (GoroutineExecStats) NonOverlappingStats ¶ added in go1.22.0
func (s GoroutineExecStats) NonOverlappingStats() map[string]time.Duration
func (GoroutineExecStats) UnknownTime ¶ added in go1.22.0
func (s GoroutineExecStats) UnknownTime() time.Duration
UnknownTime returns whatever isn't accounted for in TotalTime.
type GoroutineSummary ¶ added in go1.22.0
type GoroutineSummary struct { ID GoID Name string // A non-unique human-friendly identifier for the goroutine. PC uint64 // The first PC we saw for the entry function of the goroutine CreationTime Time // Timestamp of the first appearance in the trace. StartTime Time // Timestamp of the first time it started running. 0 if the goroutine never ran. EndTime Time // Timestamp of when the goroutine exited. 0 if the goroutine never exited. // List of regions in the goroutine, sorted based on the start time. Regions []*UserRegionSummary // Statistics of execution time during the goroutine execution. GoroutineExecStats // contains filtered or unexported fields }
GoroutineSummary contains statistics and execution details of a single goroutine. (For v2 traces.)
type Label ¶ added in go1.23.0
type Label struct { // Label is the label applied to some resource. Label string // Resource is the resource to which this label should be applied. Resource ResourceID }
Label provides details about a Label event.
type Log ¶ added in go1.23.0
type Log struct { // Task is the ID of the task this region is associated with. Task TaskID // Category is the category that was passed to runtime/trace.Log or runtime/trace.Logf. Category string // Message is the message that was passed to runtime/trace.Log or runtime/trace.Logf. Message string }
Log provides details about a Log event.
type MMUCurve ¶ added in go1.12
type MMUCurve struct {
// contains filtered or unexported fields
}
An MMUCurve is the minimum mutator utilization curve across multiple window sizes.
func NewMMUCurve ¶ added in go1.12
func NewMMUCurve(utils [][]MutatorUtil) *MMUCurve
NewMMUCurve returns an MMU curve for the given mutator utilization function.
func (*MMUCurve) Examples ¶ added in go1.12
func (c *MMUCurve) Examples(window time.Duration, n int) (worst []UtilWindow)
Examples returns n specific examples of the lowest mutator utilization for the given window size. The returned windows will be disjoint (otherwise there would be a huge number of mostly-overlapping windows at the single lowest point). There are no guarantees on which set of disjoint windows this returns.
func (*MMUCurve) MMU ¶ added in go1.12
MMU returns the minimum mutator utilization for the given time window. This is the minimum utilization for all windows of this duration across the execution. The returned value is in the range [0, 1].
func (*MMUCurve) MUD ¶ added in go1.12
MUD returns mutator utilization distribution quantiles for the given window size.
The mutator utilization distribution is the distribution of mean mutator utilization across all windows of the given window size in the trace.
The minimum mutator utilization is the minimum (0th percentile) of this distribution. (However, if only the minimum is desired, it's more efficient to use the MMU method.)
type Metric ¶ added in go1.23.0
type Metric struct { // Name is the name of the sampled metric. // // Names follow the same convention as metric names in the // runtime/metrics package, meaning they include the unit. // Names that match with the runtime/metrics package represent // the same quantity. Note that this corresponds to the // runtime/metrics package for the Go version this trace was // collected for. Name string // Value is the sampled value of the metric. // // The Value's Kind is tied to the name of the metric, and so is // guaranteed to be the same for metric samples for the same metric. Value Value }
Metric provides details about a Metric event.
type MutatorUtil ¶ added in go1.12
type MutatorUtil struct { Time int64 // Util is the mean mutator utilization starting at Time. This // is in the range [0, 1]. Util float64 }
MutatorUtil is a change in mutator utilization at a particular time. Mutator utilization functions are represented as a time-ordered []MutatorUtil.
type ProcID ¶ added in go1.23.0
type ProcID int64
ProcID is the runtime-internal G structure's id field. This is unique for each P.
type ProcState ¶ added in go1.23.0
type ProcState uint8
ProcState represents the state of a proc.
New ProcStates may be added in the future. Users of this type must be robust to that possibility.
type Range ¶ added in go1.23.0
type Range struct { // Name is a human-readable name for the range. // // This name can be used to identify the end of the range for the resource // its scoped to, because only one of each type of range may be active on // a particular resource. The relevant resource should be obtained from the // Event that produced these details. The corresponding RangeEnd will have // an identical name. Name string // Scope is the resource that the range is scoped to. // // For example, a ResourceGoroutine scope means that the same goroutine // must have a start and end for the range, and that goroutine can only // have one range of a particular name active at any given time. The // ID that this range is scoped to may be obtained via Event.Goroutine. // // The ResourceNone scope means that the range is globally scoped. As a // result, any goroutine/proc/thread may start or end the range, and only // one such named range may be active globally at any given time. // // For RangeBegin and RangeEnd events, this will always reference some // resource ID in the current execution context. For RangeActive events, // this may reference a resource not in the current context. Prefer Scope // over the current execution context. Scope ResourceID }
Range provides details about a Range event.
type RangeAttribute ¶ added in go1.23.0
type RangeAttribute struct { // Name is the human-readable name for the range. Name string // Value is the value of the attribute. Value Value }
RangeAttributes provides attributes about a completed Range.
type Reader ¶ added in go1.23.0
type Reader struct {
// contains filtered or unexported fields
}
Reader reads a byte stream, validates it, and produces trace events.
type Region ¶ added in go1.23.0
type Region struct { // Task is the ID of the task this region is associated with. Task TaskID // Type is the regionType that was passed to runtime/trace.StartRegion or runtime/trace.WithRegion. Type string }
Region provides details about a Region event.
type ResourceID ¶ added in go1.23.0
type ResourceID struct { // Kind is the kind of resource this ID is for. Kind ResourceKind // contains filtered or unexported fields }
ResourceID represents a generic resource ID.
func MakeResourceID ¶ added in go1.23.0
func MakeResourceID[T interface{ GoID | ProcID | ThreadID }](id T) ResourceID
MakeResourceID creates a general resource ID from a specific resource's ID.
func (ResourceID) Goroutine ¶ added in go1.23.0
func (r ResourceID) Goroutine() GoID
Goroutine obtains a GoID from the resource ID.
r.Kind must be ResourceGoroutine or this function will panic.
func (ResourceID) Proc ¶ added in go1.23.0
func (r ResourceID) Proc() ProcID
Proc obtains a ProcID from the resource ID.
r.Kind must be ResourceProc or this function will panic.
func (ResourceID) String ¶ added in go1.23.0
func (r ResourceID) String() string
String returns a human-readable string representation of the ResourceID.
This representation is subject to change and is intended primarily for debugging.
func (ResourceID) Thread ¶ added in go1.23.0
func (r ResourceID) Thread() ThreadID
Thread obtains a ThreadID from the resource ID.
r.Kind must be ResourceThread or this function will panic.
type ResourceKind ¶ added in go1.23.0
type ResourceKind uint8
ResourceKind indicates a kind of resource that has a state machine.
New ResourceKinds may be added in the future. Users of this type must be robust to that possibility.
const ( ResourceNone ResourceKind = iota // No resource. ResourceGoroutine // Goroutine. ResourceProc // Proc. ResourceThread // Thread. )
func (ResourceKind) String ¶ added in go1.23.0
func (r ResourceKind) String() string
String returns a human-readable representation of a ResourceKind.
The format of the returned string is for debugging purposes and is subject to change.
type Stack ¶ added in go1.23.0
type Stack struct {
// contains filtered or unexported fields
}
Stack represents a stack. It's really a handle to a stack and it's trivially comparable.
If two Stacks are equal then their Frames are guaranteed to be identical. If they are not equal, however, their Frames may still be equal.
type StackFrame ¶ added in go1.23.0
type StackFrame struct { // PC is the program counter of the function call if this // is not a leaf frame. If it's a leaf frame, it's the point // at which the stack trace was taken. PC uint64 // Func is the name of the function this frame maps to. Func string // File is the file which contains the source code of Func. File string // Line is the line number within File which maps to PC. Line uint64 }
StackFrame represents a single frame of a stack.
type StateTransition ¶ added in go1.23.0
type StateTransition struct { // Resource is the resource this state transition is for. Resource ResourceID // Reason is a human-readable reason for the state transition. Reason string // Stack is the stack trace of the resource making the state transition. // // This is distinct from the result (Event).Stack because it pertains to // the transitioning resource, not any of the ones executing the event // this StateTransition came from. // // An example of this difference is the NotExist -> Runnable transition for // goroutines, which indicates goroutine creation. In this particular case, // a Stack here would refer to the starting stack of the new goroutine, and // an (Event).Stack would refer to the stack trace of whoever created the // goroutine. Stack Stack // contains filtered or unexported fields }
StateTransition provides details about a StateTransition event.
func (StateTransition) Goroutine ¶ added in go1.23.0
func (d StateTransition) Goroutine() (from, to GoState)
Goroutine returns the state transition for a goroutine.
Transitions to and from states that are Executing are special in that they change the future execution context. In other words, future events on the same thread will feature the same goroutine until it stops running.
Panics if d.Resource.Kind is not ResourceGoroutine.
func (StateTransition) Proc ¶ added in go1.23.0
func (d StateTransition) Proc() (from, to ProcState)
Proc returns the state transition for a proc.
Transitions to and from states that are Executing are special in that they change the future execution context. In other words, future events on the same thread will feature the same goroutine until it stops running.
Panics if d.Resource.Kind is not ResourceProc.
type Summarizer ¶ added in go1.22.0
type Summarizer struct {
// contains filtered or unexported fields
}
Summarizer constructs per-goroutine time statistics for v2 traces.
func NewSummarizer ¶ added in go1.22.0
func NewSummarizer() *Summarizer
NewSummarizer creates a new struct to build goroutine stats from a trace.
func (*Summarizer) Event ¶ added in go1.22.0
func (s *Summarizer) Event(ev *Event)
Event feeds a single event into the stats summarizer.
func (*Summarizer) Finalize ¶ added in go1.22.0
func (s *Summarizer) Finalize() *Summary
Finalize indicates to the summarizer that we're done processing the trace. It cleans up any remaining state and returns the full summary.
type Summary ¶ added in go1.22.0
type Summary struct { Goroutines map[GoID]*GoroutineSummary Tasks map[TaskID]*UserTaskSummary }
Summary is the analysis result produced by the summarizer.
type Task ¶ added in go1.23.0
type Task struct { // ID is a unique identifier for the task. // // This can be used to associate the beginning of a task with its end. ID TaskID // ParentID is the ID of the parent task. Parent TaskID // Type is the taskType that was passed to runtime/trace.NewTask. // // May be "" if a task's TaskBegin event isn't present in the trace. Type string }
Task provides details about a Task event.
type TaskID ¶ added in go1.23.0
type TaskID uint64
TaskID is the internal ID of a task used to disambiguate tasks (even if they are of the same type).
type ThreadID ¶ added in go1.23.0
type ThreadID int64
ThreadID is the runtime-internal M structure's ID. This is unique for each OS thread.
type Time ¶ added in go1.23.0
type Time int64
Time is a timestamp in nanoseconds.
It corresponds to the monotonic clock on the platform that the trace was taken, and so is possible to correlate with timestamps for other traces taken on the same machine using the same clock (i.e. no reboots in between).
The actual absolute value of the timestamp is only meaningful in relation to other timestamps from the same clock.
BUG: Timestamps coming from traces on Windows platforms are only comparable with timestamps from the same trace. Timestamps across traces cannot be compared, because the system clock is not used as of Go 1.22.
BUG: Traces produced by Go versions 1.21 and earlier cannot be compared with timestamps from other traces taken on the same machine. This is because the system clock was not used at all to collect those timestamps.
type UserRegionSummary ¶ added in go1.22.0
type UserRegionSummary struct { TaskID TaskID Name string // Region start event. Normally EventRegionBegin event or nil, // but can be a state transition event from NotExist or Undetermined // if the region is a synthetic region representing task inheritance // from the parent goroutine. Start *Event // Region end event. Normally EventRegionEnd event or nil, // but can be a state transition event to NotExist if the goroutine // terminated without explicitly ending the region. End *Event GoroutineExecStats }
UserRegionSummary represents a region and goroutine execution stats while the region was active. (For v2 traces.)
type UserTaskSummary ¶ added in go1.22.0
type UserTaskSummary struct { ID TaskID Name string Parent *UserTaskSummary // nil if the parent is unknown. Children []*UserTaskSummary // Task begin event. An EventTaskBegin event or nil. Start *Event // End end event. Normally EventTaskEnd event or nil. End *Event // Logs is a list of EventLog events associated with the task. Logs []*Event // List of regions in the task, sorted based on the start time. Regions []*UserRegionSummary // Goroutines is the set of goroutines associated with this task. Goroutines map[GoID]*GoroutineSummary }
UserTaskSummary represents a task in the trace.
func (*UserTaskSummary) Complete ¶ added in go1.22.0
func (s *UserTaskSummary) Complete() bool
Complete returns true if we have complete information about the task from the trace: both a start and an end.
func (*UserTaskSummary) Descendents ¶ added in go1.22.0
func (s *UserTaskSummary) Descendents() []*UserTaskSummary
Descendents returns a slice consisting of itself (always the first task returned), and the transitive closure of all of its children.
type UtilFlags ¶ added in go1.12
type UtilFlags int
UtilFlags controls the behavior of MutatorUtilization.
const ( // UtilSTW means utilization should account for STW events. // This includes non-GC STW events, which are typically user-requested. UtilSTW UtilFlags = 1 << iota // UtilBackground means utilization should account for // background mark workers. UtilBackground // UtilAssist means utilization should account for mark // assists. UtilAssist // UtilSweep means utilization should account for sweeping. UtilSweep // UtilPerProc means each P should be given a separate // utilization function. Otherwise, there is a single function // and each P is given a fraction of the utilization. UtilPerProc )
type UtilWindow ¶ added in go1.12
type UtilWindow struct { Time int64 // MutatorUtil is the mean mutator utilization in this window. MutatorUtil float64 }
UtilWindow is a specific window at Time.
type Value ¶ added in go1.23.0
type Value struct {
// contains filtered or unexported fields
}
Value is a dynamically-typed value obtained from a trace.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
internal
|
|
oldtrace
Package oldtrace implements a parser for Go execution traces from versions 1.11–1.21.
|
Package oldtrace implements a parser for Go execution traces from versions 1.11–1.21. |
Package raw provides an interface to interpret and emit Go execution traces.
|
Package raw provides an interface to interpret and emit Go execution traces. |
format
Package traceviewer provides definitions of the JSON data structures used by the Chrome trace viewer.
|
Package traceviewer provides definitions of the JSON data structures used by the Chrome trace viewer. |