Plugins

Everything a generator does — scheduling timestamps, producing events, writing output — is handled by plugins. A plugin is a self-contained component that implements one stage of the pipeline. You pick a plugin by name, configure it in YAML, and Eventum takes care of the rest.

Plugin types

Plugins are grouped into three types, one per pipeline stage:

Each type has its own set of available plugins. You can mix and match within a type (e.g. two input plugins feeding the same generator), but you cannot use a plugin outside its type.

Input plugins

Input plugins produce timestamps using different scheduling strategies — cron expressions, fixed intervals, evenly spaced ranges, statistical distributions, and more. A generator can combine multiple input plugins; their timestamps are merged into a single chronological stream before reaching the event stage.

Event plugins

Event plugins turn timestamps into event strings. The primary plugin renders Jinja2 templates; alternatives include running a Python function or replaying events from an existing log file. A generator has exactly one event plugin.

Output plugins

Output plugins write events to a destination — the console, a local file, an HTTP endpoint, or a database. A generator can have multiple output plugins; every event is delivered to all of them.

For the full list of available plugins and their parameters, see the Plugins reference.

Configuration

Each plugin is configured as a named key inside the corresponding pipeline section. The key is the plugin name; the value is an object with plugin-specific settings:

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

event:
  template:
    mode: all
    templates:
      - my_event:
          template: templates/event.jinja

output:
  - stdout: {}

A few rules:

• input and output are lists — each item is a single-key object naming the plugin.
• event is a single object — one plugin name with its config.
• Plugin-specific fields are validated at startup. An unknown field or a wrong type causes a clear error before any events are generated.
• Relative file paths (e.g. templates/event.jinja) are resolved from the directory containing the generator config file.

Empty configs

Some plugins require no settings. Use an empty object:

output:
  - stdout: {}

Common properties

While each plugin has its own settings, some properties are shared across all plugins of a type.

Tags (input plugins)

Any input plugin can attach tags — arbitrary string labels — to its timestamps. Tags are carried through the pipeline and are available inside the event plugin (as the tags variable in templates or the tags field in script params). This lets a single event plugin produce different output depending on which input triggered it:

input:
  - cron:
      expression: "*/5 * * * * *"
      count: 1
      tags: [heartbeat]
  - cron:
      expression: "0 * * * * *"
      count: 1
      tags: [minutely]

Formatter (output plugins)

Every output plugin has a formatter that controls how event strings are shaped before writing. The formatter is configured with the formatter field:

output:
  - file:
      path: output/events.log
      formatter:
        format: json

For the full list of formats and parameters, see the Formatters reference.

Lifecycle

Plugins go through a predictable lifecycle managed by the generator:

1. Configuration — The YAML is parsed and validated against the plugin's schema. Invalid config produces an error before anything runs.

2. Instantiation — A plugin instance is created with the validated config. Each plugin receives a sequential ID (useful for logging) and a unique GUID.

3. Execution — The generator calls the plugin's core method repeatedly:

   • Input: generate — yields batches of timestamps
   • Event: produce — turns a timestamp (and tags) into event strings
   • Output: open → write (repeated) → close

4. Shutdown — Output plugins are closed gracefully (flushing buffers, closing connections). Input and event plugins require no explicit cleanup.

Output plugins follow an async lifecycle — open, write, and close are asynchronous, which allows concurrent writes to multiple destinations without blocking. Input and event plugins run synchronously.

Error handling

Eventum tracks errors at the plugin level without crashing the pipeline:

• If an event plugin fails to produce for a given timestamp, the failure is counted, logged and the pipeline moves on to the next timestamp.
• If an output plugin fails to write a batch, the failure is counted and logged. Other output plugins in the same generator are not affected.
• If a formatter cannot format an event, the event is skipped for that output. The failure count is tracked separately from write failures.

Error counts are exposed through the REST API and Studio, so you can monitor plugin health at runtime.

Choosing a plugin

The Plugins reference lists every available plugin with its parameters. As a rule of thumb:

• Input — use cron or timer for repeating schedules, linspace for evenly spaced ranges, time_patterns for realistic traffic shapes, or http for on-demand triggers.
• Event — template covers the vast majority of use cases. Reach for script only when you need full programmatic control, and replay to reprocess existing logs.
• Output — pick the plugin that matches your destination. You can combine multiple outputs to write to several destinations at once.

What's next