probe

Documentation

Overview

Package probe provides instrumentation probe types and definitions.

Index

• Constants
• 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]) InjectConsts(td *process.TargetDetails, spec *ebpf.CollectionSpec) error
  • func (i *Base[BPFObj, BPFEvent]) Load(exec *link.Executable, td *process.TargetDetails, sampler *sampling.Config) error
  • func (i *Base[BPFObj, BPFEvent]) Manifest() Manifest
  • func (i *Base[BPFObj, BPFEvent]) Spec() (*ebpf.CollectionSpec, error)
• type Const
• type FailureMode
• type FunctionSymbol
• 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 []FunctionSymbol) Manifest
• type PackageConstraints
• type Probe
• type SpanProducer
  • func (i *SpanProducer[BPFObj, BPFEvent]) Run(handle func(ptrace.ScopeSpans))
• type StructFieldConst
  • func (c StructFieldConst) InjectOption(td *process.TargetDetails) (inject.Option, error)
  • func (c StructFieldConst) SetLogger(l *slog.Logger) Const
• type StructFieldConstMaxVersion
  • func (c StructFieldConstMaxVersion) InjectOption(td *process.TargetDetails) (inject.Option, error)
• type StructFieldConstMinVersion
  • func (c StructFieldConstMinVersion) InjectOption(td *process.TargetDetails) (inject.Option, error)
• type TraceProducer
  • func (i *TraceProducer[BPFObj, BPFEvent]) Run(handle func(ptrace.ScopeSpans))
• type Uprobe
  • func (u *Uprobe) Close() error

Constants

const (
	// The default size of the perf buffer in pages.
	// We will need to make this configurable in the future.
	PerfBufferDefaultSizeInPages = 128
	// The default name of the eBPF map used to pass events from the eBPF program
	// to userspace.
	DefaultBufferMapName = "events"
)

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 *slog.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

	// SpecFn is a creation function for an eBPF CollectionSpec related to the
	// probe.
	SpecFn func() (*ebpf.CollectionSpec, error)
	// ProcessRecord is an optional processing function for the probe. If nil,
	// all records will be read directly into a new BPFEvent using the
	// encoding/binary package.
	ProcessRecord func(perf.Record) (*BPFEvent, error)
	// 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]) InjectConsts

func (i *Base[BPFObj, BPFEvent]) InjectConsts(td *process.TargetDetails, spec *ebpf.CollectionSpec) error

func (*Base[BPFObj, BPFEvent]) Load

func (i *Base[BPFObj, BPFEvent]) Load(exec *link.Executable, td *process.TargetDetails, sampler *sampling.Config) 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]) Spec

func (i *Base[BPFObj, BPFEvent]) Spec() (*ebpf.CollectionSpec, error)

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 FailureMode

type FailureMode int

FailureMode defines the behavior that is performed when a failure occurs.

const (
	// FailureModeError will cause an error to be returned if a failure occurs.
	FailureModeError FailureMode = iota
	// FailureModeWarn will cause a warning message to be logged and allow
	// operations to continue if a failure occurs.
	FailureModeWarn
	// FailureModeIgnore will continue operations and ignore any failure that
	// occurred.
	FailureModeIgnore
)

type FunctionSymbol

type FunctionSymbol struct {
	Symbol    string
	DependsOn []string
}

Wrapper object for the Manifest function symbol.

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 []FunctionSymbol
}

Manifest contains information about a package being instrumented.

func NewManifest

func NewManifest(id ID, structfields []structfield.ID, symbols []FunctionSymbol) 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 PackageConstraints

type PackageConstraints struct {
	// Package is the package import path that this constraint applies to.
	Package string
	// Constraints is the version constraint that is evaluated. If the
	// constraint is not satisfied, the FailureMode defines the behavior of how
	// the failure is handled.
	Constraints *semver.Constraints
	// FailureMode defines the behavior that is performed when the Constraint
	// is not satisfied.
	FailureMode FailureMode
}

