beyla

Documentation

Index

• Constants
• Variables
• func CheckOSCapabilities(config *Config) error
• func CheckOSSupport() error
• func KernelVersion() (major, minor int)
• type Attributes
• type Config
  • func LoadConfig(file io.Reader) (*Config, error)
  • func (c *Config) Enabled(feature Feature) bool
  • func (c *Config) ExternalLogger(handler slog.Handler, tracing bool)
  • func (c *Config) Validate() error
• type ConfigError
  • func (e ConfigError) Error() string
• type Consumer
• type Feature
• type HostIDConfig
• type NetworkConfig
• type TracesReceiverConfig
  • func (t TracesReceiverConfig) Enabled() bool

Constants

const (
	FeatureAppO11y = Feature(1 << iota)
	FeatureNetO11y
)

const (
	EbpfSourceTC   = "tc"
	EbpfSourceSock = "socket_filter"
)

const ReporterLRUSize = 256

Variables

var DefaultConfig = Config{
	ChannelBufferLen: 10,
	LogLevel:         "INFO",
	EnforceSysCaps:   false,
	EBPF: config.EPPFTracer{
		BatchLength:        100,
		BatchTimeout:       time.Second,
		HTTPRequestTimeout: 30 * time.Second,
	},
	Grafana: otel.GrafanaConfig{
		OTLP: otel.GrafanaOTLP{

			Submit: []string{"traces"},
		},
	},
	NameResolver: &transform.NameResolverConfig{
		Sources:  []string{"k8s"},
		CacheLen: 1024,
		CacheTTL: 5 * time.Minute,
	},
	Metrics: otel.MetricsConfig{
		Protocol:             otel.ProtocolUnset,
		MetricsProtocol:      otel.ProtocolUnset,
		Interval:             5 * time.Second,
		Buckets:              otel.DefaultBuckets,
		ReportersCacheLen:    ReporterLRUSize,
		HistogramAggregation: otel.AggregationExplicit,
		Features:             []string{otel.FeatureApplication},
		Instrumentations: []string{
			instrumentations.InstrumentationALL,
		},

		TTL: defaultMetricsTTL,
	},
	Traces: otel.TracesConfig{
		Protocol:           otel.ProtocolUnset,
		TracesProtocol:     otel.ProtocolUnset,
		MaxQueueSize:       4096,
		MaxExportBatchSize: 4096,
		ReportersCacheLen:  ReporterLRUSize,
		Instrumentations: []string{
			instrumentations.InstrumentationALL,
		},
	},
	Prometheus: prom.PrometheusConfig{
		Path:     "/metrics",
		Buckets:  otel.DefaultBuckets,
		Features: []string{otel.FeatureApplication},
		Instrumentations: []string{
			instrumentations.InstrumentationALL,
		},
		TTL:                         defaultMetricsTTL,
		SpanMetricsServiceCacheSize: 10000,
	},
	Printer:      false,
	TracePrinter: debug.TracePrinterDisabled,
	InternalMetrics: imetrics.Config{
		Prometheus: imetrics.PrometheusConfig{
			Port: 0,
			Path: "/internal/metrics",
		},
	},
	Attributes: Attributes{
		InstanceID: traces.InstanceIDConfig{
			HostnameDNSResolution: true,
		},
		Kubernetes: transform.KubernetesDecorator{
			Enable:                kubeflags.EnabledDefault,
			InformersSyncTimeout:  30 * time.Second,
			InformersResyncPeriod: 30 * time.Minute,
		},
		HostID: HostIDConfig{
			FetchTimeout: 500 * time.Millisecond,
		},
	},
	Routes:       &transform.RoutesConfig{Unmatch: transform.UnmatchDefault},
	NetworkFlows: defaultNetworkConfig,
	Processes: process.CollectConfig{
		RunMode:  process.RunModePrivileged,
		Interval: 5 * time.Second,
	},
	Discovery: services.DiscoveryConfig{
		ExcludeOTelInstrumentedServices: true,
	},
}

Functions

func CheckOSCapabilities

func CheckOSCapabilities(config *Config) error

func CheckOSSupport

func CheckOSSupport() error

