Built-in Scenarios¶

Sonda ships with 11 curated scenario patterns you can discover, inspect, and run without writing any YAML. Scenario YAML files live on the filesystem and are loaded at runtime through a configurable search path.

Scenario search path¶

Sonda discovers scenario YAML files from the filesystem via a search path:

--scenario-path <dir> CLI flag -- when present, only this directory is searched.
SONDA_SCENARIO_PATH env var -- colon-separated list of directories.
./scenarios/ relative to the current working directory.
~/.sonda/scenarios/ in the user's home directory.

Non-existent directories are silently skipped. If the same scenario name appears in multiple directories, the first match wins (highest-priority path).

When running from the repo root, the included scenarios/ directory is found automatically. For Docker, the SONDA_SCENARIO_PATH env var is set to /scenarios in the image.

Browse the catalog¶

List every built-in scenario with sonda scenarios list:

sonda scenarios list

Output

NAME                         CATEGORY           SIGNAL       DESCRIPTION
cpu-spike                    infrastructure     metrics      Periodic CPU usage spikes above threshold
memory-leak                  infrastructure     metrics      Monotonically growing memory usage (sawtooth)
disk-fill                    infrastructure     metrics      Constant-rate disk consumption (step counter)
interface-flap               network            multi        Network interface toggling up/down with traffic shifts
latency-degradation          application        metrics      Growing response latency with jitter (sawtooth)
error-rate-spike             application        metrics      Periodic HTTP error rate bursts
cardinality-explosion        observability      metrics      Pod label cardinality explosion with spike windows
log-storm                    application        logs         Error-level log burst with template generation
steady-state                 infrastructure     metrics      Normal oscillating baseline (sine + jitter)
network-link-failure         network            multi        Link down with traffic shift to backup path
histogram-latency            application        histogram    Request latency histogram (normal distribution)
11 scenarios

Filter by category to narrow the list:

sonda scenarios list --category network

Output

NAME                         CATEGORY           SIGNAL       DESCRIPTION
interface-flap               network            multi        Network interface toggling up/down with traffic shifts
network-link-failure         network            multi        Link down with traffic shift to backup path
2 scenarios in category "network"

Available categories: infrastructure, network, application, observability.

For machine-readable output, add --json to get a JSON array:

sonda scenarios list --json

Run a scenario¶

Pick any scenario and run it directly:

sonda scenarios run cpu-spike

Output

▶ node_cpu_usage_percent  signal_type: metrics | rate: 1/s | encoder: prometheus_text | sink: stdout | duration: 60s
node_cpu_usage_percent{cpu="0",instance="web-01",job="node_exporter"} 95 1775589686141
node_cpu_usage_percent{cpu="0",instance="web-01",job="node_exporter"} 95 1775589687146
...
■ node_cpu_usage_percent  completed in 60.0s | events: 61 | bytes: 5307 B | errors: 0

Override duration, rate, encoder, or sink without editing any YAML:

sonda scenarios run cpu-spike --duration 10s --rate 5

sonda scenarios run cpu-spike --sink http_push --endpoint http://localhost:9090/api/v1/write

Override	Description
`--duration <d>`	Shorten or extend the run (e.g. `10s`, `2m`)
`--rate <r>`	Change events per second
`--encoder <enc>`	Switch output format (e.g. `influx_lp`, `json_lines`)
`--sink <type>`	Redirect output to a sink (e.g. `http_push`, `remote_write`)
`--endpoint <url>`	Set the sink endpoint (required for network sinks)

Tip

Use --dry-run to validate what a scenario would do without emitting any data:

sonda --dry-run scenarios run cpu-spike

Inspect the YAML¶

Every built-in scenario is a standard YAML file on disk. View it with sonda scenarios show:

sonda scenarios show cpu-spike

Output

# CPU spike: periodic CPU usage spikes above threshold.
#
# Models a server experiencing recurring CPU spikes using the
# `spike_event` alias. Useful for testing alert rules that trigger
# on sustained high CPU usage.
#
# Pattern: baseline ~35% with periodic spikes to ~95%.

scenario_name: cpu-spike
category: infrastructure
signal_type: metrics
description: "Periodic CPU usage spikes above threshold"

name: node_cpu_usage_percent
rate: 1
duration: 60s

generator:
  type: spike_event
  baseline: 35.0
  spike_height: 60.0
  spike_duration: "10s"
  spike_interval: "30s"

labels:
  instance: web-01
  job: node_exporter
  cpu: "0"

encoder:
  type: prometheus_text

