profile

Documentation

Overview

Package profile is the storage tier's EXPLAIN ANALYZE: a profiled tree of the fetch operators with per-node timing and I/O counters, showing where and how much time a query spent (which parts were scanned vs pruned, rows in/out, bytes decoded). The library owns the fetch-tier subtree; an embedder's query engine splices it under its own language operators (DESIGN §16.5).

It is opt-in and zero-overhead when off: a caller installs a collector with WithCollector and reads Collector.Root after the fetch; operators call Begin (a no-op when no collector is in ctx, so the default fetch path makes no timing reads or allocations). It is safe for the concurrent fan-out a split/cluster fetch performs.

Index

• func Active(ctx context.Context) bool
• func Graft(ctx context.Context, sub *Node)
• type Collector
  • func WithCollector(ctx context.Context) (context.Context, *Collector)
  • func (c *Collector) Root() *Node
• type Handle
  • func Begin(ctx context.Context, name string) (context.Context, *Handle)
  • func (h *Handle) Add(key string, n int64)
  • func (h *Handle) End()
• type Node
  • func Decode(data []byte) (*Node, []byte, error)
  • func (n *Node) Encode(dst []byte) []byte
  • func (n *Node) Render() string
  • func (n *Node) SelfDur() time.Duration

Functions

func Active

func Active(ctx context.Context) bool

Active reports whether a profile collector is installed in ctx — i.e. whether the caller asked for EXPLAIN ANALYZE. A cluster client uses it to request a profile from a peer only when one is being collected.

func Graft

func Graft(ctx context.Context, sub *Node)

Graft attaches an already-built subtree (e.g. a peer's profile returned over the read RPC) as a child of the current node in ctx. No-op when no collector is installed or sub is nil.

Types

type Collector

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

Collector accumulates a profile tree. Safe for concurrent Begin/End across fan-out sub-fetches.

func WithCollector

func WithCollector(ctx context.Context) (context.Context, *Collector)

WithCollector installs a fresh collector rooted at a "query" node and returns it. Operators below (via Begin) attach to this root. Reading Collector.Root after the fetch yields the tree.

func (*Collector) Root

func (c *Collector) Root() *Node

Root returns the completed tree (call after the fetch finishes).

type Handle

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

Handle is an open operator node; End it (defer) when the operator finishes, and Add counters to it. A nil Handle is valid and no-ops, which is what Begin returns when no collector is installed.

func Begin

func Begin(ctx context.Context, name string) (context.Context, *Handle)

Begin starts a child operator named name under the current node in ctx and returns the child ctx (so nested Begin calls attach beneath it) and a Handle to End/Add. When no collector is in ctx it returns ctx unchanged and a nil Handle, so instrumented operators cost nothing off the profiling path.

func (*Handle) Add

func (h *Handle) Add(key string, n int64)

Add increments a counter on the operator (rows, parts, bytes…). Safe on a nil Handle; a zero delta is ignored.

func (*Handle) End

func (h *Handle) End()

End records the operator's wall time. Safe to call on a nil Handle.

type Node

type Node struct {
	Name     string           // operator name (e.g. "engine.fetch", "part-scan")
	Dur      time.Duration    // wall time of this operator (including children)
	Counters map[string]int64 // I/O counters (rows, parts_scanned, bytes_decoded, …)
	Children []*Node
}

Node is one operator in the profiled query tree.

func Decode

func Decode(data []byte) (*Node, []byte, error)

Decode parses a Node.Encode payload, returning the node and the unconsumed tail. It bounds-checks every length so a corrupt or hostile payload never panics or over-allocates.

func (*Node) Encode

func (n *Node) Encode(dst []byte) []byte

Encode appends the binary encoding of the subtree rooted at n to dst (a peer's read RPC returns it so the requester can graft it). The shape is, recursively: name, duration (nanos, varint), sorted counters, then children.

func (*Node) Render

func (n *Node) Render() string

Render returns the tree as an EXPLAIN ANALYZE-style indented listing: per node its name, wall time, self time (when it has children), and sorted counters, one node per line.

func (*Node) SelfDur

func (n *Node) SelfDur() time.Duration

SelfDur is the time spent in this node excluding its children.