Add tool to check undocumented fields (#1722)

.github/workflows/check-docs.yml

@@ -0,0 +1,26 @@
+name: Check Undocumented Fields
+
+on:
+  pull_request:
+    paths:
+      - '**.go'
+      - 'docs/**/*.md'
+  push:
+    branches: [ main ]
+    paths:
+      - '**.go'
+      - 'docs/**/*.md'
+
+jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Run documentation checker
+        run: go run ./tools/doc-checker/main.go 

pkg/beyla/config.go

@@ -153,15 +153,17 @@ type Config struct {
 
 	Attributes Attributes `yaml:"attributes"`
 	// Routes is an optional node. If not set, data will be directly forwarded to exporters.
-	Routes       *transform.RoutesConfig       `yaml:"routes"`
+	Routes *transform.RoutesConfig `yaml:"routes"`
+	// nolint:undoc
 	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"`
 	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"`
+	Exec services.RegexpAttr `yaml:"executable_name" env:"BEYLA_EXECUTABLE_NAME"`
+	// nolint:undoc
 	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.
@@ -187,9 +189,11 @@ type Config struct {
 	// From this comment, the properties below will remain undocumented, as they
 	// are useful for development purposes. They might be helpful for customer support.
 
-	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"`
+	// nolint:undoc
+	ChannelBufferLen int `yaml:"channel_buffer_len" env:"BEYLA_CHANNEL_BUFFER_LEN"`
+	// nolint:undoc
+	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
@@ -222,8 +226,10 @@ type Attributes struct {
 
 type HostIDConfig struct {
 	// Override allows overriding the reported host.id in Beyla
+	// nolint:undoc
 	Override string `yaml:"override" env:"BEYLA_HOST_ID"`
-	// HostIDFetchTimeout specifies the timeout for trying to fetch the HostID from diverse Cloud Providers
+	// FetchTimeout specifies the timeout for trying to fetch the HostID from diverse Cloud Providers
+	// nolint:undoc
 	FetchTimeout time.Duration `yaml:"fetch_timeout" env:"BEYLA_HOST_ID_FETCH_TIMEOUT"`
 }
 

pkg/beyla/network_cfg.go

@@ -80,15 +80,18 @@ type NetworkConfig struct {
 	// 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
+	// nolint:undoc
 	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
+	// nolint:undoc
 	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).
+	// nolint:undoc
 	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.
@@ -98,17 +101,19 @@ type NetworkConfig struct {
 	// 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).
+	// nolint:undoc
 	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".
+	// nolint:undoc
 	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.
+	// nolint:undoc
 	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"`
 

pkg/config/ebpf_tracer.go

@@ -9,6 +9,7 @@ import (
 // EBPFTracer configuration for eBPF programs
 type EBPFTracer struct {
 	// Enables logging of eBPF program events
+	// nolint:undoc
 	BpfDebug bool `yaml:"bpf_debug" env:"BEYLA_BPF_DEBUG"`
 
 	// WakeupLen specifies how many messages need to be accumulated in the eBPF ringbuffer
@@ -19,9 +20,11 @@ type EBPFTracer struct {
 	WakeupLen int `yaml:"wakeup_len" env:"BEYLA_BPF_WAKEUP_LEN"`
 	// BatchLength allows specifying how many traces will be batched at the initial
 	// stage before being forwarded to the next stage
+	// nolint:undoc
 	BatchLength int `yaml:"batch_length" env:"BEYLA_BPF_BATCH_LENGTH"`
 	// BatchTimeout specifies the timeout to forward the data batch if it didn't
 	// reach the BatchLength size
+	// nolint:undoc
 	BatchTimeout time.Duration `yaml:"batch_timeout" env:"BEYLA_BPF_BATCH_TIMEOUT"`
 
 	// If enabled, the kprobes based HTTP request tracking will start tracking the request
@@ -35,16 +38,19 @@ type EBPFTracer struct {
 
 	// Skips checking the kernel version for bpf_loop functionality. Some modified kernels have this
 	// backported prior to version 5.17.
+	// nolint:undoc
 	OverrideBPFLoopEnabled bool `yaml:"override_bpfloop_enabled" env:"BEYLA_OVERRIDE_BPF_LOOP_ENABLED"`
 
 	// Enables Linux Traffic Control probes for context propagation
+	// nolint:undoc
 	UseTCForL7CP bool `yaml:"traffic_control_l7_context_propagation" env:"BEYLA_BPF_TC_L7_CP"`
 
 	// Select the TC attachment backend: accepted values are 'tc' (netlink),
 	// and 'tcx'
 	TCBackend tcmanager.TCBackend `yaml:"traffic_control_backend" env:"BEYLA_BPF_TC_BACKEND"`
 
 	// Disables Beyla black-box context propagation. Used for testing purposes only.
+	// nolint:undoc
 	DisableBlackBoxCP bool `yaml:"disable_black_box_cp" env:"BEYLA_BPF_DISABLE_BLACK_BOX_CP"`
 
 	// Optimises for getting requests information immediately when request response is seen
@@ -55,11 +61,14 @@ type EBPFTracer struct {
 	HeuristicSQLDetect bool `yaml:"heuristic_sql_detect" env:"BEYLA_HEURISTIC_SQL_DETECT"`
 
 	// Enables GPU instrumentation for CUDA kernel launches and allocations
+	// nolint:undoc
 	InstrumentGPU bool `yaml:"instrument_gpu" env:"BEYLA_INSTRUMENT_GPU"`
 
 	// Enables debug printing of the protocol data
+	// nolint:undoc
 	ProtocolDebug bool `yaml:"protocol_debug_print" env:"BEYLA_PROTOCOL_DEBUG_PRINT"`
 
 	// Enables Java instrumentation with the OpenTelemetry JDK Agent
+	// nolint:undoc
 	UseOTelSDKForJava bool `yaml:"use_otel_sdk_for_java" env:"BEYLA_USE_OTEL_SDK_FOR_JAVA"`
 }

pkg/export/otel/metrics.go

@@ -75,6 +75,7 @@ type MetricsConfig struct {
 	Interval time.Duration `yaml:"interval" env:"BEYLA_METRICS_INTERVAL"`
 	// OTELIntervalMS supports metric intervals as specified by the standard OTEL definition.
 	// BEYLA_METRICS_INTERVAL takes precedence over it.
+	// nolint:undoc
 	OTELIntervalMS int `env:"OTEL_METRIC_EXPORT_INTERVAL"`
 
 	CommonEndpoint  string `yaml:"-" env:"OTEL_EXPORTER_OTLP_ENDPOINT"`
@@ -89,10 +90,12 @@ type MetricsConfig struct {
 	Buckets              Buckets `yaml:"buckets"`
 	HistogramAggregation string  `yaml:"histogram_aggregation" env:"OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION"`
 
+	// nolint:undoc
 	ReportersCacheLen int `yaml:"reporters_cache_len" env:"BEYLA_METRICS_REPORT_CACHE_LEN"`
 
 	// SDKLogLevel works independently from the global LogLevel because it prints GBs of logs in Debug mode
 	// and the Info messages leak internal details that are not usually valuable for the final user.
+	// nolint:undoc
 	SDKLogLevel string `yaml:"otel_sdk_log_level" env:"BEYLA_OTEL_SDK_LOG_LEVEL"`
 
 	// Features of metrics that are can be exported. Accepted values are "application" and "network".
@@ -104,6 +107,7 @@ type MetricsConfig struct {
 
 	// TTL is the time since a metric was updated for the last time until it is
 	// removed from the metrics set.
+	// nolint:undoc
 	TTL time.Duration `yaml:"ttl" env:"BEYLA_OTEL_METRICS_TTL"`
 
 	AllowServiceGraphSelfReferences bool `yaml:"allow_service_graph_self_references" env:"BEYLA_OTEL_ALLOW_SERVICE_GRAPH_SELF_REFERENCES"`

pkg/export/otel/traces.go

@@ -73,24 +73,32 @@ type TracesConfig struct {
 
 	// Configuration options below this line will remain undocumented at the moment,
 	// but can be useful for performance-tuning of some customers.
-	MaxExportBatchSize int           `yaml:"max_export_batch_size" env:"BEYLA_OTLP_TRACES_MAX_EXPORT_BATCH_SIZE"`
-	MaxQueueSize       int           `yaml:"max_queue_size" env:"BEYLA_OTLP_TRACES_MAX_QUEUE_SIZE"`
-	BatchTimeout       time.Duration `yaml:"batch_timeout" env:"BEYLA_OTLP_TRACES_BATCH_TIMEOUT"`
-	ExportTimeout      time.Duration `yaml:"export_timeout" env:"BEYLA_OTLP_TRACES_EXPORT_TIMEOUT"`
+	// nolint:undoc
+	MaxExportBatchSize int `yaml:"max_export_batch_size" env:"BEYLA_OTLP_TRACES_MAX_EXPORT_BATCH_SIZE"`
+	// nolint:undoc
+	MaxQueueSize int `yaml:"max_queue_size" env:"BEYLA_OTLP_TRACES_MAX_QUEUE_SIZE"`
+	// nolint:undoc
+	BatchTimeout time.Duration `yaml:"batch_timeout" env:"BEYLA_OTLP_TRACES_BATCH_TIMEOUT"`
+	// nolint:undoc
+	ExportTimeout time.Duration `yaml:"export_timeout" env:"BEYLA_OTLP_TRACES_EXPORT_TIMEOUT"`
 
 	// Configuration options for BackOffConfig of the traces exporter.
 	// See https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configretry/backoff.go
 	// BackOffInitialInterval the time to wait after the first failure before retrying.
+	// nolint:undoc
 	BackOffInitialInterval time.Duration `yaml:"backoff_initial_interval" env:"BEYLA_BACKOFF_INITIAL_INTERVAL"`
 	// BackOffMaxInterval is the upper bound on backoff interval.
+	// nolint:undoc
 	BackOffMaxInterval time.Duration `yaml:"backoff_max_interval" env:"BEYLA_BACKOFF_MAX_INTERVAL"`
 	// BackOffMaxElapsedTime is the maximum amount of time (including retries) spent trying to send a request/batch.
+	// nolint:undoc
 	BackOffMaxElapsedTime time.Duration `yaml:"backoff_max_elapsed_time" env:"BEYLA_BACKOFF_MAX_ELAPSED_TIME"`
-
+	// nolint:undoc
 	ReportersCacheLen int `yaml:"reporters_cache_len" env:"BEYLA_TRACES_REPORT_CACHE_LEN"`
 
 	// SDKLogLevel works independently from the global LogLevel because it prints GBs of logs in Debug mode
 	// and the Info messages leak internal details that are not usually valuable for the final user.
+	// nolint:undoc
 	SDKLogLevel string `yaml:"otel_sdk_log_level" env:"BEYLA_OTEL_SDK_LOG_LEVEL"`
 
 	// Grafana configuration needs to be explicitly set up before building the graph

pkg/export/prom/prom.go

@@ -100,6 +100,7 @@ type PrometheusConfig struct {
 	Port int    `yaml:"port" env:"BEYLA_PROMETHEUS_PORT"`
 	Path string `yaml:"path" env:"BEYLA_PROMETHEUS_PATH"`
 
+	// nolint:undoc
 	DisableBuildInfo bool `yaml:"disable_build_info" env:"BEYLA_PROMETHEUS_DISABLE_BUILD_INFO"`
 
 	// Features of metrics that are can be exported. Accepted values are "application" and "network".
@@ -111,8 +112,9 @@ type PrometheusConfig struct {
 
 	// TTL is the time since a metric was updated for the last time until it is
 	// removed from the metrics set.
-	TTL                         time.Duration `yaml:"ttl" env:"BEYLA_PROMETHEUS_TTL"`
-	SpanMetricsServiceCacheSize int           `yaml:"service_cache_size"`
+	TTL time.Duration `yaml:"ttl" env:"BEYLA_PROMETHEUS_TTL"`
+	// nolint:undoc
+	SpanMetricsServiceCacheSize int `yaml:"service_cache_size"`
 
 	AllowServiceGraphSelfReferences bool `yaml:"allow_service_graph_self_references" env:"BEYLA_PROMETHEUS_ALLOW_SERVICE_GRAPH_SELF_REFERENCES"`
 

pkg/internal/infraolly/process/collect.go

@@ -36,6 +36,7 @@ type CollectConfig struct {
 	RunMode RunMode
 
 	// Interval between harvests
+	// nolint:undoc
 	Interval time.Duration `yaml:"interval" env:"BEYLA_PROCESSES_INTERVAL"`
 }
 

pkg/internal/kube/store.go

@@ -40,7 +40,9 @@ func qName(om *informer.ObjectMeta) qualifiedName {
 // MetaSourceLabels allow overriding some metadata from kubernetes labels
 // Deprecated. Left here for backwards-compatibility.
 type MetaSourceLabels struct {
-	ServiceName      string `yaml:"service_name" env:"BEYLA_KUBE_META_SOURCE_LABEL_SERVICE_NAME"`
+	// nolint:undoc
+	ServiceName string `yaml:"service_name" env:"BEYLA_KUBE_META_SOURCE_LABEL_SERVICE_NAME"`
+	// nolint:undoc
 	ServiceNamespace string `yaml:"service_namespace" env:"BEYLA_KUBE_META_SOURCE_LABEL_SERVICE_NAMESPACE"`
 }
 

pkg/internal/netolly/flow/reverse_dns.go

@@ -26,13 +26,16 @@ var netLookupAddr = net.LookupAddr
 // from the documentation. This means that it does not impact in the overall Beyla performance.
 type ReverseDNS struct {
 	// Type of ReverseDNS. Values are "none" (default) and "local".
+	// nolint:undoc
 	Type string `yaml:"type" env:"BEYLA_NETWORK_REVERSE_DNS_TYPE"`
 	// CacheLen specifies the max size of the LRU cache that is checked before
 	// performing the name lookup. Default: 256
+	// nolint:undoc
 	CacheLen int `yaml:"cache_len" env:"BEYLA_NETWORK_REVERSE_DNS_CACHE_LEN"`
 	// CacheTTL specifies the time-to-live of a cached IP->hostname entry. After the
 	// cached entry becomes older than this time, the IP->hostname entry will be looked
 	// up again.
+	// nolint:undoc
 	CacheTTL time.Duration `yaml:"cache_expiry" env:"BEYLA_NETWORK_REVERSE_DNS_CACHE_TTL"`
 }
 

pkg/kubecache/config.go

@@ -14,14 +14,19 @@ import (
 // Config options of the Kubernetes Cache service. Check the "DefaultConfig" variable for a view of the default values.
 type Config struct {
 	// LogLevel can be one of: debug, info, warn, error
+	// nolint:undoc
 	LogLevel string `yaml:"log_level" env:"BEYLA_K8S_CACHE_LOG_LEVEL"`
 	// Port where the service is going to listen to
+	// nolint:undoc
 	Port int `yaml:"port" env:"BEYLA_K8S_CACHE_PORT"`
 	// MaxConnection is the maximum number of concurrent clients that the service can handle at the same time
+	// nolint:undoc
 	MaxConnections int `yaml:"max_connections" env:"BEYLA_K8S_CACHE_MAX_CONNECTIONS"`
 	// ProfilePort is the port where the pprof server is going to listen to. 0 (default) means disabled
+	// nolint:undoc
 	ProfilePort int `yaml:"profile_port" env:"BEYLA_K8S_CACHE_PROFILE_PORT"`
 	// InformerResyncPeriod is the time interval between complete resyncs of the informers
+	// nolint:undoc
 	InformerResyncPeriod time.Duration `yaml:"informer_resync_period" env:"BEYLA_K8S_CACHE_INFORMER_RESYNC_PERIOD"`
 
 	InternalMetrics instrument.InternalMetricsConfig `yaml:"internal_metrics"`

pkg/kubecache/instrument/server.go

@@ -9,7 +9,9 @@ import (
 const defaultMetricsPath = "/metrics"
 
 type InternalMetricsConfig struct {
-	Port int    `yaml:"port,omitempty" env:"BEYLA_K8S_CACHE_INTERNAL_METRICS_PROMETHEUS_PORT"`
+	// nolint:undoc
+	Port int `yaml:"port,omitempty" env:"BEYLA_K8S_CACHE_INTERNAL_METRICS_PROMETHEUS_PORT"`
+	// nolint:undoc
 	Path string `yaml:"path,omitempty" env:"BEYLA_K8S_CACHE_INTERNAL_METRICS_PROMETHEUS_PATH"`
 }
 

pkg/services/criteria.go

@@ -57,17 +57,20 @@ type DiscoveryConfig struct {
 
 	// PollInterval specifies, for the poll service watcher, the interval time between
 	// process inspections
+	// nolint:undoc
 	PollInterval time.Duration `yaml:"poll_interval" env:"BEYLA_DISCOVERY_POLL_INTERVAL"`
 
 	// SystemWide allows instrumentation of all HTTP (no gRPC) calls, incoming and outgoing at a system wide scale.
 	// No filtering per application will be done. Using this option may result in reduced quality of information
 	// gathered for certain languages, such as Golang.
+	// nolint:undoc
 	SystemWide bool `yaml:"system_wide" env:"BEYLA_SYSTEM_WIDE"`
 
 	// This can be enabled to use generic HTTP tracers only, no Go-specifics will be used:
 	SkipGoSpecificTracers bool `yaml:"skip_go_specific_tracers" env:"BEYLA_SKIP_GO_SPECIFIC_TRACERS"`
 
 	// Debugging only option. Make sure the kernel side doesn't filter any PIDs, force user space filtering.
+	// nolint:undoc
 	BPFPidFilterOff bool `yaml:"bpf_pid_filter_off" env:"BEYLA_BPF_PID_FILTER_OFF"`
 
 	// Disables instrumentation of services which are already instrumented

pkg/transform/k8s.go

@@ -25,6 +25,7 @@ type KubernetesDecorator struct {
 
 	// ClusterName overrides cluster name. If empty, the NetO11y module will try to retrieve
 	// it from the Cloud Provider Metadata (EC2, GCP and Azure), and leave it empty if it fails to.
+	// nolint:undoc
 	ClusterName string `yaml:"cluster_name" env:"BEYLA_KUBE_CLUSTER_NAME"`
 
 	// KubeconfigPath is optional. If unset, it will look in the usual location.
@@ -37,6 +38,7 @@ type KubernetesDecorator struct {
 
 	// DropExternal will drop, in NetO11y component, any flow where the source or destination
 	// IPs are not matched to any kubernetes entity, assuming they are cluster-external
+	// nolint:undoc
 	DropExternal bool `yaml:"drop_external" env:"BEYLA_NETWORK_DROP_EXTERNAL"`
 
 	// DisableInformers allows selectively disabling some informers. Accepted value is a list
@@ -47,6 +49,7 @@ type KubernetesDecorator struct {
 	DisableInformers []string `yaml:"disable_informers" env:"BEYLA_KUBE_DISABLE_INFORMERS"`
 
 	// MetaCacheAddress is the host:port address of the beyla-k8s-cache service instance
+	// nolint:undoc
 	MetaCacheAddress string `yaml:"meta_cache_address" env:"BEYLA_KUBE_META_CACHE_ADDRESS"`
 
 	// MetaRestrictLocalNode will download only the metadata from the Pods that are located in the same
@@ -59,6 +62,7 @@ type KubernetesDecorator struct {
 	MetaSourceLabels kube.MetaSourceLabels `yaml:"meta_source_labels"`
 
 	// ResourceLabels allows Beyla overriding the OTEL Resource attributes from a map of user-defined labels.
+	// nolint:undoc
 	ResourceLabels kube.ResourceLabels `yaml:"resource_labels"`
 }
 

pkg/transform/name_resolver.go

@@ -34,13 +34,16 @@ func resolverSources(str []string) maps.Bits {
 
 type NameResolverConfig struct {
 	// Sources for name resolving. Accepted values: dns, k8s
+	// nolint:undoc
 	Sources []string `yaml:"sources" env:"BEYLA_NAME_RESOLVER_SOURCES" envSeparator:"," envDefault:"k8s"`
 	// CacheLen specifies the max size of the LRU cache that is checked before
 	// performing the name lookup. Default: 256
+	// nolint:undoc
 	CacheLen int `yaml:"cache_len" env:"BEYLA_NAME_RESOLVER_CACHE_LEN"`
 	// CacheTTL specifies the time-to-live of a cached IP->hostname entry. After the
 	// cached entry becomes older than this time, the IP->hostname entry will be looked
 	// up again.
+	// nolint:undoc
 	CacheTTL time.Duration `yaml:"cache_expiry" env:"BEYLA_NAME_RESOLVER_CACHE_TTL"`
 }