Hound is a full-stack network observability system for containerized Linux workloads. Its long-term goal is to correlate L7 transactions, L4 socket endpoints, L3/L2 network flows, processes, and container identities in one coherent data model.

The project is currently building its first vertical slice after an architecture reset: the ARM64 BTF/CO-RE runtime and the tcp_lifecycle sensor. It is not yet a complete L7 observability product.

Current capabilities

• Linux ARM64, BTF, CO-RE, and ring buffer transport;
• active TCP connect outcomes, bounded error reasons, and connect duration;
• client and server endpoint establishment and close facts;
• endpoint payload byte totals, lifetime, and retransmission events;
• raw process, network namespace, and cgroup identities enriched into bounded container identities;
• bounded (process, fd) → endpoint associations with fd-reuse validation data;
• live TCP socket I/O bytes, calls, and errors without payload copying;
• capability reporting and collection-path integrity metrics;
• Rust unit tests, strict Clippy checks, and real ARM64/BTF kernel e2e tests.

An endpoint_id identifies one local socket instance for the lifetime of a loaded BPF object. It is not a cluster-wide connection ID and is not shared by the client and server endpoints.

Architecture

Kernel sensors                       Hound agent
────────────────────────────────────────────────────────────
tcp_lifecycle ─┐                 ┌─ telemetry/schema
traffic       ─┼─ ring buffer ──►├─ identity + correlation
socket_io     ─┤                 ├─ sensor dispatch
tls / l7      ─┘                 └─ aggregation + export

bpf/hound.bpf.c                Single-object kernel composition root
bpf/common/                     Shared maps and endpoint operations
bpf/sensors/tcp_lifecycle/     TCP lifecycle kernel sensor
bpf/sensors/socket_fd/         Process-local fd association sensor
bpf/sensors/socket_io/         Low-overhead cumulative socket I/O sensor
agent/src/kernel/              BPF loader and capability reporting
agent/src/telemetry/           Schema decoding and transport integrity
agent/src/identity/            Process/cgroup/container identity resolution
agent/src/sensors/             User-space sensor aggregation
agent/src/export/              Prometheus storage and HTTP export

The kernel keeps endpoint lifecycle state, process-local file descriptor bindings, and cumulative socket I/O counters separate. The component sources are compiled into one hound.bpf.o, so sensors share maps without pinned-map lifecycle coupling. Socket I/O uses BTF tracing to aggregate actual tcp_sendmsg and tcp_recvmsg return values by endpoint_id; it does not copy payload. Future L7 sensors can use the same correlation boundary without turning the metrics path into a high-frequency event stream.

Validation

cargo test --manifest-path agent/Cargo.toml
cargo clippy --manifest-path agent/Cargo.toml --all-targets -- -D warnings
./scripts/e2e-container.sh 14

On macOS, Docker Desktop only provides orchestration. The kernel under test is the ARM64 Linux VM kernel used by Docker Desktop; changing the Ubuntu container image does not change that kernel.

Implementation references

Hound studies established open-source systems without copying their internal architecture wholesale. In particular, DeepFlow keeps stable socket facts in its eBPF event, enriches process and container metadata in user space through a process cache with a procfs fallback, and performs Pod lookup after that boundary. Hound follows the same separation of concerns while keeping container ID strings out of the kernel ABI.

• DeepFlow socket event contract
• DeepFlow user-space process cache and procfs fallback
• DeepFlow process and container metadata extraction