tkbtf

README

Tracing KProbes from BTF (tk-btf)

tk-btf is a Go package to fabricate the string representation of Linux tracing kprobes based on BTF files.

Quick Start

To try out tk-btf have a look at the examples folder.

License

This software is licensed under the Apache License, version 2 ("ALv2"), quoted below.

Copyright 2023-2024 Elasticsearch https://www.elastic.co

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This repository includes dependencies/submodules whose licenses are listed in LICENSE.txt.

Documentation

Index

• Variables
• func BitFieldTypeMask[T interface{ ... }](mask T) string
• func NewFetchArg(argName string, argType string) *fetchArg
• type Probe
  • func NewKProbe() *Probe
  • func NewKRetProbe() *Probe
  • func (p *Probe) AddFetchArgs(args ...*fetchArg) *Probe
  • func (p *Probe) GetID() string
  • func (p *Probe) GetSymbolName() string
  • func (p *Probe) GetTracingEventFilter() string
  • func (p *Probe) GetTracingEventProbe() string
  • func (p *Probe) GetType() ProbeType
  • func (p *Probe) SetFilter(filter string) *Probe
  • func (p *Probe) SetRef(ref string) *Probe
• type ProbeType
• type Spec
  • func NewSpecFromKernel() (*Spec, error)
  • func NewSpecFromPath(path string, opts *SpecOptions) (*Spec, error)
  • func NewSpecFromReader(rd io.ReaderAt, opts *SpecOptions) (*Spec, error)
  • func (s *Spec) BuildSymbol(symbol *Symbol) error
  • func (s *Spec) ContainsSymbol(symbolName string) bool
  • func (s *Spec) StripAndSave(pathToSave string, symbolsToInclude ...*Symbol) error
• type SpecOptions
• type Symbol
  • func NewSymbol(symbolNames ...string) *Symbol
  • func NewSymbolWithoutValidation(symbolName string) *Symbol
  • func (s *Symbol) AddProbes(p ...*Probe) *Symbol
  • func (s *Symbol) GetProbes() []*Probe
  • func (s *Symbol) GetSymbolName() string
• type Wrap

Variables

var (
	// ErrSpecKernelNotSupported means that the running kernel does not support btf.
	ErrSpecKernelNotSupported = errors.New("running kernel does not support btf")
	// ErrSymbolNotFound means that the symbol (aka function name) was not found in the BTF spec.
	ErrSymbolNotFound = errors.New("symbol not found in btf spec")
	// ErrFuncParamNotFound means that the function parameter was not found in the btf func proto.
	ErrFuncParamNotFound = errors.New("function parameter not found")
	// ErrFieldNotFound means that a field is not part of the parent btf type members.
	ErrFieldNotFound = errors.New("field not found")
	// ErrUnsupportedFuncParamIndex means that the parameter index could not be mapped to any register.
	ErrUnsupportedFuncParamIndex = errors.New("unsupported func parameter index")
	// ErrUnsupportedArch means that the architecture is not supported.
	// Currently, arm64, and amd64 are supported.
	ErrUnsupportedArch = errors.New("unsupported architecture")
	// ErrIncompatibleFetchArg means that a fetch arg is assigned to probe type that is not compatible with,
	// e.g. FuncParamArbitrary is not compatible with ProbeTypeKRetProbe.
	ErrIncompatibleFetchArg = errors.New("incompatible fetch arg with probe type")
	// ErrMissingFieldBuilders means that the fetch args has not any field builders assigned.
	ErrMissingFieldBuilders = errors.New("missing field builders from fetch arg")
	// ErrMissingFields means that the fetch arg of a type that requires fields has not any fields assigned.
	ErrMissingFields = errors.New("missing fields")
	// ErrDuplicateFetchArgs means that two or more fetch args with the same name are specified.
	ErrDuplicateFetchArgs = errors.New("duplicate fetch args")
	// ErrMissingSymbolNames means that no symbol names are specified.
	ErrMissingSymbolNames = errors.New("missing symbol names")
	// ErrUnsupportedWrapType means that the wrap type is not supported.
	ErrUnsupportedWrapType = errors.New("unsupported wrap type")
	// ErrArrayIndexInvalidField means that the field specified as an array index is invalid.
	ErrArrayIndexInvalidField = errors.New("array index invalid field")
)

Functions

func BitFieldTypeMask

func BitFieldTypeMask[T interface {
	uint8 | uint16 | uint32 | uint64
}](mask T) string

