cli_flags.go

// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

package main

import (
	"flag"
	"fmt"
	"os"
	"strings"
	"time"

	"github.com/peterbourgon/ff/v3"

	"go.opentelemetry.io/ebpf-profiler/collector/config"
	"go.opentelemetry.io/ebpf-profiler/internal/controller"
	"go.opentelemetry.io/ebpf-profiler/internal/log"
	"go.opentelemetry.io/ebpf-profiler/interpreter/interpreterconfig"
	pm "go.opentelemetry.io/ebpf-profiler/processmanager"
	"go.opentelemetry.io/ebpf-profiler/tracer"
)

const (
	// Default values for CLI flags
	defaultArgSamplesPerSecond    = 20
	defaultArgReporterInterval    = 5.0 * time.Second
	defaultArgReporterJitter      = 0.2
	defaultArgMonitorInterval     = 5.0 * time.Second
	defaultClockSyncInterval      = 3 * time.Minute
	defaultProbabilisticThreshold = tracer.ProbabilisticThresholdMax
	defaultProbabilisticInterval  = 1 * time.Minute
	defaultArgSendErrorFrames     = false
	defaultEnvVarsValue           = ""
	defaultArgFrameCacheSize      = pm.DefaultFrameCacheSize
	defaultBPFFSRoot              = "/sys/fs/bpf/"

	// This is the X in 2^(n + x) where n is the default hardcoded map size value
	defaultArgMapScaleFactor = 0
)

// Help strings for command line arguments
var (
	noKernelVersionCheckHelp = "Disable checking kernel version for eBPF support. " +
		"Use at your own risk, to run the agent on older kernels with backported eBPF features."
	copyrightHelp      = "Show copyright and short license text."
	collAgentAddrHelp  = "The collection agent address in the format of host:port."
	verboseModeHelp    = "Enable verbose logging and debugging capabilities."
	tracersHelp        = "Comma-separated list of interpreter tracers to include."
	mapScaleFactorHelp = fmt.Sprintf("Scaling factor for eBPF map sizes. "+
		"Every increase by 1 doubles the map size. Increase if you see eBPF map size errors. "+
		"Default is %d corresponding to 4GB of executable address space, max is %d.",
		defaultArgMapScaleFactor, config.MaxArgMapScaleFactor)
	disableTLSHelp             = "Disable encryption for data in transit."
	bpfVerifierLogLevelHelp    = "Log level of the eBPF verifier output (0,1,2). Default is 0."
	versionHelp                = "Show version."
	probabilisticThresholdHelp = fmt.Sprintf("If set to a value between 1 and %d will enable "+
		"probabilistic profiling: "+
		"every probabilistic-interval a random number between 0 and %d is "+
		"chosen. If the given probabilistic-threshold is greater than this "+
		"random number, the agent will collect profiles from this system for "+
		"the duration of the interval.",
		tracer.ProbabilisticThresholdMax-1, tracer.ProbabilisticThresholdMax-1)
	probabilisticIntervalHelp = "Time interval for which probabilistic profiling will be " +
		"enabled or disabled."
	pprofHelp            = "Listening address (e.g. localhost:6060) to serve pprof information."
	samplesPerSecondHelp = "Set the frequency (in Hz) of stack trace sampling."
	reporterIntervalHelp = "Set the reporter's interval in seconds."
	reporterJitterHelp   = fmt.Sprintf("Set the jitter applied to the reporter's interval as a fraction. "+
		"Valid values are in the range [0..1]. "+
		"Default is %.1f.",
		defaultArgReporterJitter)
	monitorIntervalHelp   = "Set the monitor interval in seconds."
	clockSyncIntervalHelp = "Set the sync interval with the realtime clock. " +
		"If zero, monotonic-realtime clock sync will be performed once, " +
		"on agent startup, but not periodically."
	sendErrorFramesHelp     = "Send error frames (devfiler only, breaks Kibana)"
	sendIdleFramesHelp      = "Unwind and report idle states of the Linux kernel."
	filterMinProcessAgeHelp = "Skip samples from processes younger than this minimum age. " +
		"Set to 0 to disable minimum process age filtering."
	envVarsHelp = "Comma separated list of environment variables that will be reported with the" +
		"captured profiling samples."
	frameCacheSizeHelp = fmt.Sprintf("Set the maximum number of entries in the frame cache. "+
		"Default is %d.", defaultArgFrameCacheSize)
	bpffsHelp = fmt.Sprintf("Set the root BPF FS path for pinned maps. Only used for OBI span/trace ID communication. Default is %s",
		defaultBPFFSRoot)
	obiProcessCtxHelp = "Load or create a pinned eBPF map for sharing process context information with OBI."
	pinnedCPUIDsHelp  = "Range of CPUs to profile in the format like \"0-15,20,31\". Only for on-CPU sampling. " +
		"WARNING: This filter is effective only if your target workloads (processes, IRQ handlers, etc.) " +
		"are explicitly pinned to provided CPUs. " +
		"In non-pinned environments, profiling a subset of CPUs will produce biased or incomplete results. " +
		"For profiling specific applications, consider using sidecar deployments or custom probes instead."
)

