eventum.yml

The main application config controls how Eventum runs as a service with eventum run. It defines four sections: server settings, file paths, logging, and default generation parameters that all generators inherit.

server:
  host: "0.0.0.0"
  port: 9474

path:
  startup: /etc/eventum/startup.yml
  generators_dir: /etc/eventum/generators
  logs: /var/log/eventum
  keyring_cryptfile: /etc/eventum/cryptfile.cfg

log:
  level: info
  format: plain

generation:
  timezone: UTC
  batch:
    size: 10000

Extra fields are forbidden — any unrecognized key will cause a validation error at load time.

server

Controls the built-in web server that exposes the UI and REST API.

server.ssl

TLS/SSL settings for the server.

All SSL paths must be absolute.

server:
  ssl:
    enabled: true
    cert: /etc/eventum/server.crt
    cert_key: /etc/eventum/server.key
    verify_mode: optional
    ca_cert: /etc/eventum/ca.crt

server.auth

HTTP basic authentication credentials for the UI and API.

server.mcp

Mounts the MCP server into the running server so an AI agent can build, validate, preview, and manage generators over HTTP. Disabled by default. The endpoint is served at <host>:<port><path> and protected by the server.auth credentials.

server:
  mcp:
    enabled: true
    allow_write: false
    path: /mcp
    allowed_hosts: []

path

File system paths used by the application. All paths must be absolute.

path:
  startup: /etc/eventum/startup.yml
  generators_dir: /etc/eventum/generators
  logs: /var/log/eventum
  keyring_cryptfile: /etc/eventum/cryptfile.cfg
  generator_config_filename: generator.yml

log

Controls application logging — separate from the events that generators produce.

log:
  level: info
  third_party_level: warning
  format: json
  max_bytes: 52428800    # 50 MiB
  backups: 10

Log files

Each message goes to one file in path.logs, named after the part of the application it came from. Standard output receives all of them, so docker logs stays the combined view.

With log.format: json the same files carry the .json extension instead.

generation

Default generation parameters inherited by all generators. Individual generators can override any of these in startup.yml.

generation.batch

Controls how events are grouped before being passed to output plugins:

*The defaults of 10000 and 1.0 apply as a pair when neither field is specified. If you set only one, the other defaults to null. At least one of size or delay must be set.

size is the primary limit. delay bounds the lag batching adds to delivery in live mode, so it forms the batches of timestamps that are still ahead of real time; timestamps that have already passed, and every timestamp in sample mode, are grouped by size. With no size set, delay is the only limit on how large a batch grows and therefore always applies — see Batching for the full breakdown.

generation.queue

Controls the internal queues between pipeline stages. These act as backpressure buffers — when a downstream stage is slower, the upstream stage will block once the queue is full.

A batch is as large as the events in it, so the number of batches alone does not bound how much the queue holds: ten batches of ten thousand events come to twenty megabytes with small events and half a gigabyte with large ones. Both limits of the events queue apply, whichever is reached first, so max_event_bytes keeps that figure predictable no matter what the templates render. A single batch larger than the whole limit still passes through — holding it back would stall the pipeline — so keep batch.size in proportion to the size of an event.

What a generator occupies while it produces and writes a batch is a separate figure, and it follows batch.size — see how much memory a generator holds.

The memory each queue currently holds is reported on the instance page next to the batches it holds.

Concurrency and ordering

generation:
  timezone: America/New_York
  batch:
    size: 20000
    delay: 2.0
  queue:
    max_timestamp_batches: 20
    max_event_batches: 20
    max_event_bytes: 536870912
  keep_order: false
  max_concurrency: 200
  write_timeout: 30

Complete example

# Server
server:
  ui:
    enabled: true
  api:
    enabled: true
  host: "0.0.0.0"
  port: 9474
  ssl:
    enabled: true
    cert: /etc/eventum/server.crt
    cert_key: /etc/eventum/server.key
    verify_mode: none
  auth:
    user: admin
    password: s3cret

# Paths
path:
  startup: /etc/eventum/startup.yml
  generators_dir: /etc/eventum/generators
  logs: /var/log/eventum
  keyring_cryptfile: /etc/eventum/cryptfile.cfg

# Logging
log:
  level: info
  format: json
  max_bytes: 52428800
  backups: 10

# Default generation parameters
generation:
  timezone: UTC
  batch:
    size: 10000
    delay: 1.0
  queue:
    max_timestamp_batches: 10
    max_event_batches: 10
    max_event_bytes: 268435456
  keep_order: false
  max_concurrency: 100
  write_timeout: 10

What's next