sink:
  type: stdout

Customize a built-in¶

Built-in scenarios are a starting point. To customize one beyond what the --duration / --rate overrides offer, save the YAML to a file and edit it:

sonda scenarios show cpu-spike > my-cpu-spike.yaml
# Edit my-cpu-spike.yaml to change labels, generator params, etc.
sonda metrics --scenario my-cpu-spike.yaml

This workflow lets you use built-in patterns as templates without starting YAML from scratch.

The @name shorthand¶

Every subcommand that accepts --scenario also supports a @name shorthand. Instead of pointing to a file on disk, prefix the scenario name with @ to load a built-in:

metricslogshistogramrun

sonda metrics --scenario @cpu-spike --duration 10s

sonda logs --scenario @log-storm --duration 10s

sonda histogram --scenario @histogram-latency

sonda run --scenario @interface-flap

The @name shorthand works exactly like a file path -- CLI flags still override values in the scenario YAML. For example, --duration 10s overrides whatever duration the built-in defines.

Info

The @name shorthand is an alternative to sonda scenarios run. Both resolve the same scenario YAML from the search path. Use scenarios run when you want purpose-built override flags (--sink, --encoder, --endpoint). Use @name when you want the full set of flags available on metrics, logs, or histogram.

Scenario catalog¶

Infrastructure¶

Name	Signal	Generator	What it models
`cpu-spike`	metrics	`spike_event`	Server CPU surging from ~35% baseline to ~95% for 10s every 30s. Tests threshold alerts.
`memory-leak`	metrics	`leak`	Memory ramping from 40% to 95% over 120s (linear growth). Tests growth-rate alerts.
`disk-fill`	metrics	`step`	Disk usage climbing in fixed increments. Tests capacity alerts.
`steady-state`	metrics	`steady`	Normal oscillating baseline (~75% +/- 10) with noise. Use as a healthy control signal.

Network¶

Name	Signal	Generator	What it models
`interface-flap`	multi	sequence	Router interface toggling up/down with matching traffic counters and error spikes. 3 correlated metrics.
`network-link-failure`	multi	sequence	Primary link going down with traffic shifting to a backup path. Multi-metric correlation.

Application¶

Name	Signal	Generator	What it models
`latency-degradation`	metrics	`degradation`	HTTP response latency growing over time with noise. Tests latency SLO alerts.
`error-rate-spike`	metrics	`spike`	Periodic bursts of HTTP 5xx errors. Tests error-rate alerts.
`log-storm`	logs	template	Error-heavy log burst (60% error, 30% warn) with 10x volume spikes. Tests log pipeline backpressure.
`histogram-latency`	histogram	normal distribution	Request latency histogram (mean 100ms, stddev 30ms). Tests p99 SLO alerting and heatmap panels.

Observability¶

Name	Signal	Generator	What it models
`cardinality-explosion`	metrics	sine + cardinality spike	500 unique pod labels injected for 20s every 60s. Tests TSDB cardinality limits.

Custom scenarios¶

You can add your own scenario YAML files to any directory on the search path. For example, create ~/.sonda/scenarios/my-scenario.yaml and it will be discovered automatically:

sonda scenarios list                        # shows your custom scenario
sonda scenarios run my-scenario             # run it by name
sonda metrics --scenario @my-scenario       # @name shorthand works too

Or use --scenario-path to point to a custom directory:

sonda --scenario-path ./my-scenarios scenarios list

Custom scenario files use the same YAML format as any scenario file. The only addition is metadata fields at the top for catalog display:

~/.sonda/scenarios/my-scenario.yaml

scenario_name: my-scenario
category: application
signal_type: metrics
description: "My custom scenario pattern"

name: my_metric
rate: 1
duration: 30s
generator:
  type: sine
  amplitude: 50.0
  period_secs: 60
  offset: 50.0
encoder:
  type: prometheus_text
sink:
  type: stdout

Field	Required	Description
`scenario_name`	yes	Kebab-case identifier used with `scenarios run` and `@name`
`category`	yes	Grouping for `--category` filter
`signal_type`	yes	Signal type: `metrics`, `logs`, `histogram`, `multi`
`description`	yes	One-line description shown in `scenarios list`

What next¶

Metric Packs -- pre-built metric bundles for Telegraf SNMP and node_exporter with correct schemas
Alert Testing -- end-to-end walkthrough using shaped signals to validate alert rules
CLI Reference -- full flag reference for all scenarios subcommands
Scenario Files -- YAML reference for writing your own scenarios from scratch