oldtrace

Documentation

Overview

Package oldtrace implements a parser for Go execution traces from versions 1.11–1.21.

The package started as a copy of Go 1.19's internal/trace, but has been optimized to be faster while using less memory and fewer allocations. It has been further modified for the specific purpose of converting traces to the new 1.22+ format.

Index

• Constants
• Variables
• type Event
  • func (ev *Event) String() string
• type Events
  • func (l *Events) All() func(yield func(ev *Event) bool)
  • func (l *Events) Len() int
  • func (l *Events) Less(i, j int) bool
  • func (l *Events) Pop() (*Event, bool)
  • func (l *Events) Ptr(i int) *Event
  • func (l *Events) Swap(i, j int)
• type Frame
• type STWReason
• type Timestamp
• type Trace
  • func Parse(r io.Reader, vers version.Version) (Trace, error)
  • func (tr *Trace) STWReason(kindID uint64) STWReason

Constants

const (
	// Special P identifiers:
	FakeP    = 1000000 + iota
	TimerP   // contains timer unblocks
	NetpollP // contains network unblocks
	SyscallP // contains returns from syscalls
	GCP      // contains GC state
	ProfileP // contains recording of CPU profile samples
)

const (
	EvNone              event.Type = 0  // unused
	EvBatch             event.Type = 1  // start of per-P batch of events [pid, timestamp]
	EvFrequency         event.Type = 2  // contains tracer timer frequency [frequency (ticks per second)]
	EvStack             event.Type = 3  // stack [stack id, number of PCs, array of {PC, func string ID, file string ID, line}]
	EvGomaxprocs        event.Type = 4  // current value of GOMAXPROCS [timestamp, GOMAXPROCS, stack id]
	EvProcStart         event.Type = 5  // start of P [timestamp, thread id]
	EvProcStop          event.Type = 6  // stop of P [timestamp]
	EvGCStart           event.Type = 7  // GC start [timestamp, seq, stack id]
	EvGCDone            event.Type = 8  // GC done [timestamp]
	EvSTWStart          event.Type = 9  // GC mark termination start [timestamp, kind]
	EvSTWDone           event.Type = 10 // GC mark termination done [timestamp]
	EvGCSweepStart      event.Type = 11 // GC sweep start [timestamp, stack id]
	EvGCSweepDone       event.Type = 12 // GC sweep done [timestamp, swept, reclaimed]
	EvGoCreate          event.Type = 13 // goroutine creation [timestamp, new goroutine id, new stack id, stack id]
	EvGoStart           event.Type = 14 // goroutine starts running [timestamp, goroutine id, seq]
	EvGoEnd             event.Type = 15 // goroutine ends [timestamp]
	EvGoStop            event.Type = 16 // goroutine stops (like in select{}) [timestamp, stack]
	EvGoSched           event.Type = 17 // goroutine calls Gosched [timestamp, stack]
	EvGoPreempt         event.Type = 18 // goroutine is preempted [timestamp, stack]
	EvGoSleep           event.Type = 19 // goroutine calls Sleep [timestamp, stack]
	EvGoBlock           event.Type = 20 // goroutine blocks [timestamp, stack]
	EvGoUnblock         event.Type = 21 // goroutine is unblocked [timestamp, goroutine id, seq, stack]
	EvGoBlockSend       event.Type = 22 // goroutine blocks on chan send [timestamp, stack]
	EvGoBlockRecv       event.Type = 23 // goroutine blocks on chan recv [timestamp, stack]
	EvGoBlockSelect     event.Type = 24 // goroutine blocks on select [timestamp, stack]
	EvGoBlockSync       event.Type = 25 // goroutine blocks on Mutex/RWMutex [timestamp, stack]
	EvGoBlockCond       event.Type = 26 // goroutine blocks on Cond [timestamp, stack]
	EvGoBlockNet        event.Type = 27 // goroutine blocks on network [timestamp, stack]
	EvGoSysCall         event.Type = 28 // syscall enter [timestamp, stack]
	EvGoSysExit         event.Type = 29 // syscall exit [timestamp, goroutine id, seq, real timestamp]
	EvGoSysBlock        event.Type = 30 // syscall blocks [timestamp]
	EvGoWaiting         event.Type = 31 // denotes that goroutine is blocked when tracing starts [timestamp, goroutine id]
	EvGoInSyscall       event.Type = 32 // denotes that goroutine is in syscall when tracing starts [timestamp, goroutine id]
	EvHeapAlloc         event.Type = 33 // gcController.heapLive change [timestamp, heap live bytes]
	EvHeapGoal          event.Type = 34 // gcController.heapGoal change [timestamp, heap goal bytes]
	EvTimerGoroutine    event.Type = 35 // denotes timer goroutine [timer goroutine id]
	EvFutileWakeup      event.Type = 36 // denotes that the previous wakeup of this goroutine was futile [timestamp]
	EvString            event.Type = 37 // string dictionary entry [ID, length, string]
	EvGoStartLocal      event.Type = 38 // goroutine starts running on the same P as the last event [timestamp, goroutine id]
	EvGoUnblockLocal    event.Type = 39 // goroutine is unblocked on the same P as the last event [timestamp, goroutine id, stack]
	EvGoSysExitLocal    event.Type = 40 // syscall exit on the same P as the last event [timestamp, goroutine id, real timestamp]
	EvGoStartLabel      event.Type = 41 // goroutine starts running with label [timestamp, goroutine id, seq, label string id]
	EvGoBlockGC         event.Type = 42 // goroutine blocks on GC assist [timestamp, stack]
	EvGCMarkAssistStart event.Type = 43 // GC mark assist start [timestamp, stack]
	EvGCMarkAssistDone  event.Type = 44 // GC mark assist done [timestamp]
	EvUserTaskCreate    event.Type = 45 // trace.NewTask [timestamp, internal task id, internal parent id, stack, name string]
	EvUserTaskEnd       event.Type = 46 // end of task [timestamp, internal task id, stack]
	EvUserRegion        event.Type = 47 // trace.WithRegion [timestamp, internal task id, mode(0:start, 1:end), name string]
	EvUserLog           event.Type = 48 // trace.Log [timestamp, internal id, key string id, stack, value string]
	EvCPUSample         event.Type = 49 // CPU profiling sample [timestamp, stack, real timestamp, real P id (-1 when absent), goroutine id]
	EvCount             event.Type = 50
)

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