// Package-scope variable, so that conditionally compiled other components can refer
// to the same flagset.

func parseArgs() (*controller.Config, error) {
	var args controller.Config
	var tracers string

	fs := flag.NewFlagSet("ebpf-profiler", flag.ExitOnError)

	// Please keep the parameters ordered alphabetically in the source-code.
	fs.UintVar(&args.BPFVerifierLogLevel, "bpf-log-level", 0, bpfVerifierLogLevelHelp)

	fs.StringVar(&args.CollAgentAddr, "collection-agent", "", collAgentAddrHelp)
	fs.BoolVar(&args.Copyright, "copyright", false, copyrightHelp)

	fs.BoolVar(&args.DisableTLS, "disable-tls", false, disableTLSHelp)

	fs.DurationVar(&args.FilterMinProcessAge, "filter-min-process-age", 0, filterMinProcessAgeHelp)

	fs.UintVar(&args.FrameCacheSize, "frame-cache-size",
		uint(defaultArgFrameCacheSize), frameCacheSizeHelp)

	fs.UintVar(&args.MapScaleFactor, "map-scale-factor",
		defaultArgMapScaleFactor, mapScaleFactorHelp)

	fs.DurationVar(&args.MonitorInterval, "monitor-interval", defaultArgMonitorInterval,
		monitorIntervalHelp)

	fs.DurationVar(&args.ClockSyncInterval, "clock-sync-interval", defaultClockSyncInterval,
		clockSyncIntervalHelp)

	fs.BoolVar(&args.NoKernelVersionCheck, "no-kernel-version-check", false,
		noKernelVersionCheckHelp)

	fs.Func("pin-cpu-ids", pinnedCPUIDsHelp, func(cpuRange string) error {
		CPUIDs, err := tracer.ReadCPURange(cpuRange)
		if err != nil {
			return fmt.Errorf("failed to parse pinned CPUs range '%s': %v", cpuRange, err)
		}
		args.PinnedCPUIDs = CPUIDs
		return nil
	})

	fs.StringVar(&args.PprofAddr, "pprof", "", pprofHelp)

	fs.DurationVar(&args.ProbabilisticInterval, "probabilistic-interval",
		defaultProbabilisticInterval, probabilisticIntervalHelp)
	fs.UintVar(&args.ProbabilisticThreshold, "probabilistic-threshold",
		defaultProbabilisticThreshold, probabilisticThresholdHelp)

	fs.DurationVar(&args.ReporterInterval, "reporter-interval", defaultArgReporterInterval,
		reporterIntervalHelp)
	fs.Float64Var(&args.ReporterJitter, "reporter-jitter", defaultArgReporterJitter,
		reporterJitterHelp)

	fs.IntVar(&args.SamplesPerSecond, "samples-per-second", defaultArgSamplesPerSecond,
		samplesPerSecondHelp)

	fs.BoolVar(&args.SendErrorFrames, "send-error-frames", defaultArgSendErrorFrames,
		sendErrorFramesHelp)
	fs.BoolVar(&args.SendIdleFrames, "send-idle-frames", false, sendIdleFramesHelp)

	fs.StringVar(&tracers, "t", "all", "Shorthand for -tracers.")
	fs.StringVar(&tracers, "tracers", "all", tracersHelp)

	fs.BoolVar(&args.VerboseMode, "v", false, "Shorthand for -verbose.")
	fs.BoolVar(&args.VerboseMode, "verbose", false, verboseModeHelp)
	fs.BoolVar(&args.Version, "version", false, versionHelp)

	fs.StringVar(&args.IncludeEnvVars, "env-vars", defaultEnvVarsValue, envVarsHelp)

	fs.StringVar(&args.BPFFSRoot, "bpffs-root", defaultBPFFSRoot, bpffsHelp)

	fs.BoolVar(&args.OBIProcessCtx, "obi-process-ctx", false, obiProcessCtxHelp)

	fs.Usage = func() {
		fs.PrintDefaults()
	}

	args.Fs = fs

	args.ErrorMode = config.PropagateError

	if err := ff.Parse(fs, os.Args[1:],
		ff.WithEnvVarPrefix("OTEL_PROFILING_AGENT"),
		ff.WithConfigFileFlag("config"),
		ff.WithConfigFileParser(ff.PlainParser),
		// This will ignore configuration file (only) options that the current HA
		// does not recognize.
		ff.WithIgnoreUndefined(true),
		ff.WithAllowMissingConfigFile(true),
	); err != nil {
		return nil, err
	}

	interpreters, err := parseTracers(tracers)
	if err != nil {
		return nil, err
	}
	args.Interpreters = interpreters

	return &args, nil
}

