Run the signal plane. Understand every boundary.

Local run

The synthetic source exercises the static pipeline, versioned envelopes, generators, and default JSON output without eBPF, Docker, or Kubernetes.

cargo run --locked -p e-navigator-cli -- --source synthetic

Validate configuration separately. Unknown fields, invalid endpoints, inconsistent limits, and unknown module names fail before capture begins.

cargo run --locked -p e-navigator-cli -- --validate-config
cargo run --locked -p e-navigator-cli -- \
  --validate-config \
  --config documentation/examples/production-performance.toml

Production performance golden path

The lowest-risk route is a narrow, measurable base profile. No fixed configuration is universally fastest across kernels, workloads, traffic, and backends.

1. Verify and pin. Check the release manifest, checksums, Cosign signatures, SBOMs, image digest, and chart digest.
2. Scope capture first. Use a deny-by-default namespace and label allowlist. Exclude collectors, exporters, and E-Navigator itself.
3. Begin with cheap coverage. Enable exec, TCP lifecycle, one-minute host resources, attribution, resource and network metrics, topology, and security findings.
4. Keep expensive families off. Leave DNS payload capture, HTTP, WebSocket/gRPC-Web protocols, TLS uprobes, CPU profiling, and JSON stdout disabled until each has a consumer.
5. Export through bounded workers. Use Prometheus for health and native counters, plus only the OTLP families needed by the backend.
6. Measure matched conditions. Compare no agent, the base profile, and one added family at a time on the same node, workload, duration, and backend state.
7. Tune the bottleneck. Fix destination throughput and capture scope before increasing queues or cardinality limits.
8. Roll out with thresholds. Stop when application latency, node CPU, memory, source loss, export loss, or attribution freshness exceeds its baseline.

Render the base profile

helm template e-navigator charts/e-navigator \
  --namespace e-navigator-system \
  --set image.digest=sha256:<verified-image-digest> \
  --set-file config.toml=documentation/examples/production-performance.toml \
  --set prometheusHttp.enabled=true \
  --set health.enabled=true \
  --set service.enabled=true

Replace the example OTLP endpoint and capture selectors before rendering or installing. Inspect the ConfigMap, capabilities, RBAC, resource bounds, update strategy, and digest.

On a target matching the proven Linux 6.6 posture, add --values charts/e-navigator/values-reduced-privilege.yaml to remove SYS_ADMIN. The profile remains UID 0 and is not a rootless or universal-kernel claim.

Architecture

Runtime code is statically registered. Configuration selects known modules but never loads arbitrary plugins.

Sources

Observe bounded kernel events and host filesystem state.

Processors

Filter and attach context only when evidence exists.

Generators

Derive metrics, topology, spans, profiles, and findings.

Sinks

Export through bounded, failure-isolated surfaces.

Every observation is a versioned `SignalEnvelope`. Processing, per-generator output, total derivation breadth, derivation depth, export queues, retries, and shutdown are bounded. Pure synchronous generators use an immediate path, while the async trait remains available for streaming implementations.

One Kubernetes controller supplies Pod, Service, and EndpointSlice state to capture filtering and attribution. Metric, trace, and profile OTLP workers are independent, so one failed destination cannot block another family or the shared signal path.

Peer-flow metrics are derived only after endpoint attribution. Active W3C propagation is a separate, disabled-by-default plaintext HTTP/1 mutation boundary using cgroup SOCK_OPS and SK_MSG before TCP packetization; it is not a universal protocol or kernel claim.

Configuration model

The TOML file owns runtime behavior. Helm owns packaging, mounts, capabilities, resources, rollout, services, and probes. Keep those two layers consistent.

The [ebpf] section defaults to event_transport = "auto". A successful feature probe selects RingBuf; only a positive unsupported result selects the separately packaged perf-event object. Probe errors fail source startup. Ring capacity is explicitly bounded and every transport exposes native loss accounting.

The same section defaults to network_io_hook = "auto". It selects BTF-backed ksys_read/ksys_write fexit only after tracing-program, kernel-BTF, and target-function preflight. Positively unsupported kernels retain syscall tracepoints; indeterminate probe, verifier, load, and attach failures stop the source instead of silently weakening it.

generator.peer_flow_metrics exports bounded network.peer.flow.bytes series. The optional [http_source.context_propagation] surface requires inbound capture, a cgroup v2 root, a bounded plaintext port allowlist, and target-kernel qualification; chart defaults keep it disabled.

Operations

With the Prometheus HTTP sink and matching chart options enabled, use `/healthz` for liveness, `/readyz` for configured runtime readiness, and `/metrics` for native health and loss telemetry.

First ten minutes

• Confirm every Pod runs the verified digest.
• Confirm desired source-running and attachment state.
• Confirm the workload controller and Pod watch are fresh.
• Produce one known event for each enabled family.
• Confirm the intended sink and backend accept it.
• Confirm aggregate transport loss, perf loss, RingBuf reservation failures, send failures, queue drops, invalid records, and rejections stay at zero.
• Record CPU, resident memory, throughput, and latency against the no-agent baseline.

Failure isolation

The chart uses the `isolate` source policy, so one failed source does not stop healthy sources. This means process liveness alone cannot prove complete coverage. Alert on each required source, optional attachment, controller freshness, and export family.

Performance evidence

Local Criterion benchmarks catch parser, generator, filter, and formatting regressions. Runtime overhead requires matched live trials because kernel, workload, backend, and node contention dominate the real cost.

Do not collapse these tiers into one number. Record commands, versions, warmup, sample count, confidence intervals, workload, node, and cleanup state.

The July 21 homelab kernel-hook A/B is one such narrow result: BTF fexit measured 7.971% more scalar TCP read/write operations per second and 7.710% lower mean latency than syscall tracepoints, while remaining 7.045% below no-agent throughput and using about 13.4 MiB more summed two-pod RSS. It is not a mixed-workload or whole-stack overhead claim.

The July 22 full-stack campaign completed 33 isolated runs, but its comparison is invalidated. The Redis backend connection predated collector attachment, E-Navigator missed that family, and the aggregate signal gate did not detect the omission. A corrected workload and cumulative per-stage protocol floor are prepared, but no replacement CPU, RSS, allocation, throughput, or latency result is claimed yet.

Rust engineering

The workspace uses Rust 2024 and MSRV 1.96. Production code denies `unwrap`, `expect`, direct `panic`, `dbg`, `todo`, and `unimplemented`. Rustdoc warnings, broken links, and missing crate documentation fail the quality gate.

• Unsafe code is limited to host FFI and Aya raw-event boundaries.
• External input is bounded, validated, fixture-tested, and fuzzed at high-risk boundaries.
• Async channels, retries, response bodies, fanout, and shutdown are bounded.
• Optimizations start with a saved baseline and keep public contracts stable.
• Supply-chain policy runs cargo-deny, cargo-audit, and cargo-machete.

Proof and boundaries

E-Navigator separates implemented code, local tests, privileged runtime evidence, backend acceptance, and production readiness. A passing parser test cannot become a Kubernetes claim, and a healthy DaemonSet cannot become backend query proof.