//! The OTEL bash-command counter: each bash task's normalised shell-command //! "head", counted as `hyperhive.agent.bash.commands` keyed by `command`. //! //! Best-effort: without `OTEL_EXPORTER_OTLP_ENDPOINT`, or when the exporter //! fails to build, or when the command has no head, nothing is counted — //! recording a stat never affects task execution. The daemon exports the //! counter itself, on the same endpoint and resource attributes the harness //! uses for its own metrics. //! //! Normalisation is deliberately rough (quoting-naive) — it just needs //! to name the tool an operator would recognise. The dominant agent //! pattern is `cd && …`, so we look past leading //! `cd …`-style builtins and prefix-runners like `sudo`/`env` to find //! the first real command, then take its basename. use std::sync::OnceLock; use std::time::Duration; use opentelemetry::KeyValue; use opentelemetry::metrics::{Counter, MeterProvider as _}; use opentelemetry_otlp::{MetricExporter, Protocol, WithExportConfig}; use opentelemetry_sdk::metrics::{PeriodicReader, SdkMeterProvider}; /// Export cadence, the same as the harness's metrics. const EXPORT_INTERVAL: Duration = Duration::from_mins(1); struct Exporter { /// Kept alive for the process lifetime - the `PeriodicReader` only /// exports while its provider lives. _provider: SdkMeterProvider, commands: Counter, } /// Built on the first recorded command. `None` when OTEL isn't configured or /// the exporter failed to build; recording is then a cheap no-op. static EXPORTER: OnceLock> = OnceLock::new(); fn build() -> Option { if !std::env::var("OTEL_EXPORTER_OTLP_ENDPOINT").is_ok_and(|s| !s.trim().is_empty()) { return None; } // http/json with the blocking client and no explicit endpoint or // resource, as in the harness's exporter: the `PeriodicReader` exports // from a thread with no Tokio reactor, and the SDK reads the endpoint // and `OTEL_RESOURCE_ATTRIBUTES` from the container-wide environment. let provider = MetricExporter::builder() .with_http() .with_protocol(Protocol::HttpJson) .build() .inspect_err(|e| tracing::warn!(error = %e, "bash stats: OTEL exporter not built")) .ok() .map(|exporter| { let reader = PeriodicReader::builder(exporter) .with_interval(EXPORT_INTERVAL) .build(); SdkMeterProvider::builder().with_reader(reader).build() })?; let commands = commands_counter(&provider); Some(Exporter { _provider: provider, commands, }) } fn commands_counter(provider: &SdkMeterProvider) -> Counter { provider .meter("hyperhive.bash") .u64_counter("hyperhive.agent.bash.commands") .build() } /// Builtins whose presence as a segment head means the *real* command /// is in a later segment (e.g. the `cargo` in `cd repo && cargo build`), /// so we skip the whole segment. const SEGMENT_BUILTINS: &[&str] = &[ "cd", "pushd", "popd", "export", "set", "unset", "source", ".", ":", "true", "false", ]; /// Prefix-runners that wrap the command following them in the SAME /// segment (e.g. the `cargo` in `env FOO=bar cargo build`). We skip the /// runner plus any following flags / env-assignments and unwrap to the /// wrapped command. const PREFIX_RUNNERS: &[&str] = &[ "env", "exec", "sudo", "doas", "nice", "ionice", "stdbuf", "time", "command", "nohup", ]; /// Does `tok` look like a `VAR=value` shell assignment? fn is_assignment(tok: &str) -> bool { match tok.split_once('=') { Some((name, _)) if !name.is_empty() => name.chars().enumerate().all(|(i, c)| { c == '_' || if i == 0 { c.is_ascii_alphabetic() } else { c.is_ascii_alphanumeric() } }), _ => false, } } /// Strip a path prefix: `/nix/store/…/bin/git` -> `git`. fn basename(tok: &str) -> &str { tok.rsplit('/').next().unwrap_or(tok) } /// Resolve the head command of a single segment (no sequencing /// operators inside). `None` for an empty or builtin-only segment. fn segment_head(seg: &str) -> Option { let mut tokens = seg.split_whitespace().peekable(); // Skip leading env-assignments (`FOO=bar cmd`). while tokens.peek().is_some_and(|t| is_assignment(t)) { tokens.next(); } let mut head = tokens.next()?; // Unwrap prefix-runners: skip the runner, its option flags, and any // further env-assignments, then take the wrapped command. Bounded // loop guards against a pathological `sudo sudo sudo …`. let mut guard = 0; while PREFIX_RUNNERS.contains(&basename(head)) && guard < 8 { guard += 1; while tokens.peek().is_some_and(|t| t.starts_with('-')) { tokens.next(); } while tokens.peek().is_some_and(|t| is_assignment(t)) { tokens.next(); } match tokens.next() { Some(next) => head = next, None => return None, // bare `sudo` with nothing after it } } let base = basename(head); if base.is_empty() || SEGMENT_BUILTINS.contains(&base) { return None; } Some(base.to_owned()) } /// Extract a normalised tool name from a shell command line: the /// basename of the first real command, looking past `cd repo &&` /// prefixes, env-assignments, and prefix-runners like `sudo`/`env`. /// `None` when no real command can be identified. #[must_use] pub fn command_head(cmd: &str) -> Option { // Split into segments on shell sequencing operators. Naive: doesn't // honour quotes/escapes — acceptable for a best-effort tally. Order // matters: `||` before `|` so the former isn't shredded by the latter. let mut segments: Vec<&str> = vec![cmd]; for sep in ["&&", "||", ";", "|", "\n"] { segments = segments.into_iter().flat_map(|s| s.split(sep)).collect(); } segments.into_iter().find_map(segment_head) } /// Count one bash task's normalised command head. No-op when OTEL isn't /// configured or the command has no identifiable head. pub fn record_command(cmd: &str) { if let Some(exporter) = EXPORTER.get_or_init(build).as_ref() { count_command(&exporter.commands, cmd); } } /// Add one to `counter`, keyed by `cmd`'s normalised head; nothing when it /// has none. fn count_command(counter: &Counter, cmd: &str) { if let Some(head) = command_head(cmd) { counter.add(1, &[KeyValue::new("command", head)]); } } #[cfg(test)] mod tests { use std::collections::BTreeMap; use opentelemetry_sdk::metrics::InMemoryMetricExporter; use opentelemetry_sdk::metrics::data::{AggregatedMetrics, MetricData, ScopeMetrics}; use super::*; /// What the counter exported for each `command`, after a flush. fn counted(commands: &[&str]) -> BTreeMap { let exporter = InMemoryMetricExporter::default(); let provider = SdkMeterProvider::builder() .with_reader(PeriodicReader::builder(exporter.clone()).build()) .build(); let counter = commands_counter(&provider); for cmd in commands { count_command(&counter, cmd); } provider.force_flush().expect("flush"); let mut counts = BTreeMap::new(); for resource in exporter.get_finished_metrics().expect("metrics") { for metric in resource.scope_metrics().flat_map(ScopeMetrics::metrics) { assert_eq!(metric.name(), "hyperhive.agent.bash.commands"); let AggregatedMetrics::U64(MetricData::Sum(sum)) = metric.data() else { panic!("a counter exports a u64 sum"); }; for point in sum.data_points() { let command = point .attributes() .find(|kv| kv.key.as_str() == "command") .map(|kv| kv.value.to_string()) .expect("every count carries its command"); counts.insert(command, point.value()); } } } counts } #[test] fn each_task_counts_once_under_its_command_head() { let counts = counted(&[ "cd /repo && cargo build", "cargo test -p x", "sudo env A=1 hive-forge view 1", ]); assert_eq!( counts, BTreeMap::from([("cargo".to_owned(), 2), ("hive-forge".to_owned(), 1)]) ); } #[test] fn a_command_without_a_head_counts_nothing() { assert!(counted(&["cd /repo", " "]).is_empty()); } #[test] fn skips_leading_cd_to_the_real_tool() { assert_eq!( command_head("cd /repo && cargo build").as_deref(), Some("cargo") ); assert_eq!( command_head("cd /a/b && export X=1; hive-forge view 1").as_deref(), Some("hive-forge") ); } #[test] fn strips_store_path_to_basename() { assert_eq!( command_head("/nix/store/abc123/bin/git status").as_deref(), Some("git") ); assert_eq!( command_head("VAR=1 ./script.sh").as_deref(), Some("script.sh") ); } #[test] fn skips_leading_env_assignments() { assert_eq!( command_head("FOO=bar BAZ=qux make").as_deref(), Some("make") ); } #[test] fn unwraps_prefix_runners() { assert_eq!( command_head("sudo systemctl restart nginx").as_deref(), Some("systemctl") ); assert_eq!( command_head("env RUST_LOG=debug cargo test").as_deref(), Some("cargo") ); assert_eq!(command_head("time nix build").as_deref(), Some("nix")); } #[test] fn first_command_of_a_pipeline() { assert_eq!( command_head("git log --oneline | head -5").as_deref(), Some("git") ); } #[test] fn none_for_empty_or_builtin_only() { assert_eq!(command_head(""), None); assert_eq!(command_head(" "), None); assert_eq!(command_head("cd /only/dir"), None); assert_eq!(command_head("sudo"), None); } #[test] fn assignment_detector() { assert!(is_assignment("FOO=bar")); assert!(is_assignment("RUST_LOG=debug")); assert!(!is_assignment("--flag")); assert!(!is_assignment("=leading")); assert!(!is_assignment("git")); } }