gadgets

Documentation

Index

• Constants
• func CloseLink(l link.Link) link.Link
• func DetectBpfKtimeGetBootNs() bool
• func FixBpfKtimeGetBootNs(programSpecs map[string]*ebpf.ProgramSpec)
• func FromCString(in []byte) string
• func FromCStringN(in []byte, length int) string
• func GadgetParams(gadget GadgetDesc, parser parser.Parser) params.ParamDescs
• func GetCategories() map[string]string
• func Htonl(hl uint32) uint32
• func Htons(hs uint16) uint16
• func IPStringFromBytes(ipBytes [16]byte, ipType int) string
• func IntervalParams() params.ParamDescs
• func SortableParams(gadget GadgetDesc, parser parser.Parser) params.ParamDescs
• func WallTimeFromBootTime(ts uint64) types.Time
• type CloseGadget
• type DataEnricherByMntNs
• type DataEnricherByNetNs
• type DataNodeEnricher
• type DefaultSort
• type EventEnricherSetter
• type EventHandlerArraySetter
• type EventHandlerSetter
• type Gadget
• type GadgetContext
• type GadgetDesc
• type GadgetInstantiate
• type GadgetOutputFormats
• type GadgetResult
• type GadgetType
  • func (t GadgetType) CanSort() bool
  • func (t GadgetType) IsPeriodic() bool
• type OutputFormat
• type OutputFormats
  • func (of OutputFormats) Append(other OutputFormats)
• type RunGadget
• type StartStopAltGadget
• type StartStopGadget

Constants

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

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

	// The Trace custom resource is preferably in the "gadget" namespace
	TraceDefaultNamespace = "gadget"

	PerfBufferPages = 64

	// bpf_ktime_get_boot_ns()'s func id as defined in Linux API
	// https://github.com/torvalds/linux/blob/v6.2-rc1/include/uapi/linux/bpf.h#L5614
	BpfKtimeGetBootNsFuncID = 125
)

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

Functions

func CloseLink

func CloseLink(l link.Link) link.Link

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

func DetectBpfKtimeGetBootNs

func DetectBpfKtimeGetBootNs() bool

DetectBpfKtimeGetBootNs returns true if bpf_ktime_get_boot_ns is available in the current kernel. False negatives are possible if BTF is not available.

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, parser parser.Parser) params.ParamDescs

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

func GetCategories

func GetCategories() map[string]string

GetCategories returns a map of category name to category description

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 IntervalParams

func IntervalParams() params.ParamDescs

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 CloseGadget

type CloseGadget interface {
	Close()
}

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 interface {
	Init(GadgetContext) error
}

type GadgetContext

type GadgetContext interface {
	ID() string
	Context() context.Context
	GadgetParams() *params.Params
	Logger() logger.Logger
}

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

type GadgetResult interface {
	Result() ([]byte, error)
}

type GadgetType

type GadgetType string

GadgetType defines how a gadget is actually run

const (
	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
)

func (GadgetType) CanSort

func (t GadgetType) CanSort() bool

func (GadgetType) IsPeriodic

func (t GadgetType) IsPeriodic() bool

type OutputFormat

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

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() error
}

RunGadget is an alternative to StartStopGadget that expects the result to be emitted using the EventHandler as well but doesn't need to be stopped (manually)

type StartStopAltGadget

type StartStopAltGadget interface {
	StartAlt() error
	StopAlt()
}

StartStopAltGadget is an alternative interface to StartStop, as some gadgets already have the Start() and Stop() functions defined, but with a different signature After we've migrated to the interfaces, the gadgets should be altered to use the Start/Stop signatures of the above StartStopGadget interface.

type StartStopGadget

type StartStopGadget interface {
	Start() error
	Stop()
}