Integration and Deployment ​

This page provides a high-level overview of how to integrate eCapture into production environments and manage its lifecycle. It covers mechanisms for remote event streaming, dynamic configuration updates, output management, and performance considerations.

Remote Event Streaming (eCaptureQ) ​

For large-scale deployments, eCapture provides a WebSocket-based streaming service called eCaptureQ. This allows users to centralize traffic capture from multiple nodes into a single processing backend.

The system uses a Protobuf-based messaging protocol defined in protobuf/gen/v1 pkg/ecaptureq/server.go:23. The server maintains a 128-message history buffer (LogBuffLen) pkg/ecaptureq/server.go:29 to ensure that new clients receive recent context upon connection.

For details, see Remote Event Streaming (eCaptureQ WebSocket).

eCaptureQ Data Flow ​

The following diagram illustrates how events move from the eBPF kernel space through the eCaptureQ server to remote clients.

Diagram: eCaptureQ Streaming Architecture

Sources: pkg/ecaptureq/server.go:31-57, cli/cmd/ecaptureq.go:30-36, examples/ecaptureq_client/main.go:44-58

Remote Dynamic Configuration API ​

eCapture supports hot-reloading certain configurations without restarting the process. This is achieved via a built-in HTTP server (disabled by default as of v2.3.0 CHANGELOG.md:6). When enabled via the --listen flag, it exposes endpoints for various probes (e.g., /tls, /gotls, /bash).

This API allows SREs to:

• Change capture filters (PID, UID).
• Update target library paths (--libssl or --elfpath).
• Toggle output modes (text vs. pcapng).

For details, see Remote Dynamic Configuration API.

Logging and Output Configuration ​

eCapture provides flexible output routing through its internal/output module. It can simultaneously write to multiple destinations using adapters like IOWriterAdapter internal/output/writers/iowriter_adapter.go:22.

Key capabilities include:

• Log Forwarding: Sending operational logs to a remote TCP address via --logaddr.
• Event Forwarding: Streaming captured data to a remote address via --eventaddr.
• Rotation: Integrated log rotation to prevent disk exhaustion in production.
• Format Selection: Choosing between human-readable text, structured JSON, or binary PCAPNG/Keylog formats.

For details, see Logging and Output Configuration.

Performance Overhead and Benchmarks ​

Running eBPF uprobes introduces a small latency (typically 1-2 microseconds) per function call entry/exit. In high-throughput environments, such as a busy Nginx load balancer, this overhead can accumulate.

eCapture provides tuning parameters to mitigate impact:

• Buffer Selection: Choosing between perf_buffer and ring_buffer based on kernel support and throughput requirements.
• Sampling: Filtering by PID or CGroup to limit the scope of capture CHANGELOG.md:20.
• Batching: Using buffered writers like the pcapng packet writer CHANGELOG.md:117.

For details, see Performance Overhead and Benchmarks.

Performance and Logic Entities ​

The following diagram maps performance-sensitive components to their code implementations.

Diagram: Performance Impact Mapping

Sources: README.md:114-118, internal/output/writers/iowriter_adapter.go:22-38, CHANGELOG.md:100-107

Integration Summary Table ​

Sources: README.md:114-123, cli/cmd/ecaptureq.go:21-36, internal/output/writers/iowriter_adapter.go:22-33