probe

Documentation

Overview

Package probe provides instrumentation probe types and definitions.

Index

• type AllocationConst
  • func (c AllocationConst) InjectOption(td *process.TargetDetails) (inject.Option, error)
• type Base
  • func (i *Base[BPFObj, BPFEvent]) Close() error
  • func (i *Base[BPFObj, BPFEvent]) Load(exec *link.Executable, td *process.TargetDetails) error
  • func (i *Base[BPFObj, BPFEvent]) Manifest() Manifest
  • func (i *Base[BPFObj, BPFEvent]) Run(dest chan<- *Event)
• type Const
• type Event
• type ID
  • func (id ID) String() string
• type KeyValConst
  • func (c KeyValConst) InjectOption(*process.TargetDetails) (inject.Option, error)
• type Manifest
  • func NewManifest(id ID, structfields []structfield.ID, symbols []string) Manifest
• type Probe
• type RegistersABIConst
  • func (c RegistersABIConst) InjectOption(td *process.TargetDetails) (inject.Option, error)
• type SpanEvent
• type Status
• type StructFieldConst
  • func (c StructFieldConst) InjectOption(td *process.TargetDetails) (inject.Option, error)
• type Uprobe
• type UprobeFunc

Types

type AllocationConst

type AllocationConst struct{}

AllocationConst is a Const for all the allocation details that need to be injected into an eBPF program.

func (AllocationConst) InjectOption

func (c AllocationConst) InjectOption(td *process.TargetDetails) (inject.Option, error)

InjectOption returns the appropriately configured inject.WithAllocationDetails if the process.AllocationDetails within td are not nil. An error is returned if process.AllocationDetails is nil.

type Base

type Base[BPFObj any, BPFEvent any] struct {
	// ID is a unique identifier for the probe.
	ID ID
	// Logger is used to log operations and errors.
	Logger logr.Logger

	// Consts are the constants that need to be injected into the eBPF program
	// that is run by this Probe.
	Consts []Const
	// Uprobes is a the collection of eBPF programs that need to be attached to
	// the target process.
	Uprobes []Uprobe[BPFObj]

	// ReaderFn is a creation function for a perf.Reader based on the passed
	// BPFObj related to the probe.
	ReaderFn func(BPFObj) (*perf.Reader, error)
	// SpecFn is a creation function for an eBPF CollectionSpec related to the
	// probe.
	SpecFn func() (*ebpf.CollectionSpec, error)
	// ProcessFn processes probe events into a uniform Event type.
	ProcessFn func(*BPFEvent) *SpanEvent
	// contains filtered or unexported fields
}

Base is a base implementation of Probe.

This type can be returned by instrumentation directly. Instrumentation can also wrap this implementation with their own type if they need to override default behavior.

func (*Base[BPFObj, BPFEvent]) Close

func (i *Base[BPFObj, BPFEvent]) Close() error

Close stops the Probe.

func (*Base[BPFObj, BPFEvent]) Load

func (i *Base[BPFObj, BPFEvent]) Load(exec *link.Executable, td *process.TargetDetails) error

Load loads all instrumentation offsets.

func (*Base[BPFObj, BPFEvent]) Manifest

func (i *Base[BPFObj, BPFEvent]) Manifest() Manifest

Manifest returns the Probe's instrumentation Manifest.

func (*Base[BPFObj, BPFEvent]) Run

func (i *Base[BPFObj, BPFEvent]) Run(dest chan<- *Event)

Run runs the events processing loop.

type Const

type Const interface {
	// InjectOption returns the inject.Option to run for the Const when running
	// inject.Constants.
	InjectOption(td *process.TargetDetails) (inject.Option, error)
}

Const is an constant that needs to be injected into an eBPF program.

type Event

type Event struct {
	Package string
	Kind    trace.SpanKind
	SpanEvent
}

Event is a telemetry event that happens within an instrumented package.

type ID

