package trace
Import Path
internal/trace/v2 (on go.dev)
Dependency Relation
imports 13 packages, and imported by 3 packages
Involved Source Files
base.go
batch.go
batchcursor.go
event.go
generation.go
order.go
reader.go
resources.go
value.go
Package-Level Type Names (total 24)
Event represents a single event in the trace.
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.
Kind returns the kind of event that this is.
Label returns details about a Label event.
Panics if Kind != EventLabel.
Log returns details about a Log event.
Panics if Kind != EventLog.
Metric returns details about a Metric event.
Panics if Kind != EventMetric.
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.
Range returns details about an EventRangeBegin, EventRangeActive, or EventRangeEnd event.
Panics if Kind != EventRangeBegin, Kind != EventRangeActive, and Kind != EventRangeEnd.
RangeAttributes returns attributes for a completed range.
Panics if Kind != EventRangeEnd.
Region returns details about a RegionBegin or RegionEnd event.
Panics if Kind != EventRegionBegin and Kind != EventRegionEnd.
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.
StateTransition returns details about a StateTransition event.
Panics if Kind != EventStateTransition.
String returns the event as a human-readable string.
The format of the string is intended for debugging and is subject to change.
Task returns details about a TaskBegin or TaskEnd event.
Panics if Kind != EventTaskBegin and Kind != EventTaskEnd.
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.
Time returns the timestamp of the event.
Event : expvar.Var
Event : fmt.Stringer
func (*Reader).ReadEvent() (e Event, err error)
func internal/trace/v2/testtrace.(*Validator).Event(ev Event) error
func internal/trace.MutatorUtilizationV2(events []Event, flags trace.UtilFlags) [][]trace.MutatorUtil
func internal/trace.RelatedGoroutinesV2(events []Event, goid GoID) map[GoID]struct{}
func internal/trace.(*Summarizer).Event(ev *Event)
EventKind indicates the kind of event this is.
Use this information to obtain a more specific event that
allows access to more detailed information.
String returns a string form of the EventKind.
EventKind : expvar.Var
EventKind : fmt.Stringer
func Event.Kind() EventKind
const EventBad
const EventLabel
const EventLog
const EventMetric
const EventRangeActive
const EventRangeBegin
const EventRangeEnd
const EventRegionBegin
const EventRegionEnd
const EventStackSample
const EventStateTransition
const EventSync
const EventTaskBegin
const EventTaskEnd
GoID is the runtime-internal G structure's goid field. This is unique
for each goroutine.
func Event.Goroutine() GoID
func ResourceID.Goroutine() GoID
func internal/trace.RelatedGoroutinesV2(events []Event, goid GoID) map[GoID]struct{}
func internal/trace.RelatedGoroutinesV2(events []Event, goid GoID) map[GoID]struct{}
const NoGoroutine
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.
Executing returns true if the state indicates that the goroutine is executing
and bound to its thread.
String returns a human-readable representation of a GoState.
The format of the returned string is for debugging purposes and is subject to change.
GoState : expvar.Var
GoState : fmt.Stringer
func StateTransition.Goroutine() (from, to GoState)
const GoNotExist
const GoRunnable
const GoRunning
const GoSyscall
const GoUndetermined
const GoWaiting
Label provides details about a Label event.
Label is the label applied to some resource.
Resource is the resource to which this label should be applied.
func Event.Label() Label
Log provides details about a Log event.
Category is the category that was passed to runtime/trace.Log or runtime/trace.Logf.
Message is the message that was passed to runtime/trace.Log or runtime/trace.Logf.
Task is the ID of the task this region is associated with.
func Event.Log() Log
Metric provides details about a Metric event.
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.
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.
func Event.Metric() Metric
ProcID is the runtime-internal G structure's id field. This is unique
for each P.
func Event.Proc() ProcID
func ResourceID.Proc() ProcID
const NoProc
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.
Executing returns true if the state indicates that the proc is executing
and bound to its thread.
String returns a human-readable representation of a ProcState.
The format of the returned string is for debugging purposes and is subject to change.
ProcState : expvar.Var
ProcState : fmt.Stringer
func StateTransition.Proc() (from, to ProcState)
const ProcIdle
const ProcNotExist
const ProcRunning
const ProcUndetermined
Range provides details about a Range event.
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.
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.
func Event.Range() Range
RangeAttributes provides attributes about a completed Range.
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.
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.
func Event.RangeAttributes() []RangeAttribute
Reader reads a byte stream, validates it, and produces trace events.
ReadEvent reads a single event from the stream.
If the stream has been exhausted, it returns an invalid
event and io.EOF.
func NewReader(r io.Reader) (*Reader, error)
Region provides details about a Region event.
Task is the ID of the task this region is associated with.
Type is the regionType that was passed to runtime/trace.StartRegion or runtime/trace.WithRegion.
func Event.Region() Region
ResourceID represents a generic resource ID.
Kind is the kind of resource this ID is for.
Goroutine obtains a GoID from the resource ID.
r.Kind must be ResourceGoroutine or this function will panic.
Proc obtains a ProcID from the resource ID.
r.Kind must be ResourceProc or this function will panic.
String returns a human-readable string representation of the ResourceID.
This representation is subject to change and is intended primarily for debugging.
Thread obtains a ThreadID from the resource ID.
r.Kind must be ResourceThread or this function will panic.
ResourceID : expvar.Var
ResourceID : fmt.Stringer
func MakeResourceID[T](id T) ResourceID
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.
String returns a human-readable representation of a ResourceKind.
The format of the returned string is for debugging purposes and is subject to change.
ResourceKind : expvar.Var
ResourceKind : fmt.Stringer
const ResourceGoroutine
const ResourceNone
const ResourceProc
const ResourceThread
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.
Frames is an iterator over the frames in a Stack.
func Event.Stack() Stack
var NoStack
StackFrame represents a single frame of a stack.
File is the file which contains the source code of Func.
Func is the name of the function this frame maps to.
Line is the line number within File which maps to PC.
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.
func internal/trace/v2/internal/testgen/go122.(*Generation).Stack(stk []StackFrame) uint64
StateTransition provides details about a StateTransition event.
Reason is a human-readable reason for the state transition.
Resource is the resource this state transition is for.
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.
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.
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.
func Event.StateTransition() StateTransition
Task provides details about a Task event.
ID is a unique identifier for the task.
This can be used to associate the beginning of a task with its end.
ParentID is the ID of the parent task.
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.
func Event.Task() Task
TaskID is the internal ID of a task used to disambiguate tasks (even if they
are of the same type).
const BackgroundTask
const NoTask
ThreadID is the runtime-internal M structure's ID. This is unique
for each OS thread.
func Event.Thread() ThreadID
func ResourceID.Thread() ThreadID
func internal/trace/v2/internal/testgen/go122.(*Generation).Batch(thread ThreadID, time testkit.Time) *testkit.Batch
const NoThread
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.
Sub subtracts t0 from t, returning the duration in nanoseconds.
func Event.Time() Time
func Time.Sub(t0 Time) time.Duration
Value is a dynamically-typed value obtained from a trace.
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 robust
to that possibility.
Uint64 returns the uint64 value for a MetricSampleUint64.
Panics if this metric sample's Kind is not MetricSampleUint64.
Value : math/rand/v2.Source
ValueKind is the type of a dynamically-typed value from a trace.
func Value.Kind() ValueKind
const ValueBad
const ValueUint64
Package-Level Functions (total 2)
Type Parameters:
T: interface{GoID | ProcID | ThreadID}
MakeResourceID creates a general resource ID from a specific resource's ID.
NewReader creates a new trace reader.
Package-Level Variables (only one)
NoStack is a sentinel value that can be compared against any Stack value, indicating
a lack of a stack trace.
Package-Level Constants (total 35)
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.
EventLabel attaches a label to a resource.
EventLog represents a runtime/trace.Log call.
EventMetric is an event that represents the value of a metric at
a particular point in time.
const EventRangeActive EventKind = 6
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.
const EventRangeEnd EventKind = 7
EventRegionBegin and EventRegionEnd are a pair of events represent a runtime/trace.Region.
const EventRegionEnd EventKind = 11
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.
Transitions in state for some resource.
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.
EvTaskBegin and EvTaskEnd are a pair of events representing a runtime/trace.Task.
const EventTaskEnd EventKind = 9 const GoNotExist GoState = 1 // Goroutine does not exist. const GoRunnable GoState = 2 // Goroutine is runnable but not running. const GoUndetermined GoState = 0 // No information is known about the goroutine.
NoGoroutine indicates that the relevant events don't correspond to any
goroutine in particular.
NoProc indicates that the relevant events don't correspond to any
P in particular.
NoTask indicates the lack of a task.
NoThread indicates that the relevant events don't correspond to any
thread in particular.
const ProcNotExist ProcState = 1 // Proc does not exist. const ProcRunning ProcState = 2 // Proc is running. const ProcUndetermined ProcState = 0 // No information is known about the proc. const ResourceGoroutine ResourceKind = 1 // Goroutine. const ResourceNone ResourceKind = 0 // No resource. const ResourceProc ResourceKind = 2 // Proc. const ResourceThread ResourceKind = 3 // Thread. const ValueUint64 ValueKind = 1 |
The pages are generated with Golds v0.6.9-preview. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |