trace

package
v1.22.0 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2024 License: MIT Imports: 4 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Special P identifiers:
	FakeP = 1000000 + iota
	TimerP
	NetpollP
	SyscallP
	GCP
	ProfileP
)
View Source 
const (
	EvNone              = 0
	EvBatch             = 1
	EvFrequency         = 2
	EvStack             = 3
	EvGomaxprocs        = 4
	EvProcStart         = 5
	EvProcStop          = 6
	EvGCStart           = 7
	EvGCDone            = 8
	EvSTWStart          = 9
	EvSTWDone           = 10
	EvGCSweepStart      = 11
	EvGCSweepDone       = 12
	EvGoCreate          = 13
	EvGoStart           = 14
	EvGoEnd             = 15
	EvGoStop            = 16
	EvGoSched           = 17
	EvGoPreempt         = 18
	EvGoSleep           = 19
	EvGoBlock           = 20
	EvGoUnblock         = 21
	EvGoBlockSend       = 22
	EvGoBlockRecv       = 23
	EvGoBlockSelect     = 24
	EvGoBlockSync       = 25
	EvGoBlockCond       = 26
	EvGoBlockNet        = 27
	EvGoSysCall         = 28
	EvGoSysExit         = 29
	EvGoSysBlock        = 30
	EvGoWaiting         = 31
	EvGoInSyscall       = 32
	EvHeapAlloc         = 33
	EvHeapGoal          = 34
	EvTimerGoroutine    = 35
	EvFutileWakeup      = 36
	EvString            = 37
	EvGoStartLocal      = 38
	EvGoUnblockLocal    = 39
	EvGoSysExitLocal    = 40
	EvGoStartLabel      = 41
	EvGoBlockGC         = 42
	EvGCMarkAssistStart = 43
	EvGCMarkAssistDone  = 44
	EvUserTaskCreate    = 45
	EvUserTaskEnd       = 46
	EvUserRegion        = 47
	EvUserLog           = 48
	EvCPUSample         = 49
	EvCount             = 50
)

Event types in the trace. Verbatim copy from src/runtime/trace.go with the "trace" prefix removed.

Variables

View Source 
var BreakTimestampsForTesting bool

BreakTimestampsForTesting causes the parser to randomly alter timestamps (for testing of broken cputicks).

View Source 
var ErrTimeOrder = fmt.Errorf("time stamps out of order")

ErrTimeOrder is returned by Parse when the trace contains time stamps that do not respect actual event ordering.