Variables

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.

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

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 a real P or one of TimerP, NetpollP, SyscallP)
	Type  event.Type // one of Ev*
}

Event describes one event in the trace.

func (*Event) String

func (ev *Event) String() string

type Events

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

func (*Events) All

func (l *Events) All() func(yield func(ev *Event) bool)

func (*Events) Len

func (l *Events) Len() int

func (*Events) Less

func (l *Events) Less(i, j int) bool

func (*Events) Pop

func (l *Events) Pop() (*Event, bool)

func (*Events) Ptr

func (l *Events) Ptr(i int) *Event

func (*Events) Swap

func (l *Events) Swap(i, j int)

type Frame

type Frame struct {
	PC uint64
	// string ID of the function name
	Fn uint64
	// string ID of the file name
	File uint64
	Line int
}

Frame is a frame in stack traces.

type STWReason

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
)

type Timestamp

type Timestamp int64

Timestamp represents a count of nanoseconds since the beginning of the trace. They can only be meaningfully compared with other timestamps from the same trace.

type Trace

type Trace struct {
	Version version.Version

	// Events is the sorted list of Events in the trace.
	Events Events
	// Stacks is the stack traces (stored as slices of PCs), keyed by stack IDs
	// from the trace.
	Stacks        map[uint32][]uint64
	PCs           map[uint64]Frame
	Strings       map[uint64]string
	InlineStrings []string
}

Trace is the result of Parse.

func Parse

func Parse(r io.Reader, vers version.Version) (Trace, error)

Parse parses Go execution traces from versions 1.11–1.21. The provided reader will be read to completion and the entire trace will be materialized in memory. That is, this function does not allow incremental parsing.

The reader has to be positioned just after the trace header and vers needs to be the version of the trace. This can be achieved by using version.ReadHeader.

func (*Trace) STWReason

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