trace

package standard library
go1.22.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2024 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
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)
)
View Source 
const NoGoroutine = GoID(-1)

NoGoroutine indicates that the relevant events don't correspond to any goroutine in particular.

View Source 
const NoProc = ProcID(-1)

NoProc indicates that the relevant events don't correspond to any P in particular.

View Source 
const NoThread = ThreadID(-1)

NoThread indicates that the relevant events don't correspond to any thread in particular.

Variables

View Source 
var NoStack = Stack{}

NoStack is a sentinel value that can be compared against any Stack value, indicating a lack of a stack trace.

Functions

This section is empty.

Types

type Event 

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

Event represents a single event in the trace.

func (Event) Goroutine 

func (e Event) Goroutine() GoID

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) Kind 

func (e Event) Kind() EventKind

Kind returns the kind of event that this is.

func (Event) Label 

func (e Event) Label() Label

Label returns details about a Label event.

Panics if Kind != EventLabel.

func (Event) Log 

func (e Event) Log() Log

Log returns details about a Log event.

Panics if Kind != EventLog.

func (Event) Metric 

func (e Event) Metric() Metric

Metric returns details about a Metric event.

Panics if Kind != EventMetric.

func (Event) Proc 

func (e Event) Proc() ProcID

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 

func (e Event) Range() Range

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

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

func (Event) RangeAttributes 

func (e Event) RangeAttributes() []RangeAttribute

RangeAttributes returns attributes for a completed range.

Panics if Kind != EventRangeEnd.

func (Event) Region 

func (e Event) Region() Region

Region returns details about a RegionBegin or RegionEnd event.

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

func (Event) Stack 

func (e Event) Stack() Stack

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 

func (e Event) StateTransition() StateTransition

StateTransition returns details about a StateTransition event.

Panics if Kind != EventStateTransition.

func (Event) String 

func (e Event) 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) Task 

func (e Event) Task() Task

Task returns details about a TaskBegin or TaskEnd event.

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

func (Event) Thread 

func (e Event) Thread() ThreadID

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.

func (Event) Time 

func (e Event) Time() Time

Time returns the timestamp of the event.

type EventKind 

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

	// Transitions in state for some resource.
	EventStateTransition
)

func (EventKind) String 

func (e EventKind) String() string

String returns a string form of the EventKind.

type GoID 

type GoID int64

GoID is the runtime-internal G structure's goid field. This is unique for each goroutine.

type GoState 

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.
)

func (GoState) Executing 

func (s GoState) Executing() bool

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

func (GoState) String 

func (s GoState) 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 Label 

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 

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 Metric 

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 ProcID 

type ProcID int64

ProcID is the runtime-internal G structure's id field. This is unique for each P.

type ProcState 

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. 

const (
	ProcUndetermined ProcState = iota // No information is known about the proc.
	ProcNotExist                      // Proc does not exist.
	ProcRunning                       // Proc is running.
	ProcIdle                          // Proc is idle.
)

func (ProcState) Executing 

func (s ProcState) Executing() bool

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

func (ProcState) String 

func (s ProcState) 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 

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 

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 

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

Reader reads a byte stream, validates it, and produces trace events.

func NewReader 

func NewReader(r io.Reader) (*Reader, error)

NewReader creates a new trace reader.

func (*Reader) ReadEvent 

func (r *Reader) ReadEvent() (e Event, err error)

ReadEvent reads a single event from the stream.

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

type Region 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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.

func (Stack) Frames 

func (s Stack) Frames(yield func(f StackFrame) bool) bool

Frames is an iterator over the frames in a Stack.

type StackFrame 

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 

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 

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 

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 Task 

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 

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 

type ThreadID int64

ThreadID is the runtime-internal M structure's ID. This is unique for each OS thread.

type Time 

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.

func (Time) Sub 

func (t Time) Sub(t0 Time) time.Duration

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

type Value 

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

Value is a dynamically-typed value obtained from a trace.

func (Value) Kind 

func (v Value) 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 robust to that possibility.

func (Value) Uint64 

func (v Value) Uint64() uint64

Uint64 returns the uint64 value for a MetricSampleUint64.

Panics if this metric sample's Kind is not MetricSampleUint64.

type ValueKind 

type ValueKind uint8

ValueKind is the type of a dynamically-typed value from a trace. 

const (
	ValueBad ValueKind = iota
	ValueUint64
)

Source Files

View all Source files

Directories

Path Synopsis
go122
internal
testgen/go122
Package raw provides an interface to interpret and emit Go execution traces.
 Package raw provides an interface to interpret and emit Go execution traces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.