CheckOSSupport returns an error if the running operating system does not support the minimum required Beyla features.

func KernelVersion

func KernelVersion() (major, minor int)

Types

type Attributes

type Attributes struct {
	Kubernetes transform.KubernetesDecorator `yaml:"kubernetes"`
	InstanceID traces.InstanceIDConfig       `yaml:"instance_id"`
	Select     attributes.Selection          `yaml:"select"`
	HostID     HostIDConfig                  `yaml:"host_id"`
}

Attributes configures the decoration of some extra attributes that will be added to each span

type Config

type Config struct {
	EBPF config.EPPFTracer `yaml:"ebpf"`

	// NetworkFlows configuration for Network Observability feature
	NetworkFlows NetworkConfig `yaml:"network"`

	// Grafana overrides some values of the otel.MetricsConfig and otel.TracesConfig below
	// for a simpler submission of OTEL metrics to Grafana Cloud
	Grafana otel.GrafanaConfig `yaml:"grafana"`

	Filters filter.AttributesConfig `yaml:"filter"`

	Attributes Attributes `yaml:"attributes"`
	// Routes is an optional node. If not set, data will be directly forwarded to exporters.
	Routes       *transform.RoutesConfig       `yaml:"routes"`
	NameResolver *transform.NameResolverConfig `yaml:"name_resolver"`
	Metrics      otel.MetricsConfig            `yaml:"otel_metrics_export"`
	Traces       otel.TracesConfig             `yaml:"otel_traces_export"`
	Prometheus   prom.PrometheusConfig         `yaml:"prometheus_export"`
	Printer      debug.PrintEnabled            `yaml:"print_traces" env:"BEYLA_PRINT_TRACES"`
	TracePrinter debug.TracePrinter            `yaml:"trace_printer" env:"BEYLA_TRACE_PRINTER"`

	// Exec allows selecting the instrumented executable whose complete path contains the Exec value.
	Exec       services.RegexpAttr `yaml:"executable_name" env:"BEYLA_EXECUTABLE_NAME"`
	ExecOtelGo services.RegexpAttr `env:"OTEL_GO_AUTO_TARGET_EXE"`
	// Port allows selecting the instrumented executable that owns the Port value. If this value is set (and
	// different to zero), the value of the Exec property won't take effect.
	// It's important to emphasize that if your process opens multiple HTTP/GRPC ports, the auto-instrumenter
	// will instrument all the service calls in all the ports, not only the port specified here.
	Port services.PortEnum `yaml:"open_port" env:"BEYLA_OPEN_PORT"`

	// ServiceName is taken from either BEYLA_SERVICE_NAME env var or OTEL_SERVICE_NAME (for OTEL spec compatibility)
	// Using env and envDefault is a trick to get the value either from one of either variables
	ServiceName      string `yaml:"service_name" env:"OTEL_SERVICE_NAME,expand" envDefault:"${BEYLA_SERVICE_NAME}"`
	ServiceNamespace string `yaml:"service_namespace" env:"BEYLA_SERVICE_NAMESPACE"`

	// Discovery configuration
	Discovery services.DiscoveryConfig `yaml:"discovery"`

	LogLevel string `yaml:"log_level" env:"BEYLA_LOG_LEVEL"`

	// Check for required system capabilities and bail if they are not
	// present. If set to 'false', Beyla will still print a list of missing
	// capabilities, but the execution will continue
	EnforceSysCaps bool `yaml:"enforce_sys_caps" env:"BEYLA_ENFORCE_SYS_CAPS"`

	ChannelBufferLen int             `yaml:"channel_buffer_len" env:"BEYLA_CHANNEL_BUFFER_LEN"`
	ProfilePort      int             `yaml:"profile_port" env:"BEYLA_PROFILE_PORT"`
	InternalMetrics  imetrics.Config `yaml:"internal_metrics"`

	// Processes metrics for application. They will be only enabled if there is a metrics exporter enabled,
	// and both the "application" and "application_process" features are enabled
	Processes process.CollectConfig `yaml:"processes"`

	// Grafana Agent specific configuration
	TracesReceiver TracesReceiverConfig `yaml:"-"`
}

func LoadConfig

func LoadConfig(file io.Reader) (*Config, error)

