gadgets

Documentation

Index

• Constants
• func CloseLink(l link.Link) link.Link
• func FixBpfKtimeGetBootNs(programSpecs map[string]*ebpf.ProgramSpec)
• func FromCString(in []byte) string
• func FromCStringN(in []byte, length int) string
• func GadgetParams(gadget GadgetDesc, gType GadgetType, parser parser.Parser) params.ParamDescs
• func GetCategories() map[string]string
• func HasBpfKtimeGetBootNs() bool
• func Htonl(hl uint32) uint32
• func Htons(hs uint16) uint16
• func IPStringFromBytes(ipBytes [16]byte, ipType int) string
• func IPStringToByteArray(ipAddr string) ([16]byte, error)
• func IPStringToUint32(ipAddr string) (uint32, error)
• func IPVerFromAF(af uint16) int
• func IntervalParams() params.ParamDescs
• func LoadeBPFSpec(mountnsMap *ebpf.Map, spec *ebpf.CollectionSpec, consts map[string]interface{}, ...) error
• func ParamsFromMap(paramMap map[string]string, gadgetParams *params.Params, ...) error
• func ParamsToMap(paramMap map[string]string, gadgetParams *params.Params, ...)
• func ProtoString(proto int) string
• func SortableParams(gadget GadgetDesc, parser parser.Parser) params.ParamDescs
• func WallTimeFromBootTime(ts uint64) types.Time
• type DataEnricherByMntNs
• type DataEnricherByNetNs
• type DataNodeEnricher
• type DefaultSort
• type EventEnricherSetter
• type EventHandlerArraySetter
• type EventHandlerSetter
• type Gadget
• type GadgetContext
• type GadgetDesc
• type GadgetDescSkipParams
• type GadgetExperimental
• type GadgetInstantiate
• type GadgetOutputFormats
• type GadgetType
  • func (t GadgetType) CanSort() bool
  • func (t GadgetType) IsPeriodic() bool
• type InitCloseGadget
• type OutputFormat
• type OutputFormats
  • func (of OutputFormats) Append(other OutputFormats)
• type RunGadget
• type RunWithResultGadget

Constants

const (
	CategoryNone     = ""
	CategoryAdvise   = "advise"
	CategoryAudit    = "audit"
	CategoryProfile  = "profile"
	CategorySnapshot = "snapshot"
	CategoryTop      = "top"
	CategoryTrace    = "trace"
	CategoryOther    = "other"
)

const (
	PinPath = "/sys/fs/bpf/gadget"

	PerfBufferPages = 64

	// Constant used to enable filtering by mount namespace inode id in eBPF.
	// Keep in syn with variable defined in pkg/gadgets/common/mntns_filter.h.
	FilterByMntNsName = "gadget_filter_by_mntns"

	// Name of the map that stores the mount namespace inode id to filter on.
	// Keep in syn with name used in pkg/gadgets/common/mntns_filter.h.
	MntNsFilterMapName = "gadget_mntns_filter_map"
)

const (
	ParamInterval = "interval"
	ParamSortBy   = "sort"
	ParamMaxRows  = "max-rows"
)

const (
	LocalContainer   params.ValueHint = "local:container"
	K8SNodeName      params.ValueHint = "k8s:node"
	K8SNodeList      params.ValueHint = "k8s:node-list"
	K8SPodName       params.ValueHint = "k8s:pod"
	K8SNamespace     params.ValueHint = "k8s:namespace"
	K8SContainerName params.ValueHint = "k8s:container"
	K8SLabels        params.ValueHint = "k8s:labels"
)

Functions

func CloseLink

func CloseLink(l link.Link) link.Link

CloseLink closes l if it's not nil and returns nil

func FixBpfKtimeGetBootNs

func FixBpfKtimeGetBootNs(programSpecs map[string]*ebpf.ProgramSpec)

FixBpfKtimeGetBootNs checks if bpf_ktime_get_boot_ns is supported by the kernel and removes it if not

func FromCString

func FromCString(in []byte) string

func FromCStringN

func FromCStringN(in []byte, length int) string

func GadgetParams

func GadgetParams(gadget GadgetDesc, gType GadgetType, parser parser.Parser) params.ParamDescs

GadgetParams returns params specific to the gadgets' type - for example, it returns parameters for 'sort' and 'max-rows' for gadgets with sortable results, and 'interval' for periodically called gadgets

func GetCategories

func GetCategories() map[string]string

GetCategories returns a map of category name to category description

func HasBpfKtimeGetBootNs

func HasBpfKtimeGetBootNs() bool

HasBpfKtimeGetBootNs returns true if bpf_ktime_get_boot_ns is available

func Htonl

func Htonl(hl uint32) uint32

