gadgets

package
v0.27.1-0...-cdee6b7 Latest Latest
Warning

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

 Go to latest Published: Apr 12, 2024 License: Apache-2.0 Imports: 19 Imported by: 3

README

Built-in Gadgets

This folder contains the code for the built-in gadgets. We're converting these gadgets to be image-based, once the conversion is completed, these will be deprecated and removed.

Documentation

Index

Constants

View Source 
const (
	CategoryNone     = ""
	CategoryAdvise   = "advise"
	CategoryAudit    = "audit"
	CategoryProfile  = "profile"
	CategorySnapshot = "snapshot"
	CategoryTop      = "top"
	CategoryTrace    = "trace"
	CategoryOther    = "other"
)
View Source 
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"
)
View Source 
const (
	ParamInterval = "interval"
	ParamSortBy   = "sort"
	ParamMaxRows  = "max-rows"
)
View Source 
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"
)

Variables

This section is empty.

Functions 

func CloseLink(l link.Link) link.Link

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

func FixBpfKtimeGetBootNs added in v0.13.0 

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 added in v0.11.0 

func FromCString(in []byte) string

func FromCStringN added in v0.11.0 

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

func GadgetParams added in v0.14.0 

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 added in v0.14.0 

func GetCategories() map[string]string

GetCategories returns a map of category name to category description

func HasBpfKtimeGetBootNs added in v0.25.0 

func HasBpfKtimeGetBootNs() bool

HasBpfKtimeGetBootNs returns true if bpf_ktime_get_boot_ns is available

func Htonl added in v0.11.0 

func Htonl(hl uint32) uint32

func Htons added in v0.11.0 

func Htons(hs uint16) uint16

func IPStringFromBytes added in v0.11.0 

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

func IPStringToByteArray added in v0.18.0 

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

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

func IPStringToUint32 added in v0.17.0 

func IPStringToUint32(ipAddr string) (uint32, error)

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

func IPVerFromAF added in v0.16.0 

func IPVerFromAF(af uint16) int

func IntervalParams added in v0.14.0 

func IntervalParams() params.ParamDescs

func LoadeBPFSpec added in v0.16.1 

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.20.0 

func ProtoString(proto int) string

func SortableParams added in v0.14.0 

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

func WallTimeFromBootTime added in v0.13.0 

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 added in v0.13.0 

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 added in v0.13.0 

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 added in v0.13.0 

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

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

type DefaultSort added in v0.14.0 

type DefaultSort interface {
	SortByDefault() []string
}

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

type EventEnricherSetter added in v0.14.0 

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

type EventHandlerArraySetter added in v0.14.0 

type EventHandlerArraySetter interface {
	SetEventHandlerArray(handler any)
}

type EventHandlerSetter added in v0.14.0 

type EventHandlerSetter interface {
	SetEventHandler(handler any)
}

type Gadget added in v0.14.0 

type Gadget any

type GadgetContext added in v0.14.0 

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

type GadgetDesc added in v0.14.0 

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 added in v0.15.0 

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 added in v0.23.0 

type GadgetExperimental interface {
	Experimental() bool
}

GadgetExperimental allows to mark a gadget as experimental.

type GadgetInstantiate added in v0.14.0 

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 added in v0.14.0 

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 added in v0.14.0 

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 added in v0.14.0 

func (t GadgetType) CanSort() bool

func (GadgetType) IsPeriodic added in v0.14.0 

func (t GadgetType) IsPeriodic() bool

type InitCloseGadget added in v0.15.0 

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 added in v0.14.0 

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 added in v0.14.0 

type OutputFormats map[string]OutputFormat

func (OutputFormats) Append added in v0.14.0 

func (of OutputFormats) Append(other OutputFormats)

Append appends the OutputFormats given in other to of

type RunGadget added in v0.14.0 

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 added in v0.15.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
advise
networkpolicy/advisor
seccomp/tracer
audit
seccomp/tracer
seccomp/types
profile
block-io/tracer
block-io/types
cpu/tracer
cpu/types
tcprtt/tracer
tcprtt/types
prometheus
tracer
run
types
types
snapshot
process/tracer
process/types
socket/tracer
socket/types
top
block-io/tracer
block-io/types
ebpf/piditer
ebpf/tracer
ebpf/types
file/tracer
file/types
tcp/tracer
tcp/types
trace
bind/tracer
bind/types
capabilities/tracer
capabilities/types
dns/tracer
dns/types
exec/tracer
exec/types
fsslower/tracer
fsslower/types
mount/tracer
mount/types
network/tracer
network/types
oomkill/tracer
oomkill/types
open/tracer
open/types
signal/tracer
signal/types
sni/tracer
sni/types
tcp/tracer
tcp/types
tcpconnect/tracer
tcpconnect/types
tcpdrop/tracer
tcpdrop/tracer/dropreasongen
tcpdrop/types
tcpretrans/tracer
tcpretrans/types
traceloop
labels
tracer
types

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.