LoadConfig overrides configuration in the following order (from less to most priority) 1 - Default configuration (defaultConfig variable) 2 - Contents of the provided file reader (nillable) 3 - Environment variables

func (*Config) Enabled

func (c *Config) Enabled(feature Feature) bool

Enabled checks if a given Beyla feature is enabled according to the global configuration

func (*Config) ExternalLogger

func (c *Config) ExternalLogger(handler slog.Handler, tracing bool)

ExternalLogger sets the logging capabilities of Beyla. Used for integrating Beyla with an external logging system (for example Alloy) TODO: maybe this method has too many responsibilities, as it affects the global logger.

func (*Config) Validate

func (c *Config) Validate() error

nolint:cyclop

type ConfigError

type ConfigError string

func (ConfigError) Error

func (e ConfigError) Error() string

type Consumer

type Consumer interface {
	otelconsumer.Traces
}

type Feature

type Feature uint

Features that can be enabled in Beyla (can be at the same time): App O11y and/or Net O11y

type HostIDConfig

type HostIDConfig struct {
	// Override allows overriding the reported host.id in Beyla
	Override string `yaml:"override" env:"BEYLA_HOST_ID"`
	// HostIDFetchTimeout specifies the timeout for trying to fetch the HostID from diverse Cloud Providers
	FetchTimeout time.Duration `yaml:"fetch_timeout" env:"BEYLA_HOST_ID_FETCH_TIMEOUT"`
}

type NetworkConfig

type NetworkConfig struct {
	// Enable network metrics.
	// Default value is false (disabled)
	Enable bool `yaml:"enable" env:"BEYLA_NETWORK_METRICS"`

	// Specify the source type for network events, e.g tc or socket_filter. The tc implementation
	// cannot be used when there are other tc eBPF probes, e.g. Cilium CNI.
	Source string `yaml:"source" env:"BEYLA_NETWORK_SOURCE"`

	// AgentIP allows overriding the reported Agent IP address on each flow.
	AgentIP string `yaml:"agent_ip" env:"BEYLA_NETWORK_AGENT_IP"`

	// AgentIPIface specifies which interface should the agent pick the IP address from in order to
	// report it in the AgentIP field on each flow. Accepted values are: external (default), local,
	// or name:<interface name> (e.g. name:eth0).
	// If the AgentIP configuration property is set, this property has no effect.
	AgentIPIface string `yaml:"agent_ip_iface" env:"BEYLA_NETWORK_AGENT_IP_IFACE"`
	// AgentIPType specifies which type of IP address (IPv4 or IPv6 or any) should the agent report
	// in the AgentID field of each flow. Accepted values are: any (default), ipv4, ipv6.
	// If the AgentIP configuration property is set, this property has no effect.
	AgentIPType string `yaml:"agent_ip_type" env:"BEYLA_NETWORK_AGENT_IP_TYPE"`
	// Interfaces contains the interface names from where flows will be collected. If empty, the agent
	// will fetch all the interfaces in the system, excepting the ones listed in ExcludeInterfaces.
	// If an entry is enclosed by slashes (e.g. `/br-/`), it will match as regular expression,
	// otherwise it will be matched as a case-sensitive string.
	Interfaces []string `yaml:"interfaces" env:"BEYLA_NETWORK_INTERFACES" envSeparator:","`
	// ExcludeInterfaces contains the interface names that will be excluded from flow tracing. Default:
	// "lo" (loopback).
	// If an entry is enclosed by slashes (e.g. `/br-/`), it will match as regular expression,
	// otherwise it will be matched as a case-sensitive string.
	ExcludeInterfaces []string `yaml:"exclude_interfaces" env:"BEYLA_NETWORK_EXCLUDE_INTERFACES" envSeparator:","`
	// Protocols causes Beyla to drop flows whose transport protocol is not in this list.
	Protocols []string `yaml:"protocols" env:"BEYLA_NETWORK_PROTOCOLS" envSeparator:","`
	// ExcludeProtocols causes Beyla to drop flows whose transport protocol is in this list.
	// If the Protocols list is already defined, ExcludeProtocols has no effect.
	ExcludeProtocols []string `yaml:"exclude_protocols" env:"BEYLA_NETWORK_EXCLUDE_PROTOCOLS" envSeparator:","`
	// CacheMaxFlows specifies how many flows can be accumulated in the accounting cache before
	// being flushed for its later export. Default value is 5000.
	// Decrease it if you see the "received message larger than max" error in Beyla logs.
	CacheMaxFlows int `yaml:"cache_max_flows" env:"BEYLA_NETWORK_CACHE_MAX_FLOWS"`
	// CacheActiveTimeout specifies the maximum duration that flows are kept in the accounting
	// cache before being flushed for its later export.
	CacheActiveTimeout time.Duration `yaml:"cache_active_timeout" env:"BEYLA_NETWORK_CACHE_ACTIVE_TIMEOUT"`
	// Deduper specifies the deduper type. Accepted values are "none" (disabled) and "first_come".
	// When enabled, it will detect duplicate flows (flows that have been detected e.g. through
	// both the physical and a virtual interface).
	// "first_come" will forward only flows from the first interface the flows are received from.
	// Default value: first_come
	Deduper string `yaml:"deduper" env:"BEYLA_NETWORK_DEDUPER"`
	// DeduperFCTTL specifies the expiry duration of the flows "first_come" deduplicator. After
	// a flow hasn't been received for that expiry time, the deduplicator forgets it. That means
	// that a flow from a connection that has been inactive during that period could be forwarded
	// again from a different interface.
	// If the value is not set, it will default to 2 * CacheActiveTimeout
	DeduperFCTTL time.Duration `yaml:"deduper_fc_ttl" env:"BEYLA_NETWORK_DEDUPER_FC_TTL"`
	// Direction allows selecting which flows to trace according to its direction. Accepted values
	// are "ingress", "egress" or "both" (default).
	Direction string `yaml:"direction" env:"BEYLA_NETWORK_DIRECTION"`
	// Sampling holds the rate at which packets should be sampled and sent to the target collector.
	// E.g. if set to 100, one out of 100 packets, on average, will be sent to the target collector.
	Sampling int `yaml:"sampling" env:"BEYLA_NETWORK_SAMPLING"`
	// ListenInterfaces specifies the mechanism used by the agent to listen for added or removed
	// network interfaces. Accepted values are "watch" (default) or "poll".
	// If the value is "watch", interfaces are traced immediately after they are created. This is
	// the recommended setting for most configurations. "poll" value is a fallback mechanism that
	// periodically queries the current network interfaces (frequency specified by ListenPollPeriod).
	ListenInterfaces string `yaml:"listen_interfaces" env:"BEYLA_NETWORK_LISTEN_INTERFACES"`
	// ListenPollPeriod specifies the periodicity to query the network interfaces when the
	// ListenInterfaces value is set to "poll".
	ListenPollPeriod time.Duration `yaml:"listen_poll_period" env:"BEYLA_NETWORK_LISTEN_POLL_PERIOD"`

	// ReverseDNS allows flows that haven't been previously decorated with any source/destination name
	// to override the name with the network hostname of the source and destination IPs.
	// This is an experimental feature and it is not guaranteed to work on most virtualized environments
	// for external traffic.
	ReverseDNS flow.ReverseDNS `yaml:"reverse_dns"`

	// Print the network flows in the Standard Output, if true
	Print bool `yaml:"print_flows" env:"BEYLA_NETWORK_PRINT_FLOWS"`

	// CIDRs list, to be set as the "src.cidr" and "dst.cidr"
	// attribute as a function of the source and destination IP addresses.
	// If an IP does not match any address here, the attributes won't be set.
	// If an IP matches multiple CIDR definitions, the flow will be decorated with the
	// narrowest CIDR. By this reason, you can safely add a 0.0.0.0/0 entry to group there
	// all the traffic that does not match any of the other CIDRs.
	CIDRs cidr.Definitions `yaml:"cidrs" env:"BEYLA_NETWORK_CIDRS" envSeparator:","`
}

type TracesReceiverConfig

type TracesReceiverConfig struct {
	Traces []Consumer
}

func (TracesReceiverConfig) Enabled

func (t TracesReceiverConfig) Enabled() bool