Documentation
¶
Overview ¶
Package stacks is a trace kind that dumps the stacks of the processes of a tree at each checkpoint its host marks, storing one record per goroutine of a Go dump, or one per dump of a native one. Dumps go over the transports a host registers in Dumpers.
Index ¶
- Constants
- Variables
- func AskGops(ctx context.Context, addr string, request byte) ([]byte, error)
- func FetchPProf(ctx context.Context, addr, profile, query string) ([]byte, error)
- func NewKind(dumpers *Dumpers) *tracing.Handler[Params, Stack]
- type AddressFunc
- type CheckpointParams
- type Dump
- type Dumper
- type Dumpers
- type Frame
- type NativeOptions
- type Params
- type Stack
- type Target
Constants ¶
const ( // FormatGo is a Go goroutine dump, as runtime/pprof's goroutine profile // writes it at debug=2 and a Go process prints it as SIGQUIT kills it. FormatGo = "go" // FormatNative is an OS stack sampler's dump of a process's threads. FormatNative = "native" )
The formats a Dump is in.
const ( TransportInProcess = "inprocess" TransportNative = "native" TransportPProf = "pprof" TransportGops = "gops" )
The transports commons-db ships.
const Kind = "stacks"
Kind is the name a host registers the kind as.
Variables ¶
var Text = tracing.ExportFormat{Name: "text", Ext: "txt", MIME: "text/plain"}
Text is the format a window downloads in as the dumps it holds, each checkpoint's in turn.
Functions ¶
func AskGops ¶
AskGops sends the gops agent at addr one signal (github.com/google/gops/signal) and reads its whole reply.
func FetchPProf ¶
FetchPProf reads the net/http/pprof profile named profile ("goroutine", "heap", "profile" for CPU, ...) from the server at addr, with query.
Types ¶
type AddressFunc ¶
AddressFunc is the address of pid's pprof HTTP server or gops agent, as host:port, when it has one.
type CheckpointParams ¶
type CheckpointParams struct {
Key string `json:"key,omitempty"`
PID int `json:"pid,omitempty"`
Transport string `json:"transport,omitempty"`
Reason string `json:"reason,omitempty"`
Dump *Dump `json:"dump,omitempty"`
}
CheckpointParams are what a checkpoint dumps: the stacks of the process Key or PID names, the root when neither does, over Transport, the first available non-destructive one when empty, or Dump, a dump taken elsewhere, such as the goroutines a Go test printed as SIGQUIT killed it, which takes no transport. Reason, such as "periodic", "timeout" or "manual", is recorded with the stacks.
func (CheckpointParams) Validate ¶
func (p CheckpointParams) Validate() error
type Dump ¶
type Dump struct {
Format string `json:"format"`
Text string `json:"text"`
CollectedAt time.Time `json:"collectedAt"`
}
Dump is a process's stacks as one dump took them.
type Dumper ¶
type Dumper interface {
// Transport names it, such as "inprocess", "native", "pprof", "gops" or
// "sigquit".
Transport() string
// Destructive reports whether a dump kills the process, as SIGQUIT does.
Destructive() bool
// Available is nil when this dumper can dump pid, or why it cannot.
Available(pid int) error
Dump(ctx context.Context, pid int) (Dump, error)
}
Dumper dumps the stacks of a process over one transport: it is the stacks kind's transport, which a host provides.
func Gops ¶
func Gops(address AddressFunc) Dumper
Gops dumps the goroutines of a Go process that runs a gops agent at the address address gives.
func InProcess ¶
func InProcess() Dumper
InProcess dumps the goroutines of the host, the one process whose stacks it can read from inside it.
func Native ¶
func Native(options NativeOptions) Dumper
Native samples any process's threads with the OS's stack sampler, without stopping it: sample on darwin, eu-stack or gdb on linux, looked up once, here.
func PProf ¶
func PProf(address AddressFunc) Dumper
PProf dumps the goroutines of a Go process that serves net/http/pprof at the address address gives (/debug/pprof/goroutine?debug=2).
type Dumpers ¶
type Dumpers struct {
// contains filtered or unexported fields
}
Dumpers is the registry of the transports a host's stacks are dumped with, in the order a dump that names none prefers them. One Dumpers is shared, like a process.Sampler, by the stacks kind and the process_tree kind that lists each process's transports.
func NewDumpers ¶
NewDumpers registers dumpers, in order.
func (*Dumpers) Transports ¶
func (d *Dumpers) Transports(pid int) []process.StackTransport
Transports are the transports that can dump pid, in order.
type Frame ¶
type Frame struct {
Func string `json:"func"`
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
}
Frame is one call of a stack.
type NativeOptions ¶
type NativeOptions struct {
// LookPath finds the sampler; nil is exec.LookPath.
LookPath func(file string) (string, error)
// Run runs the sampler at path, its output the stacks it dumped; nil runs
// it as a child process.
Run func(ctx context.Context, path string, args ...string) (string, error)
}
NativeOptions are how the native dumper finds and runs the OS's sampler.
type Params ¶
type Params struct {
// RootPID is the process whose tree is dumped; zero is the host's own.
RootPID int `json:"rootPid,omitempty" clicky:"title=Root PID"`
}
Params choose the tree whose processes a capture dumps.
type Stack ¶
type Stack struct {
tracing.Truncation
CheckpointID string `json:"checkpointId" pretty:"hide" filter:"exact"`
TakenAt time.Time `json:"takenAt" pretty:"label=Taken" sort:"takenAt"`
Reason string `json:"reason,omitempty" filter:"terms"`
Transport string `json:"transport" filter:"terms"`
Key string `json:"key" pretty:"hide" filter:"exact"`
PID int `json:"pid" pretty:"label=PID" filter:"terms"`
Format string `json:"format" filter:"terms"`
GoroutineID int `json:"goroutineId,omitempty" pretty:"label=Goroutine"`
State string `json:"state,omitempty" filter:"terms"`
// WaitMinutes is how long the goroutine has waited in its state, as the
// dump rounds it.
WaitMinutes int `json:"waitMinutes,omitempty" pretty:"label=Waiting (min)" sort:"waitMinutes"`
LockedToThread bool `json:"lockedToThread,omitempty"`
Frames []Frame `json:"frames,omitempty" pretty:"hide"`
CreatedBy *Frame `json:"createdBy,omitempty" pretty:"hide"`
Raw string `json:"raw" pretty:"hide" filter:"none"`
Error string `json:"error,omitempty"`
}
Stack is the record the kind stores: one goroutine of a Go dump, or the whole of a native one, or why a dump failed.
Source Files