func Htons

func Htons(hs uint16) uint16

func IPStringFromBytes

func IPStringFromBytes(ipBytes [16]byte, ipType int) string

func IPStringToByteArray

func IPStringToByteArray(ipAddr string) ([16]byte, error)

IPStringToByteArray converts an IP address (IPv6 only) string to a uint32 in big-endian.

func IPStringToUint32

func IPStringToUint32(ipAddr string) (uint32, error)

IPStringToUint32 converts an IP address (IPv4 only) string to a uint32 in big-endian.

func IPVerFromAF

func IPVerFromAF(af uint16) int

func IntervalParams

func IntervalParams() params.ParamDescs

func LoadeBPFSpec

func LoadeBPFSpec(
	mountnsMap *ebpf.Map,
	spec *ebpf.CollectionSpec,
	consts map[string]interface{},
	objs interface{},
) error

LoadeBPFSpec is a helper to load an eBPF spec from gadgets. It replaces filter map and calls the necessary functions to load Maps and Programs into the kernel

func ParamsFromMap

func ParamsFromMap(
	paramMap map[string]string,
	gadgetParams *params.Params,
	runtimeParams *params.Params,
	operatorParams params.Collection,
) error

ParamsFromMap fills the given params (gadget, runtime and operator) using values from `paramMap`. It looks up values using prefixes (see also `ParamsToMap`) and applies verification. If verification for a field fails, an error will be returned.

func ParamsToMap

func ParamsToMap(
	paramMap map[string]string,
	gadgetParams *params.Params,
	runtimeParams *params.Params,
	operatorParams params.Collection,
)

ParamsToMap adds the given params (gadget, runtime and operator) to the paramMap. It uses prefixes to ensure the keys remain unique.

func ProtoString

func ProtoString(proto int) string

func SortableParams

func SortableParams(gadget GadgetDesc, parser parser.Parser) params.ParamDescs

func WallTimeFromBootTime

func WallTimeFromBootTime(ts uint64) types.Time

WallTimeFromBootTime converts a time from bpf_ktime_get_boot_ns() to the wall time with nano precision.

Example:

fmt.Printf("Time: %s\n", WallTimeFromBootTime(ts).String())

would display:

Time: 2022-12-15T16:49:00.452371948+01:00

Shell command to convert the number to a date:

$ date -d @$(echo 1671447636499110634/1000000000|bc -l) +"%d-%m-%Y %H:%M:%S:%N"
19-12-2022 12:00:36:499110634

bpf_ktime_get_boot_ns was added in Linux 5.7. If not available and the BPF program returns 0, just get the timestamp in userspace.

Types

type DataEnricherByMntNs

type DataEnricherByMntNs interface {
	EnrichByMntNs(event *types.CommonData, mountnsid uint64)
}

DataEnricherByMntNs is used to enrich events with Kubernetes information, like node, namespace, pod name and container name when the mount namespace is available.

type DataEnricherByNetNs

type DataEnricherByNetNs interface {
	EnrichByNetNs(event *types.CommonData, netnsid uint64)
}

DataEnricherByNetNs is used to enrich events with Kubernetes information, like node, namespace, pod name and container name when the network namespace is available.

type DataNodeEnricher

type DataNodeEnricher interface {
	EnrichNode(event *types.CommonData)
}

DataNodeEnricher is used to enrich events with Kubernetes node, without needing any namespace.

type DefaultSort

type DefaultSort interface {
	SortByDefault() []string
}

DefaultSort can be implemented in addition to the Gadget interface, to specify the default sorting columns

type EventEnricherSetter

type EventEnricherSetter interface {
	SetEventEnricher(func(ev any) error)
}

type EventHandlerArraySetter

type EventHandlerArraySetter interface {
	SetEventHandlerArray(handler any)
}

type EventHandlerSetter

type EventHandlerSetter interface {
	SetEventHandler(handler any)
}

type Gadget

type Gadget any

type GadgetContext

type GadgetContext interface {
	ID() string
	Context() context.Context
	GadgetParams() *params.Params
	RuntimeParams() *params.Params
	Args() []string
	Logger() logger.Logger
	Timeout() time.Duration
}

type GadgetDesc

type GadgetDesc interface {
	// Name provides the name of the gadget. This is used for the calling the gadget, auto-creating the cobra commands,
	// logging, etc.
	Name() string

	// Description provides a short description of the gadget. This is used for a quick help in cobra, help,
	// web-interface etc.
	Description() string

	// Category is used for cobra sub-commands and categories on the web interface.
	Category() string

	// Type is used to differentiate between how gadgets are run. The type essentially controls the workflow of the
	// gadget.
	Type() GadgetType

	// ParamDescs returns a map of configuration parameters. These hold also default values, descriptions, validators and
	// so on. Used whenever a gadget is called somehow. Auto-creates parameters for cobra as well.
	ParamDescs() params.ParamDescs

	// Parser returns a parser.Parser instance that can handle events and do certain operations on them
	// (sorting, filtering, etc.) without the caller needing to know about the underlying types.
	Parser() parser.Parser

	// EventPrototype returns a blank event. Useful for checking for interfaces on it (see operators).
	EventPrototype() any
}

