trace

Documentation

Overview

Package trace is an externally-importable copy of internal/trace.

Index

• Constants
• Variables
• func GoroutineStats(events []*Event) map[uint64]*GDesc
• func Print(events []*Event)
• func PrintEvent(ev *Event)
• func RelatedGoroutines(events []*Event, goid uint64) map[uint64]bool
• type Event
  • func Parse(r io.Reader, bin string) ([]*Event, error)
• type Frame
• type GDesc
• type Writer
  • func NewWriter() *Writer
  • func (w *Writer) Emit(typ byte, args ...uint64)

Constants

const (
	// Special P identifiers:
	FakeP    = 1000000 + iota
	TimerP   // depicts timer unblocks
	NetpollP // depicts network unblocks
	SyscallP // depicts returns from syscalls
	GCP      // depicts GC state
)

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]
	EvGCScanStart    = 9  // GC mark termination start [timestamp]
	EvGCScanDone     = 10 // GC mark termination done [timestamp]
	EvGCSweepStart   = 11 // GC sweep start [timestamp, stack id]
	EvGCSweepDone    = 12 // GC sweep done [timestamp]
	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 // memstats.heap_live change [timestamp, heap_alloc]
	EvNextGC         = 34 // memstats.next_gc change [timestamp, next_gc]
	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]
	EvCount          = 43
)

Event types in the trace. Verbatim copy from src/runtime/trace.go.

Variables

var BreakTimestampsForTesting bool

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

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.

var EventDescriptions = [EvCount]struct {
	Name       string
	minVersion int
	Stack      bool
	Args       []string
}{
	EvNone:           {"None", 1005, false, []string{}},
	EvBatch:          {"Batch", 1005, false, []string{"p", "ticks"}},
	EvFrequency:      {"Frequency", 1005, false, []string{"freq"}},
	EvStack:          {"Stack", 1005, false, []string{"id", "siz"}},
	EvGomaxprocs:     {"Gomaxprocs", 1005, true, []string{"procs"}},
	EvProcStart:      {"ProcStart", 1005, false, []string{"thread"}},
	EvProcStop:       {"ProcStop", 1005, false, []string{}},
	EvGCStart:        {"GCStart", 1005, true, []string{"seq"}},
	EvGCDone:         {"GCDone", 1005, false, []string{}},
	EvGCScanStart:    {"GCScanStart", 1005, false, []string{}},
	EvGCScanDone:     {"GCScanDone", 1005, false, []string{}},
	EvGCSweepStart:   {"GCSweepStart", 1005, true, []string{}},
	EvGCSweepDone:    {"GCSweepDone", 1005, false, []string{}},
	EvGoCreate:       {"GoCreate", 1005, true, []string{"g", "stack"}},
	EvGoStart:        {"GoStart", 1005, false, []string{"g", "seq"}},
	EvGoEnd:          {"GoEnd", 1005, false, []string{}},
	EvGoStop:         {"GoStop", 1005, true, []string{}},
	EvGoSched:        {"GoSched", 1005, true, []string{}},
	EvGoPreempt:      {"GoPreempt", 1005, true, []string{}},
	EvGoSleep:        {"GoSleep", 1005, true, []string{}},
	EvGoBlock:        {"GoBlock", 1005, true, []string{}},
	EvGoUnblock:      {"GoUnblock", 1005, true, []string{"g", "seq"}},
	EvGoBlockSend:    {"GoBlockSend", 1005, true, []string{}},
	EvGoBlockRecv:    {"GoBlockRecv", 1005, true, []string{}},
	EvGoBlockSelect:  {"GoBlockSelect", 1005, true, []string{}},
	EvGoBlockSync:    {"GoBlockSync", 1005, true, []string{}},
	EvGoBlockCond:    {"GoBlockCond", 1005, true, []string{}},
	EvGoBlockNet:     {"GoBlockNet", 1005, true, []string{}},
	EvGoSysCall:      {"GoSysCall", 1005, true, []string{}},
	EvGoSysExit:      {"GoSysExit", 1005, false, []string{"g", "seq", "ts"}},
	EvGoSysBlock:     {"GoSysBlock", 1005, false, []string{}},
	EvGoWaiting:      {"GoWaiting", 1005, false, []string{"g"}},
	EvGoInSyscall:    {"GoInSyscall", 1005, false, []string{"g"}},
	EvHeapAlloc:      {"HeapAlloc", 1005, false, []string{"mem"}},
	EvNextGC:         {"NextGC", 1005, false, []string{"mem"}},
	EvTimerGoroutine: {"TimerGoroutine", 1005, false, []string{"g"}},
	EvFutileWakeup:   {"FutileWakeup", 1005, false, []string{}},
	EvString:         {"String", 1007, false, []string{}},
	EvGoStartLocal:   {"GoStartLocal", 1007, false, []string{"g"}},
	EvGoUnblockLocal: {"GoUnblockLocal", 1007, true, []string{"g"}},
	EvGoSysExitLocal: {"GoSysExitLocal", 1007, false, []string{"g", "ts"}},
	EvGoStartLabel:   {"GoStartLabel", 1008, false, []string{"g", "seq", "label"}},
	EvGoBlockGC:      {"GoBlockGC", 1008, true, []string{}},
}

Functions

func GoroutineStats

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

GoroutineStats generates statistics for all goroutines in the trace.

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 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 {
	Off  int  // offset in input file (for debugging and error reporting)
	Type byte // one of Ev*

	Ts    int64     // timestamp in nanoseconds
	P     int       // P on which the event happened (can be one of TimerP, NetpollP, SyscallP)
	G     uint64    // G on which the event happened
	StkID uint64    // unique stack ID
	Stk   []*Frame  // stack trace (can be empty)
	Args  [3]uint64 // event-type-specific arguments
	SArgs []string  // event-type-specific string args
	// linked event (can be nil), depends on event type:
	// for GCStart: the GCStop
	// for GCScanStart: the GCScanDone
	// 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
	Link *Event
	// contains filtered or unexported fields
}

Event describes one event in the trace.

func Parse

func Parse(r io.Reader, bin string) ([]*Event, error)

Parse parses, post-processes and verifies the trace.

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

	ExecTime      int64
	SchedWaitTime int64
	IOTime        int64
	BlockTime     int64
	SyscallTime   int64
	GCTime        int64
	SweepTime     int64
	TotalTime     int64
	// contains filtered or unexported fields
}

GDesc contains statistics about execution of a single goroutine.

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.