Documentation ¶
Overview ¶
Package probe provides instrumentation probe types and definitions.
Index ¶
- Constants
- type AllocationConst
- 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 FunctionSymbol
- type ID
- type KeyValConst
- type Manifest
- type Probe
- type RegistersABIConst
- type SpanProducer
- type StructFieldConst
- type StructFieldConstMinVersion
- type TraceProducer
- type Uprobe
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" )
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]) 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.
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 ¶
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.
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 ¶
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 // 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.