View Source 
var EventDescriptions = [EvCount]struct {
	Name       string
	minVersion int
	Stack      bool
	Args       []string
	SArgs      []string
}{
	EvNone:              {"None", 1005, false, []string{}, nil},
	EvBatch:             {"Batch", 1005, false, []string{"p", "ticks"}, nil},
	EvFrequency:         {"Frequency", 1005, false, []string{"freq"}, nil},
	EvStack:             {"Stack", 1005, false, []string{"id", "siz"}, nil},
	EvGomaxprocs:        {"Gomaxprocs", 1005, true, []string{"procs"}, nil},
	EvProcStart:         {"ProcStart", 1005, false, []string{"thread"}, nil},
	EvProcStop:          {"ProcStop", 1005, false, []string{}, nil},
	EvGCStart:           {"GCStart", 1005, true, []string{"seq"}, nil},
	EvGCDone:            {"GCDone", 1005, false, []string{}, nil},
	EvSTWStart:          {"STWStart", 1005, false, []string{"kindid"}, []string{"kind"}},
	EvSTWDone:           {"STWDone", 1005, false, []string{}, nil},
	EvGCSweepStart:      {"GCSweepStart", 1005, true, []string{}, nil},
	EvGCSweepDone:       {"GCSweepDone", 1005, false, []string{"swept", "reclaimed"}, nil},
	EvGoCreate:          {"GoCreate", 1005, true, []string{"g", "stack"}, nil},
	EvGoStart:           {"GoStart", 1005, false, []string{"g", "seq"}, nil},
	EvGoEnd:             {"GoEnd", 1005, false, []string{}, nil},
	EvGoStop:            {"GoStop", 1005, true, []string{}, nil},
	EvGoSched:           {"GoSched", 1005, true, []string{}, nil},
	EvGoPreempt:         {"GoPreempt", 1005, true, []string{}, nil},
	EvGoSleep:           {"GoSleep", 1005, true, []string{}, nil},
	EvGoBlock:           {"GoBlock", 1005, true, []string{}, nil},
	EvGoUnblock:         {"GoUnblock", 1005, true, []string{"g", "seq"}, nil},
	EvGoBlockSend:       {"GoBlockSend", 1005, true, []string{}, nil},
	EvGoBlockRecv:       {"GoBlockRecv", 1005, true, []string{}, nil},
	EvGoBlockSelect:     {"GoBlockSelect", 1005, true, []string{}, nil},
	EvGoBlockSync:       {"GoBlockSync", 1005, true, []string{}, nil},
	EvGoBlockCond:       {"GoBlockCond", 1005, true, []string{}, nil},
	EvGoBlockNet:        {"GoBlockNet", 1005, true, []string{}, nil},
	EvGoSysCall:         {"GoSysCall", 1005, true, []string{}, nil},
	EvGoSysExit:         {"GoSysExit", 1005, false, []string{"g", "seq", "ts"}, nil},
	EvGoSysBlock:        {"GoSysBlock", 1005, false, []string{}, nil},
	EvGoWaiting:         {"GoWaiting", 1005, false, []string{"g"}, nil},
	EvGoInSyscall:       {"GoInSyscall", 1005, false, []string{"g"}, nil},
	EvHeapAlloc:         {"HeapAlloc", 1005, false, []string{"mem"}, nil},
	EvHeapGoal:          {"HeapGoal", 1005, false, []string{"mem"}, nil},
	EvTimerGoroutine:    {"TimerGoroutine", 1005, false, []string{"g"}, nil},
	EvFutileWakeup:      {"FutileWakeup", 1005, false, []string{}, nil},
	EvString:            {"String", 1007, false, []string{}, nil},
	EvGoStartLocal:      {"GoStartLocal", 1007, false, []string{"g"}, nil},
	EvGoUnblockLocal:    {"GoUnblockLocal", 1007, true, []string{"g"}, nil},
	EvGoSysExitLocal:    {"GoSysExitLocal", 1007, false, []string{"g", "ts"}, nil},
	EvGoStartLabel:      {"GoStartLabel", 1008, false, []string{"g", "seq", "labelid"}, []string{"label"}},
	EvGoBlockGC:         {"GoBlockGC", 1008, true, []string{}, nil},
	EvGCMarkAssistStart: {"GCMarkAssistStart", 1009, true, []string{}, nil},
	EvGCMarkAssistDone:  {"GCMarkAssistDone", 1009, false, []string{}, nil},
	EvUserTaskCreate:    {"UserTaskCreate", 1011, true, []string{"taskid", "pid", "typeid"}, []string{"name"}},
	EvUserTaskEnd:       {"UserTaskEnd", 1011, true, []string{"taskid"}, nil},
	EvUserRegion:        {"UserRegion", 1011, true, []string{"taskid", "mode", "typeid"}, []string{"name"}},
	EvUserLog:           {"UserLog", 1011, true, []string{"id", "keyid"}, []string{"category", "message"}},
	EvCPUSample:         {"CPUSample", 1019, true, []string{"ts", "p", "g"}, nil},
}

Functions

func GoroutineStats 

func GoroutineStats(events []*Event) map[uint64]*GDesc

GoroutineStats generates statistics for all goroutines in the trace.

func IsSystemGoroutine 

func IsSystemGoroutine(entryFn string) bool

func MutatorUtilization 

func MutatorUtilization(events []*Event, flags UtilFlags) [][]MutatorUtil

MutatorUtilization returns a set of mutator utilization functions for the given trace. 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 MutatorUtilizationV2 added in v1.22.0 