// parseTracers parses the comma-separated tracers string and returns an
// interpreterconfig.Config with only the listed interpreters enabled.
// "all" enables every interpreter.
// Unknown names return an error.
func parseTracers(tracers string) (interpreterconfig.Config, error) {
	for name := range strings.SplitSeq(tracers, ",") {
		if strings.ToLower(strings.TrimSpace(name)) == "all" {
			return interpreterconfig.AllInterpreters(), nil
		}
	}

	// Start with all interpreters disabled; enable only the ones listed.
	cfg := interpreterconfig.NoInterpreters()
	for name := range strings.SplitSeq(tracers, ",") {
		name = strings.ToLower(strings.TrimSpace(name))
		switch name {
		case "python":
			cfg.Python.Disabled = false
		case "perl":
			cfg.Perl.Disabled = false
		case "php":
			cfg.PHP.Disabled = false
		case "hotspot":
			cfg.Hotspot.Disabled = false
		case "ruby":
			cfg.Ruby.Disabled = false
		case "v8":
			cfg.V8.Disabled = false
		case "dotnet":
			cfg.Dotnet.Disabled = false
		case "go":
			cfg.Go.Disabled = false
			cfg.Go.Symbolization.Disabled = false
		case "labels":
			cfg.Go.Disabled = false
			cfg.Go.Labels.Disabled = false
		case "beam":
			cfg.BEAM.Disabled = false
		case "thread_context":
			log.Warn("The thread context interpreter is a stub and does not do anything yet")
			cfg.ThreadContext.Disabled = false
		case "luajit":
			log.Warn("The LuaJIT interpreter is incomplete and may not work properly")
			cfg.LuaJIT.Disabled = false
		case "native":
			log.Warn("Enabling the `native` tracer explicitly is deprecated (it's always-on)")
		case "":
			// ignore empty segments
		default:
			return interpreterconfig.Config{}, fmt.Errorf("unknown tracer: %s", name)
		}
	}

	return cfg, nil
}