func IsSystemGoroutine(entryFnstring)bool

func MutatorUtilizationV2(events []Event, flagsUtilFlags) [][]MutatorUtil

func RelatedGoroutinesV2(events []Event, goidGoID) map[GoID]struct{}

type ClockSnapshot struct {// Trace is a snapshot of the trace clock.TraceTime// Wall is a snapshot of the system's wall clock.Walltime.Time// Mono is a snapshot of the system's monotonic clock.Monouint64}

type Event struct {// contains filtered or unexported fields}

func (Event)Experimental¶added ingo1.23.0

func (eEvent) Experimental()ExperimentalEvent

Experimental returns a view of the raw event for an experimental event.

Panics if Kind != EventExperimental.

func (Event)Goroutine¶added ingo1.23.0

func (eEvent) Goroutine()GoID

Goroutine returns the ID of the goroutine that was executing whenthis event happened. It describes part of the execution contextfor this event.

Note that for goroutine state transitions this always refers to thestate before the transition. For example, if a goroutine is juststarting to run on this thread and/or proc, then this will returnNoGoroutine. In this case, the goroutine starting to run will becan be found at Event.StateTransition().Resource.

func (Event)Kind¶added ingo1.23.0

func (eEvent) Kind()EventKind

Kind returns the kind of event that this is.

func (Event)Label¶added ingo1.23.0

func (eEvent) Label()Label

Label returns details about a Label event.

Panics if Kind != EventLabel.

func (Event)Log¶added ingo1.23.0

func (eEvent) Log()Log

Log returns details about a Log event.

Panics if Kind != EventLog.

func (Event)Metric¶added ingo1.23.0

func (eEvent) Metric()Metric

Metric returns details about a Metric event.

Panics if Kind != EventMetric.

func (Event)Proc¶added ingo1.23.0

func (eEvent) Proc()ProcID

Proc returns the ID of the proc this event event pertains to.

Note that for proc state transitions this always refers to thestate before the transition. For example, if a proc is juststarting to run on this thread, then this will return NoProc.

func (Event)Range¶added ingo1.23.0

func (eEvent) Range()Range

Range returns details about an EventRangeBegin, EventRangeActive, or EventRangeEnd event.

Panics if Kind != EventRangeBegin, Kind != EventRangeActive, and Kind != EventRangeEnd.

func (Event)RangeAttributes¶added ingo1.23.0

func (eEvent) RangeAttributes() []RangeAttribute

RangeAttributes returns attributes for a completed range.

Panics if Kind != EventRangeEnd.

func (Event)Region¶added ingo1.23.0

func (eEvent) Region()Region

Region returns details about a RegionBegin or RegionEnd event.

Panics if Kind != EventRegionBegin and Kind != EventRegionEnd.

func (Event)Stack¶added ingo1.23.0

func (eEvent) Stack()Stack

Stack returns a handle to a stack associated with the event.

This represents a stack trace at the current moment in time forthe current execution context.

func (Event)StateTransition¶added ingo1.23.0

func (eEvent) StateTransition()StateTransition

StateTransition returns details about a StateTransition event.

Panics if Kind != EventStateTransition.

func (Event)String¶added ingo1.11

func (eEvent) String()string

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)Sync¶added ingo1.25.0

func (eEvent) Sync()Sync

Sync returns details that are relevant for the following events, up to but excluding thenext EventSync event.

func (Event)Task¶added ingo1.23.0

func (eEvent) Task()Task

Task returns details about a TaskBegin or TaskEnd event.

Panics if Kind != EventTaskBegin and Kind != EventTaskEnd.

func (Event)Thread¶added ingo1.23.0

func (eEvent) Thread()ThreadID

Thread returns the ID of the thread this event pertains to.

Note that for thread state transitions this always refers to thestate before the transition. For example, if a thread is juststarting to run, then this will return NoThread.

Note: tracking thread state is not currently supported, so thiswill always return a valid thread ID. However thread state transitionsmay be tracked in the future, and callers must be robust to thispossibility.

func (Event)Time¶added ingo1.23.0

func (eEvent) Time()Time

Time returns the timestamp of the event.

type EventKinduint16

func (EventKind)String¶added ingo1.23.0

func (eEventKind) String()string

String returns a string form of the EventKind.

type ExperimentalBatch struct {// Thread is the ID of the thread that produced a packet of data.ThreadThreadID// Data is a packet of unparsed data all produced by one thread.Data []byte}

type ExperimentalEvent struct {// Name is the name of the event.Namestring// Experiment is the name of the experiment this event is a part of.Experimentstring// Args lists the names of the event's arguments in order.Args []string// contains filtered or unexported fields}

func (ExperimentalEvent)ArgValue¶added ingo1.25.0

func (eExperimentalEvent) ArgValue(iint)Value

ArgValue returns a typed Value for the i'th argument in the experimental event.

type GoIDint64

type GoStateuint8

func (GoState)Executing¶added ingo1.23.0

func (sGoState) Executing()bool

Executing returns true if the state indicates that the goroutine is executingand bound to its thread.

func (GoState)String¶added ingo1.23.0

func (sGoState) String()string

String returns a human-readable representation of a GoState.

The format of the returned string is for debugging purposes and is subject to change.

type GoroutineExecStats struct {// These stats are all non-overlapping.ExecTimetime.DurationSchedWaitTimetime.DurationBlockTimeByReason map[string]time.DurationSyscallTimetime.DurationSyscallBlockTimetime.Duration// TotalTime is the duration of the goroutine's presence in the trace.// Necessarily overlaps with other stats.TotalTimetime.Duration// Total time the goroutine spent in certain ranges; may overlap// with other stats.RangeTime map[string]time.Duration}

func (GoroutineExecStats)NonOverlappingStats¶added ingo1.22.0

func (sGoroutineExecStats) NonOverlappingStats() map[string]time.Duration

func (GoroutineExecStats)UnknownTime¶added ingo1.22.0

func (sGoroutineExecStats) UnknownTime()time.Duration

UnknownTime returns whatever isn't accounted for in TotalTime.

type GoroutineSummary struct {IDGoIDNamestring// A non-unique human-friendly identifier for the goroutine.PCuint64// The first PC we saw for the entry function of the goroutineCreationTimeTime// Timestamp of the first appearance in the trace.StartTimeTime// Timestamp of the first time it started running. 0 if the goroutine never ran.EndTimeTime// 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}

type Label struct {// Label is the label applied to some resource.Labelstring// Resource is the resource to which this label should be applied.ResourceResourceID}

type Log struct {// Task is the ID of the task this region is associated with.TaskTaskID// Category is the category that was passed to runtime/trace.Log or runtime/trace.Logf.Categorystring// Message is the message that was passed to runtime/trace.Log or runtime/trace.Logf.Messagestring}

type MMUCurve struct {// contains filtered or unexported fields}

funcNewMMUCurve¶added ingo1.12

func NewMMUCurve(utils [][]MutatorUtil) *MMUCurve

NewMMUCurve returns an MMU curve for the given mutator utilizationfunction.

func (*MMUCurve)Examples¶added ingo1.12

func (c *MMUCurve) Examples(windowtime.Duration, nint) (worst []UtilWindow)

Examples returns n specific examples of the lowest mutatorutilization for the given window size. The returned windows will bedisjoint (otherwise there would be a huge number ofmostly-overlapping windows at the single lowest point). There areno guarantees on which set of disjoint windows this returns.

func (*MMUCurve)MMU¶added ingo1.12

func (c *MMUCurve) MMU(windowtime.Duration) (mmufloat64)

MMU returns the minimum mutator utilization for the given timewindow. This is the minimum utilization for all windows of thisduration across the execution. The returned value is in the range[0, 1].

func (*MMUCurve)MUD¶added ingo1.12

func (c *MMUCurve) MUD(windowtime.Duration, quantiles []float64) []float64

MUD returns mutator utilization distribution quantiles for thegiven window size.

The mutator utilization distribution is the distribution of meanmutator utilization across all windows of the given window size inthe trace.

The minimum mutator utilization is the minimum (0th percentile) ofthis distribution. (However, if only the minimum is desired, it'smore efficient to use the MMU method.)

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.Namestring// 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.ValueValue}

type MutatorUtil struct {Timeint64// Util is the mean mutator utilization starting at Time. This// is in the range [0, 1].Utilfloat64}

type ProcIDint64

type ProcStateuint8

func (ProcState)Executing¶added ingo1.23.0

func (sProcState) Executing()bool

Executing returns true if the state indicates that the proc is executingand bound to its thread.

func (ProcState)String¶added ingo1.23.0

func (sProcState) String()string

String returns a human-readable representation of a ProcState.

The format of the returned string is for debugging purposes and is subject to change.

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.Namestring// 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.ScopeResourceID}

type RangeAttribute struct {// Name is the human-readable name for the range.Namestring// Value is the value of the attribute.ValueValue}

type Reader struct {// contains filtered or unexported fields}

funcNewReader¶added ingo1.23.0

func NewReader(rio.Reader) (*Reader,error)

NewReader creates a new trace reader.

func (*Reader)ReadEvent¶added ingo1.23.0

func (r *Reader) ReadEvent() (eEvent, errerror)

ReadEvent reads a single event from the stream.

If the stream has been exhausted, it returns an invalid event and io.EOF.

type Region struct {// Task is the ID of the task this region is associated with.TaskTaskID// Type is the regionType that was passed to runtime/trace.StartRegion or runtime/trace.WithRegion.Typestring}

type ResourceID struct {// Kind is the kind of resource this ID is for.KindResourceKind// contains filtered or unexported fields}

funcMakeResourceID¶added ingo1.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 ingo1.23.0

func (rResourceID) Goroutine()GoID

Goroutine obtains a GoID from the resource ID.

r.Kind must be ResourceGoroutine or this function will panic.

func (ResourceID)Proc¶added ingo1.23.0

func (rResourceID) Proc()ProcID

Proc obtains a ProcID from the resource ID.

r.Kind must be ResourceProc or this function will panic.

func (ResourceID)String¶added ingo1.23.0

func (rResourceID) 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 ingo1.23.0

func (rResourceID) Thread()ThreadID

Thread obtains a ThreadID from the resource ID.

r.Kind must be ResourceThread or this function will panic.

type ResourceKinduint8

func (ResourceKind)String¶added ingo1.23.0

func (rResourceKind) 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 struct {// contains filtered or unexported fields}

func (Stack)Frames¶added ingo1.23.0

func (sStack) Frames()iter.Seq[StackFrame]

Frames is an iterator over the frames in a Stack.

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.PCuint64// Func is the name of the function this frame maps to.Funcstring// File is the file which contains the source code of Func.Filestring// Line is the line number within File which maps to PC.Lineuint64}

type StateTransition struct {// Resource is the resource this state transition is for.ResourceResourceID// Reason is a human-readable reason for the state transition.Reasonstring// 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.StackStack// contains filtered or unexported fields}

func (StateTransition)Goroutine¶added ingo1.23.0

func (dStateTransition) Goroutine() (from, toGoState)

Goroutine returns the state transition for a goroutine.

Transitions to and from states that are Executing are special in thatthey change the future execution context. In other words, future eventson the same thread will feature the same goroutine until it stops running.

Panics if d.Resource.Kind is not ResourceGoroutine.

func (StateTransition)Proc¶added ingo1.23.0

func (dStateTransition) Proc() (from, toProcState)

Proc returns the state transition for a proc.

Transitions to and from states that are Executing are special in thatthey change the future execution context. In other words, future eventson the same thread will feature the same goroutine until it stops running.

Panics if d.Resource.Kind is not ResourceProc.

type Summarizer struct {// contains filtered or unexported fields}

funcNewSummarizer¶added ingo1.22.0

func NewSummarizer() *Summarizer

NewSummarizer creates a new struct to build goroutine stats from a trace.

func (*Summarizer)Event¶added ingo1.22.0

func (s *Summarizer) Event(ev *Event)

Event feeds a single event into the stats summarizer.

func (*Summarizer)Finalize¶added ingo1.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 struct {Goroutines map[GoID]*GoroutineSummaryTasks      map[TaskID]*UserTaskSummary}

type Sync struct {// N indicates that this is the Nth sync event in the trace.Nint// ClockSnapshot is a snapshot of different clocks taken in close in time// that can be used to correlate trace events with data captured by other// tools. May be nil for older trace versions.ClockSnapshot *ClockSnapshot// ExperimentalBatches contain all the unparsed batches of data for a given experiment.ExperimentalBatches map[string][]ExperimentalBatch}

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.IDTaskID// ParentID is the ID of the parent task.ParentTaskID// 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.Typestring}

type TaskIDuint64

type ThreadIDint64

type Timeint64

func (Time)Sub¶added ingo1.23.0

func (tTime) Sub(t0Time)time.Duration

Sub subtracts t0 from t, returning the duration in nanoseconds.

type UserRegionSummary struct {TaskIDTaskIDNamestring// 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 *EventGoroutineExecStats}

type UserTaskSummary struct {IDTaskIDNamestringParent   *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}

func (*UserTaskSummary)Complete¶added ingo1.22.0

func (s *UserTaskSummary) Complete()bool

Complete returns true if we have complete information about the taskfrom the trace: both a start and an end.

func (*UserTaskSummary)Descendents¶added ingo1.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 UtilFlagsint

type UtilWindow struct {Timeint64// MutatorUtil is the mean mutator utilization in this window.MutatorUtilfloat64}

type Value struct {// contains filtered or unexported fields}

func (Value)Kind¶added ingo1.23.0

func (vValue) Kind()ValueKind

Kind returns the ValueKind of the value.

It represents the underlying structure of the value.

New ValueKinds may be added in the future. Users of this type must be robustto that possibility.

func (Value)String¶added ingo1.25.0

func (vValue) String()string

String returns the string value for a ValueString, and otherwisea string representation of the value for other kinds of values.

func (Value)Uint64¶added ingo1.23.0

func (vValue) Uint64()uint64

Uint64 returns the uint64 value for a ValueUint64.

Panics if this Value's Kind is not ValueUint64.

type ValueKinduint8