Configuration

Event Forwarder can be configured with CLI flags or environment variables. CLI flags are convenient for direct testing; environment variables are usually easier for collectors, containers, and system services.

CLI flags
Environment variables

event-forwarder \
  --endpoint "https://service.example.com/api/v1/events/search" \
  --api-key "$SERVICE_API_KEY" \
  --state-file "/var/lib/event-forwarder/state.json"

export SERVICE_ENDPOINT="https://service.example.com/api/v1/events/search"
export SERVICE_API_KEY="replace-me"
export SERVICE_STATE_FILE="/var/lib/event-forwarder/state.json"

event-forwarder

Available options:

CLI flag Environment variable Default Description

CLI flag	Environment variable	Default	Description
`--endpoint`	`SERVICE_ENDPOINT`	Required	Service events search endpoint.
`--api-key`	`SERVICE_API_KEY`	Required	Service API key sent as the `X-API-KEY` header.
`--api-id`	`SERVICE_API_ID`	`admin`	Service API ID sent as the `X-API-ID` header.
`--user-agent`	`SERVICE_USER_AGENT`	`vector-event-forwarder/1.0`	HTTP `User-Agent` header.
`--page-size`	`SERVICE_PAGE_SIZE`	`50`	Number of events requested per page.
`--start-page`	`SERVICE_START_PAGE`	`1`	First API page index requested.
`--max-pages`	`SERVICE_MAX_PAGES`	`0`	Maximum pages to fetch in one run. `0` means unlimited.
`--timeout`	`SERVICE_TIMEOUT`	`30s`	HTTP request timeout.
`--state-file`	`SERVICE_STATE_FILE`	Empty	Cursor state path. Leave empty to disable durable state.
`--start-timestamp`	`SERVICE_START_TIMESTAMP`	Empty	Initial lower bound as RFC3339/RFC3339Nano or Unix milliseconds.
`--retries`	`SERVICE_RETRIES`	`2`	Retry count for HTTP 429 and 5xx responses.
`--retry-backoff`	`SERVICE_RETRY_BACKOFF`	`1s`	Base retry backoff. Retry attempt `n` waits `retry-backoff * n`.
`--tls-insecure-skip-verify`	`SERVICE_TLS_INSECURE_SKIP_VERIFY`	`false`	Disable TLS certificate verification. Use only in controlled test environments.
`--log-level`	`SERVICE_LOG_LEVEL`	`info`	`trace`, `debug`, `info`, `warn`, `error`, or `disabled`.
`--trace-file`, `--trace`	`SERVICE_TRACE_FILE`	Empty	Write OpenTelemetry diagnostic traces to the given OTLP JSON Lines file. Event bodies are included.
`--daemon`	`SERVICE_DAEMON`	`false`	Keep the process alive and poll periodically for new events. Requires a state file.
`--poll-interval`	`SERVICE_POLL_INTERVAL`	`10s`	Delay between daemon-mode fetch runs.
`--version`, `-v`	-	-	Print binary and Go versions.

--endpoint

SERVICE_ENDPOINT

Required

Service events search endpoint.

--api-key

SERVICE_API_KEY

Required

Service API key sent as the X-API-KEY header.

--api-id

SERVICE_API_ID

admin

Service API ID sent as the X-API-ID header.

--user-agent

SERVICE_USER_AGENT

vector-event-forwarder/1.0

HTTP User-Agent header.

--page-size

SERVICE_PAGE_SIZE

50

Number of events requested per page.

--start-page

SERVICE_START_PAGE

1

First API page index requested.

--max-pages

SERVICE_MAX_PAGES

0

Maximum pages to fetch in one run. 0 means unlimited.

--timeout

SERVICE_TIMEOUT

30s

HTTP request timeout.

--state-file

SERVICE_STATE_FILE

Empty

Cursor state path. Leave empty to disable durable state.

--start-timestamp

SERVICE_START_TIMESTAMP

Empty

Initial lower bound as RFC3339/RFC3339Nano or Unix milliseconds.

--retries

SERVICE_RETRIES

2

Retry count for HTTP 429 and 5xx responses.

--retry-backoff

SERVICE_RETRY_BACKOFF

1s

Base retry backoff. Retry attempt n waits retry-backoff * n.

--tls-insecure-skip-verify

SERVICE_TLS_INSECURE_SKIP_VERIFY

false

Disable TLS certificate verification. Use only in controlled test environments.

--log-level

SERVICE_LOG_LEVEL

info

trace, debug, info, warn, error, or disabled.

--trace-file, --trace

SERVICE_TRACE_FILE

Empty

Write OpenTelemetry diagnostic traces to the given OTLP JSON Lines file. Event bodies are included.

--daemon

SERVICE_DAEMON

false

Keep the process alive and poll periodically for new events. Requires a state file.

--poll-interval

SERVICE_POLL_INTERVAL

10s

Delay between daemon-mode fetch runs.

--version, -v

Print binary and Go versions.

Show the generated CLI help:

event-forwarder --help

State file
Daemon mode

When state persistence is enabled, the state file contains:

{
  "last_timestamp_ms": 1782209730123,
  "event_ids_at_last_timestamp": ["event-a", "event-b"]
}

Use a persistent directory for this file. For containers, mount a volume. For collectors running as system services, store it under a writable data directory such as /var/lib/event-forwarder/state.json.

If no state file is configured, each run starts from --start-timestamp when it is set, otherwise from --start-page.

Use --daemon when the forwarder should stay alive and poll for new events itself instead of being restarted by a scheduler or collector:

event-forwarder \
  --endpoint "https://service.example.com/api/v1/events/search" \
  --api-key "$SERVICE_API_KEY" \
  --state-file "/var/lib/event-forwarder/state.json" \
  --daemon \
  --poll-interval 10s

Daemon mode runs one fetch immediately, then waits for --poll-interval before the next fetch. It keeps running until the process receives SIGINT/SIGTERM or the parent process stops it. Before each wait, the daemon logs the next scheduled poll time to stderr.

A state file is required in daemon mode. Without a cursor, the process would have no durable record of the last emitted event and could re-emit old events on each poll.