GadgetDesc is the main interface for handling gadgets

type GadgetDescSkipParams

type GadgetDescSkipParams interface {
	SkipParams() []params.ValueHint
}

GadgetDescSkipParams / SkipParams() can define params that a gadget, runtime or operators never can use in combination with this gadget. Currently, this is used to not allow to specify for example a container name when the gadget is working inside the kubernetes environment and using the netns (as results could be ambiguous in that case).

type GadgetExperimental

type GadgetExperimental interface {
	Experimental() bool
}

GadgetExperimental allows to mark a gadget as experimental.

type GadgetInstantiate

type GadgetInstantiate interface {
	GadgetDesc

	// NewInstance creates a new gadget and returns it; the tracer should be allocated and configured but
	// should not run any code that depends on cleanup
	NewInstance() (Gadget, error)
}

GadgetInstantiate is the same interface as Gadget but adds one call to instantiate an actual tracer

type GadgetOutputFormats

type GadgetOutputFormats interface {
	OutputFormats() (supportedFormats OutputFormats, defaultFormatKey string)
}

GadgetOutputFormats can be implemented together with the gadget interface to register alternative output formats that are used in combination with the GadgetResult interface. The defaultFormatKey MUST match the key of an entry in the supportedFormats map

type GadgetType

type GadgetType string

GadgetType defines how a gadget is actually run

const (
	TypeUnknown        GadgetType = ""
	TypeTrace          GadgetType = "trace"          // Normal trace gadgets
	TypeTraceIntervals GadgetType = "traceIntervals" // top gadgets expecting arrays of events
	TypeOneShot        GadgetType = "oneShot"        // Gadgets that only fetch results
	TypeProfile        GadgetType = "profile"        // Gadgets that run until the user stops, or it times out and then shows results
	TypeRun            GadgetType = "run"            // This is a special type only used by the run command
	TypeOther          GadgetType = "other"
)

func (GadgetType) CanSort

func (t GadgetType) CanSort() bool

func (GadgetType) IsPeriodic

func (t GadgetType) IsPeriodic() bool

type InitCloseGadget

type InitCloseGadget interface {
	// Init is expected to initialize the gadget. It will be called right before
	// the operators are installed, and also before Run() is called (which is
	// done after the operators are installed, see the Gadget interface).
	Init(GadgetContext) error

	// Close is expected to clean up all the resources allocated by the gadget.
	// It will be called after Run() returns and after the operators have been
	// uninstalled.
	// TODO: We should pass the gadget context to Close().
	Close()
}

InitCloseGadget is an optional interface that can be implemented by gadgets that needs to be initialized before the operators are installed. An example of this is when the gadget needs to be kept up-to-date with the containers that need to be traced, as the operators will start sending notifications of this as soon as it is installed. So, the gadget needs to be initialized and ready to receive those notifications before the operators are installed.

type OutputFormat

type OutputFormat struct {
	Name                   string                    `json:"name"`
	Description            string                    `json:"description"`
	RequiresCombinedResult bool                      `json:"requiresCombinedResult"`
	Transform              func(any) ([]byte, error) `json:"-"`
}

OutputFormat can hold alternative output formats for a gadget. Whenever such a format is used, the result of the gadget will be passed to the Transform() function and returned to the user.

type OutputFormats

type OutputFormats map[string]OutputFormat

func (OutputFormats) Append

func (of OutputFormats) Append(other OutputFormats)

Append appends the OutputFormats given in other to of

type RunGadget

type RunGadget interface {
	// Run is expected to run the gadget and emits the events using the
	// EventHandler. This function is expected to be blocking and return only
	// when the context is done, after which the gadget should clean up all
	// resources. Notice that this function will be called after operators are
	// installed.
	Run(GadgetContext) error
}

RunGadget is an interface that will be implemented by gadgets that are run in the background and emit events as soon as they occur.

type RunWithResultGadget

type RunWithResultGadget interface {
	// RunWithResult follows the same rules as Run() but instead of using an
	// EventHandler to emit the events, it returns the result of the gadget as a
	// byte array after the context is done.
	RunWithResult(GadgetContext) ([]byte, error)
}

RunWithResultGadget is an alternative to RunGadget that returns the result of the gadget only at the end of its execution.