instrumentation

Documentation

Index

• type Config
• type ConfigGroup
• type ConfigGroupResolver
• type ConfigUpdate
• type DistributionMatcher
• type Factory
• type Handler
• type Instrumentation
• type Manager
  • func NewManager[processDetails ProcessDetails, configGroup ConfigGroup](options ManagerOptions[processDetails, configGroup]) (Manager, error)
• type ManagerOptions
• type OtelDistribution
• type ProcessDetails
• type ProcessDetailsResolver
• type Reporter
• type Settings
• type SettingsGetter

Types

type Config

type Config any

type ConfigGroup

type ConfigGroup interface {
	comparable
}

ConfigGroup is used to represent a group of instrumented processes which can be configured together. For example, a Kubernetes deployment with multiple replicas can be considered a ConfigGroup. A config group may include multiple process groups, but there is no assumption on a connection between them.

type ConfigGroupResolver

type ConfigGroupResolver[processDetails ProcessDetails, configGroup ConfigGroup] interface {
	// Resolve will classify the process into a configuration group.
	// The Otel Distribution is resolved in the time of calling this function, and may be used
	// to determine the configuration group.
	Resolve(context.Context, processDetails, OtelDistribution) (configGroup, error)
}

ConfigGroupResolver is used to resolve the configuration group of a process.

type ConfigUpdate

type ConfigUpdate[configGroup ConfigGroup] map[configGroup]Config

ConfigUpdate is used to send a configuration update request to the manager. The manager will apply the configuration to all instrumentations that match the config group.

type DistributionMatcher

type DistributionMatcher[processDetails ProcessDetails] interface {
	// Distribution will match a process to an Otel Distribution.
	Distribution(context.Context, processDetails) (OtelDistribution, error)
}

DistributionMatcher is used to match a process to an Otel Distribution.

type Factory

type Factory interface {
	// CreateInstrumentation will initialize the instrumentation for the given process.
	// Setting can be used to pass initial configuration to the instrumentation.
	CreateInstrumentation(ctx context.Context, pid int, settings Settings) (Instrumentation, error)
}

Factory is used to create an Instrumentation

type Handler

type Handler[processDetails ProcessDetails, configGroup comparable] struct {
	ProcessDetailsResolver ProcessDetailsResolver[processDetails]
	ConfigGroupResolver    ConfigGroupResolver[processDetails, configGroup]
	Reporter               Reporter[processDetails]
	DistributionMatcher    DistributionMatcher[processDetails]
	SettingsGetter         SettingsGetter[processDetails]
}

Handler is used to classify, report and configure instrumentations.

type Instrumentation

type Instrumentation interface {
	// Loads the relevant probes, and will perform any initialization required
	// for the instrumentation to be ready to run.
	// For eBPF, this will load the probes into the kernel
	// In case of a failure, an error will be returned and all the resources will be cleaned up.
	Load(ctx context.Context) error

	// Run will start reading events from the probes and export them.
	// It is a blocking call, and will return only when the instrumentation is stopped.
	// During the run, telemetry will be collected from the probes and sent with the configured exporter.
	// Run will return when either a fatal error occurs, the context is canceled, or Close is called.
	Run(ctx context.Context) error

	// Close will stop the instrumentation (Stop the Run function) and clean up all the resources associated with it.
	// When it returns, the instrumentation is stopped and all resources are cleaned up.
	Close(ctx context.Context) error

	// ApplyConfig will send a configuration update to the instrumentation.
	ApplyConfig(ctx context.Context, config Config) error
}

Instrumentation is used to instrument a running process

type Manager

type Manager interface {
	// Run launches the manger.
	// It will block until the context is canceled.
	// It is an error to not cancel the context before the program exits, and may result in leaked resources.
	Run(ctx context.Context) error
}

Manager is used to orchestrate the ebpf instrumentations lifecycle.

func NewManager

func NewManager[processDetails ProcessDetails, configGroup ConfigGroup](options ManagerOptions[processDetails, configGroup]) (Manager, error)

type ManagerOptions