func MutatorUtilizationV2(events []tracev2.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 Print 

func Print(events []*Event)

Print dumps events to stdout. For debugging.

func PrintEvent 

func PrintEvent(ev *Event)

PrintEvent dumps the event to stdout. For debugging.

func ReadVersion added in v1.22.0 

func ReadVersion(r io.Reader) (ver int, off int, err error)

func RelatedGoroutines 

func RelatedGoroutines(events []*Event, goid uint64) map[uint64]bool

RelatedGoroutines finds a set of goroutines related to goroutine goid.

func RelatedGoroutinesV2 added in v1.22.0 

func RelatedGoroutinesV2(events []tracev2.Event, goid tracev2.GoID) map[tracev2.GoID]struct{}

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 {
	Off  int
	Type byte

	Ts    int64
	P     int
	G     uint64
	StkID uint64
	Stk   []*Frame
	Args  [3]uint64
	SArgs []string
	// linked event (can be nil), depends on event type:
	// for GCStart: the GCStop
	// for GCSTWStart: the GCSTWDone
	// for GCSweepStart: the GCSweepDone
	// for GoCreate: first GoStart of the created goroutine
	// for GoStart/GoStartLabel: the associated GoEnd, GoBlock or other blocking event
	// for GoSched/GoPreempt: the next GoStart
	// for GoBlock and other blocking events: the unblock event
	// for GoUnblock: the associated GoStart
	// for blocking GoSysCall: the associated GoSysExit
	// for GoSysExit: the next GoStart
	// for GCMarkAssistStart: the associated GCMarkAssistDone
	// for UserTaskCreate: the UserTaskEnd
	// for UserRegion: if the start region, the corresponding UserRegion end event
	Link *Event
	// contains filtered or unexported fields
}

Event describes one event in the trace.

func (*Event) String 

func (ev *Event) String() string

type Frame 

type Frame struct {
	PC   uint64
	Fn   string
	File string
	Line int
}

Frame is a frame in stack traces.

type GDesc 

type GDesc struct {
	ID           uint64
	Name         string
	PC           uint64
	CreationTime int64
	StartTime    int64
	EndTime      int64

	// List of regions in the goroutine, sorted based on the start time.
	Regions []*UserRegionDesc

	// Statistics of execution time during the goroutine execution.
	GExecutionStat
	// contains filtered or unexported fields
}

GDesc contains statistics and execution details of a single goroutine.

type GExecutionStat 

type GExecutionStat struct {
	ExecTime      int64
	SchedWaitTime int64
	IOTime        int64
	BlockTime     int64
	SyscallTime   int64
	GCTime        int64
	SweepTime     int64
	TotalTime     int64
}

GExecutionStat contains statistics about a goroutine's execution during a period of time.

type GoroutineExecStats added in v1.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 v1.22.0 

func (s GoroutineExecStats) NonOverlappingStats() map[string]time.Duration

func (GoroutineExecStats) UnknownTime added in v1.22.0 

func (s GoroutineExecStats) UnknownTime() time.Duration

UnknownTime returns whatever isn't accounted for in TotalTime.

type GoroutineSummary added in v1.22.0 

type GoroutineSummary struct {
	ID           tracev2.GoID
	Name         string
	PC           uint64
	CreationTime tracev2.Time
	StartTime    tracev2.Time
	EndTime      tracev2.Time

	// 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 MMUCurve 

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

An MMUCurve is the minimum mutator utilization curve across multiple window sizes.

func NewMMUCurve 

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

NewMMUCurve returns an MMU curve for the given mutator utilization function.

func (*MMUCurve) Examples 

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 

func (c *MMUCurve) MMU(window time.Duration) (mmu float64)

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 

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

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 MutatorUtil 

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 ParseResult 

type ParseResult struct {
	// Events is the sorted list of Events in the trace.
	Events []*Event
	// Stacks is the stack traces keyed by stack IDs from the trace.
	Stacks map[uint64][]*Frame
}

ParseResult is the result of Parse.

func Parse 

func Parse(r io.Reader, bin string) (ParseResult, error)

Parse parses, post-processes and verifies the trace.

type Summarizer added in v1.22.0 

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

Summarizer constructs per-goroutine time statistics for v2 traces.

func NewSummarizer added in v1.22.0 

func NewSummarizer() *Summarizer

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

func (*Summarizer) Event added in v1.22.0 

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

Event feeds a single event into the stats summarizer.

func (*Summarizer) Finalize added in v1.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 v1.22.0 

type Summary struct {
	Goroutines map[tracev2.GoID]*GoroutineSummary
	Tasks      map[tracev2.TaskID]*UserTaskSummary
}

Summary is the analysis result produced by the summarizer.

type UserRegionDesc 

type UserRegionDesc struct {
	TaskID uint64
	Name   string

	// Region start event. Normally EvUserRegion start event or nil,
	// but can be EvGoCreate event if the region is a synthetic
	// region representing task inheritance from the parent goroutine.
	Start *Event

	// Region end event. Normally EvUserRegion end event or nil,
	// but can be EvGoStop or EvGoEnd event if the goroutine
	// terminated without explicitly ending the region.
	End *Event

	GExecutionStat
}

UserRegionDesc represents a region and goroutine execution stats while the region was active.

type UserRegionSummary added in v1.22.0 

type UserRegionSummary struct {
	TaskID tracev2.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 *tracev2.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 *tracev2.Event

	GoroutineExecStats
}

UserRegionSummary represents a region and goroutine execution stats while the region was active. (For v2 traces.)

type UserTaskSummary added in v1.22.0 

type UserTaskSummary struct {
	ID       tracev2.TaskID
	Name     string
	Parent   *UserTaskSummary
	Children []*UserTaskSummary

	// Task begin event. An EventTaskBegin event or nil.
	Start *tracev2.Event

	// End end event. Normally EventTaskEnd event or nil.
	End *tracev2.Event

	// Logs is a list of tracev2.EventLog events associated with the task.
	Logs []*tracev2.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[tracev2.GoID]*GoroutineSummary
}

UserTaskSummary represents a task in the trace.

func (*UserTaskSummary) Complete added in v1.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 v1.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 

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 

type UtilWindow struct {
	Time int64
	// MutatorUtil is the mean mutator utilization in this window.
	MutatorUtil float64
}

UtilWindow is a specific window at Time.

type Writer 

type Writer struct {
	bytes.Buffer
}

Writer is a test trace writer.

func NewWriter 

func NewWriter() *Writer

func (*Writer) Emit 

func (w *Writer) Emit(typ byte, args ...uint64)

Emit writes an event record to the trace. See Event types for valid types and required arguments.

Source Files

View all Source files

Directories

Path Synopsis
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.
v2
event
event/go122
internal/testgen/go122
raw
Package raw provides an interface to interpret and emit Go execution traces.
 Package raw provides an interface to interpret and emit Go execution traces.
testtrace
version

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.