Project structure

Eventum has two levels of configuration: the application level (for eventum run) and the generator level (for both eventum run and eventum generate). Understanding the structure makes it easier to navigate the config pages that follow.

Application level

When running Eventum as a full application with eventum run, the project root contains two config files and a directory of generators:

How the files relate

eventum.yml points to startup.yml and to the generators directory:

path:
  startup: /opt/eventum/startup.yml
  generators_dir: /opt/eventum/generators
  logs: /opt/eventum/logs
  keyring_cryptfile: /opt/eventum/cryptfile.cfg

All path.* values must be absolute paths.

startup.yml lists which generators to start and can override any generation parameter from eventum.yml on a per-generator basis:

- id: access-logs
  path: access-logs/generator.yml   # relative to generators_dir
  autostart: true
  timezone: America/New_York

- id: error-logs
  path: error-logs/generator.yml
  live_mode: false                  # override: run in sample mode
  batch:
    size: 50000                     # override: larger batches

Parameters cascade: eventum.yml sets the defaults → startup.yml overrides per generator. Any field not specified in startup.yml inherits from eventum.yml.

Generator level

A generator is a self-contained directory with a config file and its supporting resources:

Only generator.yml is required. The other directories depend on which plugins you use:

generator.yml

The generator config defines the three-stage pipeline — input, event, and output:

input:
  - cron:
      expression: "* * * * * *"
      count: 1

event:
  template:
    mode: all
    templates:
      - access_log:
          template: templates/access.jinja

output:
  - stdout: {}
  - file:
      path: output/events.log

See the generator.yml reference for the full schema.

Path resolution

All relative paths inside generator.yml are resolved from the directory containing the config file, not from the working directory. This means a generator directory is fully portable — you can move it anywhere and it works as long as its internal structure is intact.

For example, if generator.yml is at /opt/eventum/generators/access-logs/generator.yml, then templates/access.jinja resolves to /opt/eventum/generators/access-logs/templates/access.jinja.

Single-generator mode

When using eventum generate, you don't need eventum.yml or startup.yml — just a generator directory with its config:

eventum generate --id my-gen --path my-generator/generator.yml ...

All execution parameters (timezone, batch size, live mode, etc.) are passed as CLI flags instead of being defined in startup.yml. See the eventum generate reference for all available flags.

What's next