trace

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jan 9, 2024 License: MIT Imports: 9 Imported by: 3

Documentation

Overview

Copyright 2014 The Go Authors. All rights reserved.

Index

Constants

View Source 
const (
	// Special P identifiers:
	FakeP    = 1000000 + iota
	NetpollP // depicts network unblocks
	SyscallP // depicts returns from syscalls
	GCP      // depicts GC state
	ProfileP // depicts recording of CPU profile samples
)
View Source 
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, stack, name string]
	EvUserTaskEnd       = 46 // end of task [timestamp, internal task id, stack]
	EvUserRegion        = 47 // trace.WithRegion [timestamp, internal task id, mode(0:start, 1:end), stack, name string]
	EvUserLog           = 48 // trace.Log [timestamp, internal id, key string id, stack, value string]
	EvCPUSample         = 49 // CPU profiling sample [timestamp, stack, real timestamp, real P id (-1 when absent), goroutine id]
	EvCount             = 50
)

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

View Source 
const (
	ArgGCSweepDoneReclaimed = 1
	ArgGCSweepDoneSwept     = 0
	ArgGoCreateG            = 0
	ArgGoCreateStack        = 1
	ArgGoStartLabelLabelID  = 2
	ArgGoUnblockG           = 0
	ArgUserLogKeyID         = 1
	ArgUserLogMessage       = 3
	ArgUserRegionMode       = 1
	ArgUserRegionTaskID     = 0
	ArgUserRegionTypeID     = 2
	ArgUserTaskCreateTaskID = 0
	ArgUserTaskCreateTypeID = 2
	ArgHeapAllocMem         = 0
	ArgHeapGoalMem          = 0
	ArgSTWStartKind         = 0
)

Variables

View Source 
var ErrTimeOrder = errors.New("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 ErrTooManyEvents = fmt.Errorf("trace contains more than %d events", math.MaxInt32)
View Source 
var EventDescriptions = [256]struct {
	Name       string
	minVersion int
	Stack      bool
	Args       []string
	SArgs      []string // string arguments
}{
	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:          {"GCSTWStart", 1005, false, []string{"kindid"}, []string{"kind"}},
	EvSTWDone:           {"GCSTWDone", 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, res Trace) map[uint64]*GDesc

GoroutineStats generates statistics for all goroutines in the trace.

func MutatorUtilization 

func MutatorUtilization(events []Event, res Trace, 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 RelatedGoroutines 

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

RelatedGoroutines finds a set of goroutines related to goroutine goid.

Types

type Event 

type Event struct {
	Ts    Timestamp // timestamp in nanoseconds
	G     uint64    // G on which the event happened
	Args  [4]uint64 // event-type-specific arguments
	StkID uint32    // unique stack ID
	P     int32     // P on which the event happened (can be one of TimerP, NetpollP, SyscallP)
	// 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, GoWaiting, or GoInSyscall 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 GoInSyscall and 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 int32
	Type byte // one of Ev*
}

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 Timestamp
	StartTime    Timestamp
	EndTime      Timestamp

	// 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      time.Duration
	SchedWaitTime time.Duration
	IOTime        time.Duration
	BlockTime     time.Duration
	SyscallTime   time.Duration
	GCTime        time.Duration
	SweepTime     time.Duration
	TotalTime     time.Duration
}

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

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 Timestamp
	// 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 Parser 

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

func NewParser 

func NewParser(r io.Reader) (*Parser, error)

func (*Parser) Parse 

func (p *Parser) Parse() (Trace, error)

type STWReason added in v0.3.0 

type STWReason int
const (
	STWUnknown                 STWReason = 0
	STWGCMarkTermination       STWReason = 1
	STWGCSweepTermination      STWReason = 2
	STWWriteHeapDump           STWReason = 3
	STWGoroutineProfile        STWReason = 4
	STWGoroutineProfileCleanup STWReason = 5
	STWAllGoroutinesStackTrace STWReason = 6
	STWReadMemStats            STWReason = 7
	STWAllThreadsSyscall       STWReason = 8
	STWGOMAXPROCS              STWReason = 9
	STWStartTrace              STWReason = 10
	STWStopTrace               STWReason = 11
	STWCountPagesInUse         STWReason = 12
	STWReadMetricsSlow         STWReason = 13
	STWReadMemStatsSlow        STWReason = 14
	STWPageCachePagesLeaked    STWReason = 15
	STWResetDebugLog           STWReason = 16

	NumSTWReasons = 17
)

func (STWReason) String added in v0.3.0 

func (stw STWReason) String() string

type Timestamp 

type Timestamp int64

type Trace 

type Trace struct {
	Version int

	// Events is the sorted list of Events in the trace.
	Events []Event
	// Stacks is the stack traces keyed by stack IDs from the trace.
	//
	// OPT(dh): we could renumber stacks, PCs and Strings densely and store them in slices instead of maps. I don't know
	// if the cost of accesses will outweigh the cost of renumbering.
	Stacks  map[uint32][]uint64
	PCs     map[uint64]Frame
	Strings map[uint64]string
}

Trace is the result of Parse.

func Parse 

func Parse(r io.Reader, progress func(float64)) (Trace, error)

func (*Trace) STWReason added in v0.3.0 

func (tr *Trace) STWReason(kindID uint64) STWReason

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 UtilFlags 

type UtilFlags int

UtilFlags controls the behavior of MutatorUtilization. 

const (
	// UtilSTW means utilization should account for STW events.
	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 Timestamp
	// MutatorUtil is the mean mutator utilization in this window.
	MutatorUtil float64
}

UtilWindow is a specific window at Time.

Source Files

View all Source files

Directories

Path Synopsis
Package ptrace processes a runtime trace and enriches it with additional information.
 Package ptrace processes a runtime trace and enriches it with additional information.

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.