eCapture Event Forwarding API

December 7, 2025 · View on GitHub

This document briefly explains how to receive events and runtime logs from eCapture as a client, and where to find the detailed protocol and demo code in this repository.

Notes:

  • Default listening address: ws://127.0.0.1:28257
  • The listening address can be modified via the --ecaptureq command-line argument, for example: --ecaptureq=ws://127.0.0.1:28257/
  • All interfaces are Protobuf

eCapture exposes three parameters related to log / event output:

  • --logaddr: output for eCapture runtime logs (text)
  • --eventaddr: output for captured events (text)
  • --ecaptureq: WebSocket + Protobuf(LogEntry) endpoint for streaming runtime logs and events (structured)

The repository already contains detailed protocol docs and a full demo client.
This file is intentionally concise and mainly serves as an index + behavior overview.

1. Output parameters and priority

1.1 --logaddr: runtime logs (text)

  • Purpose: specify where eCapture’s own runtime logs are written.
  • Supported targets:
    • File path (e.g. /var/log/ecapture.log)
    • tcp://host:port
    • ws://host:port/path or wss://host:port/path
  • Content: initialization info, module startup, configuration details, errors, etc.
    Format: plain text.

1.2 --eventaddr: captured events (text)

  • Purpose: specify where captured event logs are written.
  • Supported targets: similar to --logaddr (file / TCP / WebSocket), but output is text-formatted event logs.
  • Typical use cases:
    • Directly writing events into files, TCP streams, or an existing log pipeline;
    • When your downstream system prefers plain text logs and does not need protobuf parsing yet.

1.3 --ecaptureq: unified event forwarding (WebSocket + Protobuf)

  • Purpose: start a WebSocket server (eCaptureQ) and stream both runtime logs and captured events as structured LogEntry Protobuf messages.

  • Example:

    # Start eCaptureQ on localhost:28257
sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/

  • Characteristics:

    • Clients connect via WebSocket;
    • Each message is a binary Protobuf-encoded LogEntry;
    • The log_type field distinguishes heartbeat / process log / event.

1.4 Relationship between eventaddr and ecaptureq

Both parameters define “event output channels”:

  • --eventaddr: event logs in plain text format;
  • --ecaptureq: events + logs in Protobuf(LogEntry) format via WebSocket.

Priority:

  • If both --ecaptureq and --eventaddr are set, eCapture will prefer --ecaptureq for streaming events.
  • You can think of it as:
    • For structured, programmatically consumable event streams → use --ecaptureq;
    • For plain text log output → use --eventaddr.

If you want real-time, structured events via WebSocket + Protobuf, use --ecaptureq and refer to the existing protocol docs and demo client.

2.1 Protocol and message structure

Please read:

  • Protobuf definition:
    protobuf/proto/v1/ecaptureq.proto
  • Protocol overview:
    protobuf/PROTOCOLS.md

Together they define:

  • Top-level message LogEntry:

    message LogEntry {
  LogType log_type = 1;

  oneof payload {
    Event event_payload = 2;
    Heartbeat heartbeat_payload = 3;
    string run_log = 4;
  }
}

  • LogType enum:

    • LOG_TYPE_HEARTBEAT – heartbeat messages;
    • LOG_TYPE_PROCESS_LOG – eCapture runtime logs;
    • LOG_TYPE_EVENT – captured business events (e.g. TLS/HTTP data).

  • Event fields:

    • timestamp, uuid, src_ip, dst_ip, pid, pname, type, length, payload, etc.

  • Heartbeat fields:

    • timestamp, count, message.

PROTOCOLS.md provides detailed semantics for each field; use it as the main reference when integrating.

2.2 Official Go demo client

If you use Go, the easiest approach is to reuse the official demo:

  • Directory: examples/ecaptureq_client/
    • Code: examples/ecaptureq_client/main.go
    • Usage: examples/ecaptureq_client/README.md

The demo already implements:

  1. Connecting to the WebSocket server specified by --ecaptureq;
  2. Continuously reading binary messages;
  3. Decoding them into pb.LogEntry (under protobuf/gen/v1);
  4. Handling message types by LogType:
    • printing runtime logs;
    • displaying captured events in a human-friendly way (including payload text/hex/base64);
    • optionally showing heartbeats in verbose mode.

Quick start with the demo

# 1. Start eCapture with eCaptureQ enabled
sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/

# 2. Build the client
cd examples/ecaptureq_client
go build -o ecaptureq_client main.go

# 3. Connect and watch events
./ecaptureq_client -server ws://127.0.0.1:28257/
# or
./ecaptureq_client -server ws://192.168.1.100:28257/ -verbose

If you want to integrate this into your own system:

  • Copy the core receive + decode + dispatch logic from main.go;
  • Replace “print to terminal” with writing to your storage, message queue, or analytics engine.

2.3 Integrating from other languages

For other languages (Python / Java / Node.js / Rust / …), the pattern is:

  1. Use that language’s Protobuf tooling to generate types from
    protobuf/proto/v1/ecaptureq.proto.
  2. Use a WebSocket client library to connect to ws://HOST:PORT/
    (note: the URL must end with /).
  3. In a loop:
    • read a binary message from WebSocket;
    • decode it into LogEntry;
    • handle it based on log_type (heartbeat / process log / event).

You can first run examples/ecaptureq_client to observe real traffic and then mirror the same logic in your language of choice.

3. Using eventaddr / logaddr for plain text logs

If you don’t want to deal with Protobuf and just need plain text logs:

  • Use --logaddr for eCapture runtime logs;
  • Use --eventaddr for captured event logs (text).

Examples:

# Runtime logs to one file, event logs to another
./ecapture tls \
  --logaddr=/var/log/ecapture.log \
  --eventaddr=/var/log/ecapture-events.log

or:

# Send event logs via TCP to a remote service
./ecapture tls \
  --eventaddr=tcp://192.168.1.100:9000

In this mode, as a “client” you only need to:

  • Read from the configured file or TCP stream;
  • Parse lines (or whatever text format was chosen) as logs/events.

Reminder: If you set both --ecaptureq and --eventaddr, events will be streamed via --ecaptureq first (WebSocket + Protobuf).
eventaddr is mainly useful when you are not using eCaptureQ and just need text logs.

4. Summary

  • For structured, programmatic consumption of events:
    • Use --ecaptureq, and refer to:
      • protobuf/proto/v1/ecaptureq.proto
      • protobuf/PROTOCOLS.md
      • examples/ecaptureq_client/
  • For plain text logs:
    • Use --logaddr for runtime logs;
    • Use --eventaddr for event logs (no Protobuf).
  • When both are configured, --ecaptureq has the highest priority and is used first to forward events and logs over WebSocket + Protobuf.

This document stays minimal on purpose.
For full details, always refer to the protocol docs and the demo client in this repository.