BitFieldTypeMask generates the string representation of a bitfield fetchArg type based on the given mask value (https://docs.kernel.org/trace/kprobetrace.html#types). Specifically, it dynamically determines the leading zeros, ones count, and size of container based on the mask (supported types are uint8, uint16, uint32, or uint64) and performs the necessary calculations to build the respective string representation of a bitfield type. When this type is assigned to a fetchArg, it causes only the bits of the fetch arg value that fall withing the original mask to remain (ret := fetchArgValue & mask) and then be shifted all the way to the right (ret := ret >> maskTrailingZeros). The bitfield type has a format of "b{bitWidth}@{bitOffset}/{containerSize}".

Note: masks without consecutive ones (e.g. 0x5) are not supported and their behavior is undefined.

func NewFetchArg

func NewFetchArg(argName string, argType string) *fetchArg

NewFetchArg creates and returns a new fetchArg with the given name and type. Note that fetchArg requires fieldsBuilders to be attached to it which is done by the functions FuncParamWithName, FuncParamArbitrary, and FuncParamWithCustomType for KProbes. Respectively, for KRetProbes the fieldsBuilder functions are FuncReturn and FuncReturnArbitrary. When a fetch arg is built without any fieldsBuilder attached, ErrMissingFieldBuilders is returned. Also, that you can add multiple fieldsBuilders to the same fetchArg but the first one, in respect to the order they were added, that is built without an error will satisfy the fetchArg.

Types

type Probe

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

func NewKProbe

func NewKProbe() *Probe

NewKProbe creates and returns new Probe of type ProbeTypeKProbe.

func NewKRetProbe

func NewKRetProbe() *Probe

NewKRetProbe creates and returns new Probe of type ProbeTypeKRetProbe.

func (*Probe) AddFetchArgs

func (p *Probe) AddFetchArgs(args ...*fetchArg) *Probe

AddFetchArgs attaches the given fetchArgs to the Probe.

func (*Probe) GetID

func (p *Probe) GetID() string

GetID returns the ID of the Probe. The ID is the result of combining the probe type and the symbol name or the reference name if it is set.

func (*Probe) GetSymbolName

func (p *Probe) GetSymbolName() string

GetSymbolName returns the symbol name of the Probe.

func (*Probe) GetTracingEventFilter

func (p *Probe) GetTracingEventFilter() string

GetTracingEventFilter returns the tracing event filter of the Probe. It returns an empty string if no filter is set.

func (*Probe) GetTracingEventProbe

func (p *Probe) GetTracingEventProbe() string

GetTracingEventProbe returns the tracing event probe string for the Probe.

func (*Probe) GetType

func (p *Probe) GetType() ProbeType

GetType returns the ProbeType.

func (*Probe) SetFilter

func (p *Probe) SetFilter(filter string) *Probe

SetFilter sets a tracing event filter to the probe. It takes a filter string as input and returns a pointer to the probe. Note that this doesn't validate the supplied filter string and it up to the caller to check its validity.

func (*Probe) SetRef

func (p *Probe) SetRef(ref string) *Probe

SetRef sets the reference name of the probe. This is useful when multiple probes are attached to the same symbol and an extra factor of distinguishing them is required.

type ProbeType

type ProbeType uint32

ProbeType highlights the type of the Probe. (https://docs.kernel.org/trace/kprobetrace.html#synopsis-of-kprobe-events)

const (
	// ProbeTypeKProbe captures a KProbe.
	ProbeTypeKProbe ProbeType = iota
	// ProbeTypeKRetProbe captures a KRetProbe.
	ProbeTypeKRetProbe
)

type Spec

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

Spec holds the btfSpec and the registersResolver.

func NewSpecFromKernel

func NewSpecFromKernel() (*Spec, error)

NewSpecFromKernel generates a new Spec from the kernel.

func NewSpecFromPath

func NewSpecFromPath(path string, opts *SpecOptions) (*Spec, error)

NewSpecFromPath generates a new Spec from the given file path.

func NewSpecFromReader

func NewSpecFromReader(rd io.ReaderAt, opts *SpecOptions) (*Spec, error)

NewSpecFromReader generates a new Spec from the given io.ReaderAt.

func (*Spec) BuildSymbol

func (s *Spec) BuildSymbol(symbol *Symbol) error

BuildSymbol builds the given symbol against the btf spec.

func (*Spec) ContainsSymbol

func (s *Spec) ContainsSymbol(symbolName string) bool

ContainsSymbol returns true if the btf spec contains the given symbol name

func (*Spec) StripAndSave

func (s *Spec) StripAndSave(pathToSave string, symbolsToInclude ...*Symbol) error

StripAndSave first extracts from all Symbols the associated btf types and respective members that are used to successfully construct the probes. Then based on the former it clears any unused btf types and members from the btf spec. Finally, it saves the btf spec with wire format to the given path.

type SpecOptions

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

type Symbol

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

Symbol represents a function symbol and holds the list of probes associated with it.

func NewSymbol

func NewSymbol(symbolNames ...string) *Symbol

NewSymbol creates and returns a new Symbol instance with the given symbol names.

func NewSymbolWithoutValidation

func NewSymbolWithoutValidation(symbolName string) *Symbol

NewSymbolWithoutValidation creates and returns a new Symbol instance which during build won't try to extract the function prototype from the btf spec. This is useful in case the function prototype is not available in the btf spec.

func (*Symbol) AddProbes

func (s *Symbol) AddProbes(p ...*Probe) *Symbol

AddProbes attaches the given probes to the Symbol.

func (*Symbol) GetProbes

func (s *Symbol) GetProbes() []*Probe

GetProbes returns the list of probes attached to the Symbol.

func (*Symbol) GetSymbolName

func (s *Symbol) GetSymbolName() string

GetSymbolName returns the name of the resolved symbol. If the Symbol is set not to validate the symbol it returns the first symbol name of the provided ones during Symbol instantiation.

Note if you call GetSymbolName on a Symbol that has not been built, it will return an empty string.

type Wrap

type Wrap uint32

Wrap indicates if and how the first field should be wrapped in fieldsBuilder that process the fields without relying on the existence of the function prototype in the BTF spec, namely FuncParamWithCustomType, FuncParamArbitrary and FuncReturnArbitrary.

const (
	// WrapNone there is no wrapping to the type.
	WrapNone Wrap = iota
	// WrapPointer the type will be wrapped under a pointer that targets to it.
	WrapPointer
	// WrapStructPointer the type will be wrapped as a member of an arbitrary struct at offset zero which is wrapped
	// under a pointer.
	WrapStructPointer
)