probe

package
v0.19.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 5, 2024 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package probe provides instrumentation probe types and definitions.

Index

Constants

View Source
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"
)

Variables

This section is empty.

Functions

This section is empty.

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 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 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 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 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
	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 StructFieldConstMinVersion

type StructFieldConstMinVersion struct {
	StructField StructFieldConst
	MinVersion  *version.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

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

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL