beyla

Documentation

Index

• Constants
• Variables
• func CheckOSCapabilities(config *Config) error
• func CheckOSSupport() error
• 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:   true,
	EBPF: ebpfcommon.TracerConfig{
		BatchLength:        100,
		BatchTimeout:       time.Second,
		BpfBaseDir:         "/var/run/beyla",
		BpfPath:            fmt.Sprintf("beyla-%d", os.Getpid()),
		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: 100 * 365 * 24 * time.Hour,
	},
	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,
		},
		HostID: HostIDConfig{
			FetchTimeout: 500 * time.Millisecond,
		},
	},
	Routes:       &transform.RoutesConfig{Unmatch: transform.UnmatchHeuristic},
	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.

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 ebpfcommon.TracerConfig `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