PackageConstraints is a versioning requirement for a package.

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 the eBPF programs and maps required by the Probe.
	// It also attaches the eBPF programs to the target process.
	// TODO: currently passing Sampler as an initial configuration - this will be
	// updated to a more generic configuration in the future.
	Load(*link.Executable, *process.TargetDetails, *sampling.Config) error

	// Run runs the events processing loop.
	Run(func(ptrace.ScopeSpans))

	// 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 SpanProducer

type SpanProducer[BPFObj any, BPFEvent any] struct {
	Base[BPFObj, BPFEvent]

	Version   string
	SchemaURL string
	ProcessFn func(*BPFEvent) ptrace.SpanSlice
}

func (*SpanProducer[BPFObj, BPFEvent]) Run

func (i *SpanProducer[BPFObj, BPFEvent]) Run(handle func(ptrace.ScopeSpans))

Run runs the events processing loop.

type StructFieldConst

type StructFieldConst struct {
	Key string
	ID  structfield.ID
	// contains filtered or unexported fields
}

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.

func (StructFieldConst) SetLogger

func (c StructFieldConst) SetLogger(l *slog.Logger) Const

SetLogger sets the Logger for StructFieldConst operations.

type StructFieldConstMaxVersion

type StructFieldConstMaxVersion struct {
	StructField StructFieldConst
	// MaxVersion is the exclusive maximum version (it will only match versions
	// less than this).
	MaxVersion *semver.Version
}

StructFieldConstMaxVersion is a Const for a struct field offset. These struct field ID needs to be known offsets in the inject package. The offset is only injected if the module version is less than the MaxVersion.

func (StructFieldConstMaxVersion) InjectOption

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

InjectOption returns the appropriately configured inject.WithOffset if the version of the struct field module is known and is less than the MaxVersion. If the module version is not known, an error is returned. If the module version is known but is greater than or equal to the MaxVersion, no offset is injected.

type StructFieldConstMinVersion

type StructFieldConstMinVersion struct {
	StructField StructFieldConst
	MinVersion  *semver.Version
}

StructFieldConstMinVersion is a Const for a struct field offset. These struct field ID needs to be known offsets in the inject package. The offset is only injected if the module version is greater than or equal to the MinVersion.

func (StructFieldConstMinVersion) InjectOption

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

InjectOption returns the appropriately configured inject.WithOffset if the version of the struct field module is known and is greater than or equal to the MinVersion. If the module version is not known, an error is returned. If the module version is known but is less than the MinVersion, no offset is injected.

type TraceProducer

type TraceProducer[BPFObj any, BPFEvent any] struct {
	Base[BPFObj, BPFEvent]

	ProcessFn func(*BPFEvent) ptrace.ScopeSpans
}

func (*TraceProducer[BPFObj, BPFEvent]) Run

func (i *TraceProducer[BPFObj, BPFEvent]) Run(handle func(ptrace.ScopeSpans))

Run runs the events processing loop.

type Uprobe

type Uprobe struct {
	// Sym is the symbol name of the function to attach the eBPF program to.
	Sym string
	// PackageConstraints are the evaluated when the Uprobe is loaded.
	PackageConstraints []PackageConstraints
	// FailureMode defines the behavior that is performed when the Uprobe fails
	// to attach.
	FailureMode FailureMode
	// EntryProbe is the name of the eBPF program to attach to the entry of the
	// function specified by Sym. If EntryProbe is empty, no eBPF program will be attached to the entry of the function.
	EntryProbe string
	// ReturnProbe is the name of the eBPF program to attach to the return of the
	// function specified by Sym. If ReturnProbe is empty, no eBPF program will be attached to the return of the function.
	ReturnProbe string
	DependsOn   []string
	// contains filtered or unexported fields
}

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

func (*Uprobe) Close

func (u *Uprobe) Close() error