ptrace

Documentation

Overview

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

Index

• func ComputeProcessorBusy(tr *Trace, p *Processor, bucketSize time.Duration) []int
• type EventID
• type Function
  • func (fn Function) String() string
• type Goroutine
  • func (g *Goroutine) EffectiveEnd() trace.Timestamp
  • func (g *Goroutine) EffectiveStart() trace.Timestamp
• type Machine
• type Point
• type Processor
• type SchedulingState
• type Span
  • func (s *Span) Duration() time.Duration
  • func (s *Span) Events(all []EventID, tr *Trace) []EventID
• type SpanTags
• type Spans
  • func ToSpans(spans []Span) Spans
• type Statistic
• type Statistics
  • func ComputeStatistics(spans Spans) Statistics
  • func (stat *Statistics) Blocked() time.Duration
  • func (stat *Statistics) GCAssist() time.Duration
  • func (stat *Statistics) Inactive() time.Duration
  • func (stat *Statistics) Running() time.Duration
• type Task
  • func (t *Task) Stub() bool
• type Trace
  • func Parse(res trace.Trace, progress func(float64)) (*Trace, error)
  • func (t *Trace) End() trace.Timestamp
  • func (t *Trace) Event(ev EventID) *trace.Event
  • func (tr *Trace) G(gid uint64) *Goroutine
  • func (tr *Trace) P(pid int32) *Processor
  • func (t *Trace) Task(id uint64) *Task

Functions

func ComputeProcessorBusy

func ComputeProcessorBusy(tr *Trace, p *Processor, bucketSize time.Duration) []int

Types

type EventID

type EventID int32

type Function

type Function struct {
	trace.Frame
	// Sequential ID of function in the trace
	SeqID      int
	Goroutines []*Goroutine
}

func (Function) String

func (fn Function) String() string

type Goroutine

type Goroutine struct {
	ID     uint64
	Parent uint64
	// Sequential ID of goroutine in the trace
	SeqID    int
	Function *Function
	Spans    []Span
	// The actual Start and end times of the goroutine. While spans are bounded to 0 and the end of the trace, the
	// actual Start and end of the goroutine might be unknown.
	Start       container.Option[trace.Timestamp]
	End         container.Option[trace.Timestamp]
	UserRegions [][]Span
	Events      []EventID
}

func (*Goroutine) EffectiveEnd

func (g *Goroutine) EffectiveEnd() trace.Timestamp

func (*Goroutine) EffectiveStart

func (g *Goroutine) EffectiveStart() trace.Timestamp

type Machine

type Machine struct {
	ID int32
	// Sequential ID of machine in the trace
	SeqID int
	// OPT(dh): using Span for Ms is wasteful. We don't need tags, stacktrace offsets etc. We only care about what
	// processor is running at what time. The only benefit of reusing Span is that we can use the same code for
	// rendering Gs and Ms, but that doesn't seem worth the added cost.
	Spans      []Span
	Goroutines []Span
}

type Point

type Point struct {
	When  trace.Timestamp
	Value uint64
}

type Processor

type Processor struct {
	ID int32
	// Sequential ID of processor in the trace
	SeqID int
	// OPT(dh): using Span for Ps is wasteful. We don't need tags, stacktrace offsets etc. We only care about what
	// goroutine is running at what time. The only benefit of reusing Span is that we can use the same code for
	// rendering Gs and Ps, but that doesn't seem worth the added cost.
	Spans []Span
}

type SchedulingState

type SchedulingState uint8

const (
	StateNone SchedulingState = iota

	// Goroutine states
	StateInactive
	StateActive
	StateGCIdle
	StateGCDedicated
	StateGCFractional
	StateBlocked
	StateBlockedSend
	StateBlockedRecv
	StateBlockedSelect
	StateBlockedSync
	StateBlockedSyncOnce
	StateBlockedSyncTriggeringGC
	StateBlockedCond
	StateBlockedNet
	StateBlockedGC
	StateBlockedSyscall
	StateStuck
	StateReady
	StateCreated
	StateDone
	StateGCMarkAssist
	StateGCSweep

	// Special states used by user regions and stack frames
	StateUserRegion
	StateStack
	StateCPUSample

	// Processor states
	StateRunningG

	// Machine states
	StateRunningP

	StateLast
)

type Span

type Span struct {
	Start trace.Timestamp
	End   trace.Timestamp
	Event EventID
	// At is an offset from the top of the stack, skipping over uninteresting runtime frames.
	At uint8
	// We track the scheduling State explicitly, instead of mapping from trace.Event.Type, because we apply pattern
	// matching to stack traces that may result in more accurate states. For example, we can determine
	// stateBlockedSyncOnce from the stack trace, and we would otherwise use stateBlockedSync.
	State SchedulingState
	Tags  SpanTags
}

func (*Span) Duration

func (s *Span) Duration() time.Duration

func (*Span) Events

func (s *Span) Events(all []EventID, tr *Trace) []EventID

type SpanTags

type SpanTags uint8

const (
	SpanTagNetwork SpanTags = 1 << iota
	SpanTagTCP
	SpanTagTLS
	SpanTagRead
	SpanTagAccept
	SpanTagDial
	SpanTagHTTP

	// Used for spans of GC goroutines, used when choosing span colors for processor timelines.
	SpanTagGC
)

type Spans

type Spans interface {
	AtPtr(idx int) *Span
	Len() int
}

Spans is an interface that allows ComputeStatistics to operate on abstract collections of spans, not just slices.

func ToSpans

func ToSpans(spans []Span) Spans

type Statistic

type Statistic struct {
	Count           int
	Min, Max, Total time.Duration
	Average, Median float64
}

type Statistics

type Statistics [StateLast]Statistic

func ComputeStatistics

func ComputeStatistics(spans Spans) Statistics

func (*Statistics) Blocked

func (stat *Statistics) Blocked() time.Duration

func (*Statistics) GCAssist

func (stat *Statistics) GCAssist() time.Duration

func (*Statistics) Inactive

func (stat *Statistics) Inactive() time.Duration

func (*Statistics) Running

func (stat *Statistics) Running() time.Duration

type Task

type Task struct {
	// OPT(dh): Technically we only need the EventID field, everything else can be extracted from the event on demand.
	// But there are probably not enough tasks to make that worth it.
	ID uint64
	// Sequential ID of task in the trace
	SeqID int
	Name  string
	Event EventID
}

func (*Task) Stub

func (t *Task) Stub() bool

type Trace

type Trace struct {
	// OPT(dh): can we get rid of all these pointers?
	Goroutines []*Goroutine
	Processors []*Processor
	Machines   []*Machine
	Functions  map[string]*Function
	GC         []Span
	STW        []Span
	Tasks      []*Task
	HeapSize   []Point
	HeapGoal   []Point
	// Mapping from Goroutine ID to list of CPU sample events
	CPUSamples map[uint64][]EventID

	HasCPUSamples bool

	trace.Trace
	// contains filtered or unexported fields
}

func Parse

func Parse(res trace.Trace, progress func(float64)) (*Trace, error)

func (*Trace) End

func (t *Trace) End() trace.Timestamp

func (*Trace) Event

func (t *Trace) Event(ev EventID) *trace.Event

func (*Trace) G

func (tr *Trace) G(gid uint64) *Goroutine

func (*Trace) P

func (tr *Trace) P(pid int32) *Processor

func (*Trace) Task

func (t *Trace) Task(id uint64) *Task