type ManagerOptions[processDetails ProcessDetails, configGroup ConfigGroup] struct {
	Logger logr.Logger

	// Factories is a map of OTel distributions to their corresponding instrumentation factories.
	//
	// The manager will use this map to create new instrumentations based on the process event.
	// If a process event is received and the OTel distribution is not found in this map,
	// the manager will ignore the event.
	Factories map[OtelDistribution]Factory

	// Handler is used to resolve details, config group, OTel distribution and settings for the instrumentation
	// based on the process event.
	//
	// The handler is also used to report the instrumentation lifecycle events.
	Handler *Handler[processDetails, configGroup]

	// DetectorOptions is a list of options to configure the process detector.
	//
	// The process detector is used to trigger new instrumentation for new relevant processes,
	// and un-instrumenting processes once they exit.
	DetectorOptions []detector.DetectorOption

	// ConfigUpdates is a channel for receiving configuration updates.
	// The manager will apply the configuration to all instrumentations that match the config group.
	//
	// The caller is responsible for closing the channel once no more updates are expected.
	ConfigUpdates <-chan ConfigUpdate[configGroup]
}

type OtelDistribution

type OtelDistribution struct {
	Language common.ProgrammingLanguage
	OtelSdk  common.OtelSdk
}

OtelDistribution is a customized version of an OpenTelemetry component. see https://opentelemetry.io/docs/concepts/distributions and https://github.com/odigos-io/odigos/pull/1776#discussion_r1853367917 for more information. TODO: This should be moved to a common root package, since it will require a bigger refactor across multiple components, we use this local definition for now.

type ProcessDetails

type ProcessDetails interface {
	fmt.Stringer
}

ProcessDetails is used to convert the common process details reported by the detector to details relevant to hosting platform.

ProcessDetails can contain details that associates a process to a group of processes that are managed together by the hosting platform. It may include different information depending on the platform (Kubernetes, VM, etc).

For example consider an app which is launched by a bash script, the script launches a python process. The process may create different child processes, and the bash script may launch multiple python processes. In this case, the process group may include the bash script, the python process, and the child processes.

Another category of information that may be included relates to language and runtime information which can be used to determine the OTel distribution to use.

type ProcessDetailsResolver

type ProcessDetailsResolver[processDetails ProcessDetails] interface {
	// Resolve will classify the process into a process group.
	// Those process group details may be used for future calls when reporting the status of the instrumentation.
	// or for resolving the configuration group of the process.
	Resolve(context.Context, detector.ProcessEvent) (processDetails, error)
}

ProcessDetailsResolver is used to resolve the process group of a process.

type Reporter

type Reporter[processDetails ProcessDetails] interface {
	// OnInit is called when the instrumentation is initialized.
	// The error parameter will be nil if the instrumentation was initialized successfully.
	OnInit(ctx context.Context, pid int, err error, pg processDetails) error

	// OnLoad is called after an instrumentation is loaded successfully or failed to load.
	// The error parameter will be nil if the instrumentation was loaded successfully.
	OnLoad(ctx context.Context, pid int, err error, pg processDetails) error

	// OnRun is called after the instrumentation stops running.
	// An error may report a fatal error during the instrumentation run, or a closing error
	// which happened during the closing of the instrumentation.
	OnRun(ctx context.Context, pid int, err error, pg processDetails) error

	// OnExit is called when the instrumented process exits, and the instrumentation has already been stopped.
	// For a reported which persists the instrumentation state, this is the time to clean up the state.
	OnExit(ctx context.Context, pid int, pg processDetails) error
}

Reporter is used to report the status of the instrumentation. It is called at different stages of the instrumentation lifecycle.

type Settings

type Settings struct {
	// ServiceName is the name of the service that is being instrumented
	// It will be used to populate the service.name resource attribute.
	ServiceName string
	// ResourceAttributes can be used to pass additional resource attributes to the instrumentation
	// These attributes will be added to the resource attributes of the telemetry data.
	ResourceAttributes []attribute.KeyValue
	// InitialConfig is the initial configuration that should be applied to the instrumentation,
	// it can be used to enable/disable specific instrumentation libraries, configure sampling, etc.
	InitialConfig Config
}

Settings is used to pass initial configuration to the instrumentation

type SettingsGetter

type SettingsGetter[processDetails ProcessDetails] interface {
	// GetSettings will fetch the initial settings of an instrumentation.
	Settings(context.Context, processDetails, OtelDistribution) (Settings, error)
}

SettingsGetter is used to fetch the initial settings of an instrumentation.