Introduction

Event Forwarder is a small CLI that fetches events from a Service events API, such as Horizon or Stream, and emits each event to stdout as newline-delimited JSON (NDJSON). Logs and diagnostics are written to stderr, so stdout can be consumed safely by log collectors.

Event Forwarder data flow
Figure 1. Event Forwarder data flow

The intended use case is to let customers reuse their existing log scraping stack. Event Forwarder does not try to become a complete log pipeline. It only handles the Service-specific work:

  • authenticating to the events API;

  • paging through event search results;

  • retrying transient HTTP 429 and 5xx responses;

  • preserving each original event payload;

  • writing exactly one compact JSON document per stdout line;

  • persisting a cursor when a state file is configured.

This design makes the integration portable. Any collector that can execute a command, read a container log stream, or tail a file can ingest Event Forwarder output and then forward it to the customer’s SIEM, datalake, message bus, or log analytics platform.

State persistence is optional but recommended for scheduled or long-running collector integrations. When SERVICE_STATE_FILE or --state-file is set, the forwarder stores the newest emitted timestamp and the event IDs seen at that same timestamp. The file is updated after each event is successfully written to stdout, allowing the next run to resume without re-emitting events that were already forwarded.