Agent Architecture

The denpex-enterprise-agent is a long-running host process that collects hardware signals, eBPF traces, host telemetry, and exports OTLP envelopes to the control plane.

Lifecycle

1. Boot — read /etc/denpex/agent.yaml, load config, start metrics + eBPF + journald readers.
2. Discovery — enumerate NVML devices, DCGM group, IB devices, ROCE NICs, top NUMA nodes, MIIG instances.
3. Steady-state — emit 1Hz OTLP envelopes with current GPU/IB/NIC counters and any new eBPF/PSI/procfs events.
4. Incident mode — when triggered by --enable-cupti, subscribe to CUPTI activity/callback for 1s windows.
5. Shutdown — flush ring buffers, write final audit record, exit.

Privilege Model

The agent emits a host_event { kind: capability_missing, ... } for any capability it cannot acquire, and continues with reduced collection depth.

Threading Model

• Main thread: config load + signal handling.
• eBPF loader thread: loads *.bpf.o once at start.
• Ring-buffer consumer threads: one per program; cap 1,000 events/sec with drop+counter on overflow.
• Metrics thread: polls NVML/DCGM at 1 Hz (configurable).
• Exporter thread: ships OTLP envelopes to control-plane.

Crate Layout

agents/denpex-enterprise-agent/
├── src/
│   ├── gpu/
│   │   ├── nvml.rs        # NVMLCollector (FFI)
│   │   ├── dcgm.rs        # DCGMCollector (FFI)
│   │   └── cupti.rs       # CUPTI activity/callback (opt-in)
│   ├── host/
│   │   ├── ebpf.rs       # eBPF loader, ringbuf consumer
│   │   ├── ebpf_programs/
│   │   │   ├── sched_switch.bpf.c
│   │   │   ├── oom_kill.bpf.c
│   │   │   └── ...
│   │   ├── psi.rs        # /proc/pressure/*
│   │   ├── journald.rs   # libsystemd-sys
│   │   └── ...
│   ├── topology.rs       # DMA, NUMA, IRQ affinity
│   └── otlp.rs           # OTLP exporter (tonic + prost)

Crash Semantics

The agent never crashes on a hook failure — every callback is wrapped in catch_unwind. A panic in one eBPF consumer drops into a backoff and reattaches; never takes down the agent.