Scenarios

A scenario is the core building block in Tracemill. It defines a stateful sequence of event emissions — a single "story" of activity, like a brute-force attack or a user login session.

Structure

A scenario YAML file has three main sections:

type: scenario
state:
  source_ip: gen.ipv4()
  user_id: gen.uuid()
steps:
  - emit:
      type: "console-login@1.0"
      fields:
        src_ip: ref.source_ip
        user: ref.user_id
        outcome: "failure"
  - emit:
      type: "console-login@1.0"
      fields:
        src_ip: ref.source_ip
        user: ref.user_id
        outcome: "success"

State

The state block declares variables resolved once per scenario run. Variables can reference generators (gen.*) or literal values. They are resolved in topological order — a variable can reference another variable declared in the same block via ref.*.

Steps

Each step emits an event of a given type. The fields block maps field names to values — literals, generator calls, or references to state variables.

Event Types

Event types (e.g., console-login@1.0) are defined separately and provide a schema with default values. Scenario fields override event type defaults. A timestamp field is stamped automatically from the runner's clock.