type ID struct {
	// SpanKind is the span kind handled by the probe.
	SpanKind trace.SpanKind
	// InstrumentedPkg is the package path of the instrumented code.
	InstrumentedPkg string
}

ID is a unique identifier for a probe.

func (ID) String

func (id ID) String() string

type KeyValConst

type KeyValConst struct {
	Key string
	Val interface{}
}

KeyValConst is a Const for a generic key-value pair.

This should not be used as a replacement for any of the other provided Const implementations. Those implementations may have added significance and should be used instead where applicable.

func (KeyValConst) InjectOption

func (c KeyValConst) InjectOption(*process.TargetDetails) (inject.Option, error)

InjectOption returns the appropriately configured inject.WithKeyValue.

type Manifest

type Manifest struct {
	// ID is a unique identifier for the probe.
	Id ID

	// StructFields are the struct fields in an instrumented package that are
	// used for instrumentation.
	StructFields []structfield.ID

	// Symbols are the runtime symbols that are used to attach a probe's eBPF
	// program to a perf events.
	Symbols []string
}

Manifest contains information about a package being instrumented.

func NewManifest

func NewManifest(id ID, structfields []structfield.ID, symbols []string) Manifest

NewManifest returns a new Manifest for the instrumentation probe with name that instruments pkg. The structfields and symbols will be sorted in-place and added directly to the returned Manifest.

type Probe

type Probe interface {
	// Manifest returns the Probe's instrumentation Manifest. This includes all
	// the information about the package the Probe instruments.
	Manifest() Manifest

	// Load loads all instrumentation offsets.
	Load(*link.Executable, *process.TargetDetails) error

	// Run runs the events processing loop.
	Run(eventsChan chan<- *Event)

	// Close stops the Probe.
	Close() error
}

Probe is the instrument used by instrumentation for a Go package to measure and report on the state of that packages operation.

type RegistersABIConst

type RegistersABIConst struct{}

RegistersABIConst is a Const for the boolean flag informing an eBPF program if the Go space has registered ABI.

func (RegistersABIConst) InjectOption

func (c RegistersABIConst) InjectOption(td *process.TargetDetails) (inject.Option, error)

InjectOption returns the appropriately configured inject.WithRegistersABI.

type SpanEvent

type SpanEvent struct {
	SpanName          string
	Attributes        []attribute.KeyValue
	StartTime         int64
	EndTime           int64
	SpanContext       *trace.SpanContext
	ParentSpanContext *trace.SpanContext
	Status            Status
}

type Status

type Status struct {
	Code        codes.Code
	Description string
}

type StructFieldConst

type StructFieldConst struct {
	Key string
	Val structfield.ID
}

StructFieldConst is a Const for a struct field offset. These struct field ID needs to be known offsets in the inject package.

func (StructFieldConst) InjectOption

func (c StructFieldConst) InjectOption(td *process.TargetDetails) (inject.Option, error)

InjectOption returns the appropriately configured inject.WithOffset if the version of the struct field module is known. If it is not, an error is returned.

type Uprobe

type Uprobe[BPFObj any] struct {
	// Sym is the symbol name of the function to attach the eBPF program to.
	Sym string
	// Fn is the function that will attach the eBPF program to the function.
	Fn UprobeFunc[BPFObj]
	// Optional is a boolean flag informing if the Uprobe is optional. If the
	// Uprobe is optional and fails to attach, the error is logged and
	// processing continues.
	Optional bool
}

Uprobe is an eBPF program that is attached in the entry point and/or the reutrn of a function.

type UprobeFunc

type UprobeFunc[BPFObj any] func(symbol string, exec *link.Executable, target *process.TargetDetails, obj *BPFObj) ([]link.Link, error)

UprobeFunc is a function that will attach a eBPF program to a perf event that fires when the given symbol starts executing in exec.

It is expected the symbol belongs to are shared library and its offset can be determined using target.

Losing the reference to the resulting Link (up) will close the Uprobe and prevent further execution of prog. The Link must be Closed during program shutdown to avoid leaking system resources.