Skip to content

Example scenarios

The examples/ directory contains ready-to-run YAML scenario files. Every generator, encoder, and sink combination is covered. Each file works as-is with the sonda CLI.

sonda run examples/basic-metrics.yaml

Basic metrics

File Generator Encoder Sink Description
basic-metrics.yaml sine prometheus_text stdout 1000 evt/s sine wave with labels and a recurring gap
simple-constant.yaml constant prometheus_text stdout Minimal up=1 metric at 10 evt/s for 10 seconds
step-counter.yaml step prometheus_text stdout Monotonic counter that wraps around at 1000
jitter-sine.yaml sine + jitter prometheus_text stdout Sine wave with deterministic jitter noise

Sink types

File Generator Encoder Sink Description
tcp-sink.yaml sine prometheus_text tcp Stream to a TCP listener (nc -l 9999)
udp-sink.yaml constant json_lines udp Send UDP datagrams to port 9998
file-sink.yaml sawtooth influx_lp file Write to /tmp/sonda-output.txt
http-push-sink.yaml sine prometheus_text http_push POST batches to an HTTP endpoint
http-push-retry.yaml sine prometheus_text http_push HTTP push with exponential-backoff retry on 5xx, 429, and connect failures
kafka-sink.yaml constant prometheus_text kafka Publish to a local Kafka broker
kafka-tls.yaml constant prometheus_text kafka Publish to a TLS-secured Kafka broker with SASL PLAIN auth

See Sinks for configuration details on each sink type.

OTLP / OpenTelemetry

File Signal Encoder Sink Description
otlp-metrics.yaml metrics otlp otlp_grpc Push sine wave metrics to an OTel Collector over gRPC
otlp-logs.yaml logs otlp otlp_grpc Push template logs to an OTel Collector over gRPC

Not included in the pre-built binaries

OTLP is an optional feature. The release binaries and the published Docker image do not include it. Two ways to get it:

  • As a binary — build from source: cargo build --features otlp -p sonda.
  • As a container — build the image yourself with OTLP compiled in. See Building the image.

Both scenarios above run unchanged once you have a build that includes OTLP. See Encoders — otlp for the encoder reference.

gNMI target

File Generator Encoder Sink Description
gnmi-telegraf.yaml step + flap gnmi gnmi_target Router with four interfaces on 0.0.0.0:57400: counters and oper-status for Telegraf's inputs.gnmi

Telegraf is the client here. Start it with the Compose stack's gnmi profile, which uses examples/telegraf/telegraf.conf, then run the scenario on your host:

docker compose -f examples/docker-compose-victoriametrics.yml --profile gnmi up -d
sonda run examples/gnmi-telegraf.yaml

See Sinks — gnmi_target for what the target serves and Encoders — gnmi for the path templates.

Encoding formats

File Generator Encoder Sink Description
influx-file.yaml sawtooth influx_lp file InfluxDB line protocol written to a file
json-tcp.yaml sine json_lines tcp JSON Lines over TCP
prometheus-http-push.yaml sine prometheus_text http_push Prometheus text POSTed in batches
precision-formatting.yaml sine prom/json/influx stdout Demonstrates the precision field with 3 encoders
remote-write-vm.yaml sine remote_write remote_write Protobuf remote write to VictoriaMetrics*
multi-format-test.yaml constant influx_lp file InfluxDB line protocol for pipeline validation

*The remote_write encoder is included in the release binaries and the published Docker image. When you build from source, add --features remote-write. See Encoders — remote_write for details.

Scheduling

File Generator Encoder Sink Description
burst-metrics.yaml sine prometheus_text stdout Bursts to 5x the rate for 2s every 10s
cardinality-spike.yaml sine prometheus_text stdout Injects 100 unique pod_name labels for 5s every 10s
long-running-metrics.yaml sine prometheus_text stdout No duration — runs until stopped (pair with sonda-server POST/DELETE)

Histograms and summaries

File Signal Encoder Sink Description
histogram.yaml histogram prometheus_text stdout Exponential distribution, 100 observations per tick (latency-style histogram)
summary.yaml summary prometheus_text stdout Normal distribution (mean 0.1, stddev 0.02), 100 observations per tick

Run them with sonda run. Histograms and summaries are signal_type: variants in the scenario YAML:

sonda run examples/histogram.yaml
sonda run examples/summary.yaml

See Generators for distribution options.

Metric packs

File Pack Encoder Sink Description
pack-scenario.yaml telegraf_snmp_interface prometheus_text stdout Expand a pack into per-metric scenarios with user-supplied labels
pack-with-overrides.yaml telegraf_snmp_interface prometheus_text stdout Override one metric's generator (ifOperStatus -> flap) without editing the pack
gnmi-pack.yaml openconfig_interface gnmi gnmi_target Two interfaces served as a gNMI target, every metric at the path and value type the pack's hints give it
snmp-telegraf.yaml telegraf_snmp_interface snmp snmp_agent Router with four interfaces on 0.0.0.0:1161 for Telegraf's inputs.snmp, every interface metric at the OID and SNMP type the pack's hints give it, beside an Opaque float, an Opaque double, an IpAddress and an enum string
if-mib-switch.yaml if_mib snmp snmp_agent 24-port access switch on 0.0.0.0:1163: every port's ifTable and ifXTable columns, ifIndex and ifType served as INTEGERs, two ports flapping half a cycle apart, and ifNumber
snmp-traps.yaml telegraf_snmp_interface snmp snmp_trap One router interface whose ifOperStatus flaps, sending coldStart, then linkDown and linkUp at each flap, as SNMPv2c INFORMs to a trap receiver on 127.0.0.1:1162

Packs are kind: composable YAML files in a catalog directory you control. Point sonda run at that directory with --catalog <dir> so pack: <name> references resolve. See Metric Packs for the catalog layout.

Dynamic labels

Dynamic labels rotate a label's value on every tick. Unlike cardinality spikes, the label is always present and cycles through a bounded set.

File Generator Strategy Description
dynamic-labels-fleet.yaml sine counter (10) 10-node set: hostname=host-0..host-9 rotating on a CPU-usage metric
dynamic-labels-regions.yaml uniform values list Cycle region through us-east-1, us-west-2, eu-west-1 on an API-latency metric
dynamic-labels-multi.yaml step counter + values Two rotating labels (hostname counter x region values) on a request counter
dynamic-labels-logs.yaml template (logs) counter (3) Rotating pod_name label on structured log events

See the Dynamic Labels guide for the walkthrough and Dynamic labels for the field reference.

Capacity planning

Test ingest pipelines by pushing high-volume, bursty, or high-cardinality workloads to VictoriaMetrics or another backend. Change url: to target your own stack.

File Generator Encoder Sink Description
capacity-throughput-test.yaml sine x3 prometheus_text http_push Three concurrent streams at 1000 evt/s each (3000 total) to find saturation
capacity-burst-test.yaml sine + bursts prometheus_text http_push 500 evt/s baseline with 10x spikes for 5s every 30s to test backpressure
capacity-cardinality-stress.yaml constant + spike prometheus_text http_push 500-value pod_name and 200-value endpoint cardinality spikes to test the index

See the Capacity Planning guide for measurement methodology.

Log scenarios

File Generator Encoder Sink Description
log-template.yaml template json_lines stdout Structured logs with field pools and severity weights
log-csv-replay.yaml csv_replay json_lines stdout Replay structured log events from a CSV (timestamp, severity, message, fields)
loki-json-lines.yaml template json_lines loki Push log events to a Loki instance
kafka-json-logs.yaml template json_lines kafka Send log events to a Kafka topic

Run log scenarios with sonda run. Log entries are signal_type: logs in the scenario YAML:

sonda run examples/log-template.yaml

Docker and VictoriaMetrics

File Generator Encoder Sink Description
docker-metrics.yaml sine prometheus_text stdout CPU wave (30 to 70%) for the Docker Compose stack
docker-alerts.yaml sine prometheus_text stdout Threshold-crossing sine for alert rule testing
victoriametrics-metrics.yaml sine prometheus_text http_push Push directly to VictoriaMetrics
vm-push-scenario.yaml sine prometheus_text http_push Push cpu_usage to VictoriaMetrics for alert testing

See Docker deployment for the full stack setup.

Alert testing

File Generator Encoder Sink Description
sine-threshold-test.yaml sine prometheus_text stdout Sine wave crossing a 90% threshold
for-duration-test.yaml sequence prometheus_text stdout Sequence pattern for for: duration testing
constant-threshold-test.yaml constant prometheus_text stdout Sustained 95% breach for for: 5m alerts
gap-alert-test.yaml constant prometheus_text stdout Alert resolution via periodic gaps
sequence-alert-test.yaml sequence prometheus_text stdout CPU pattern crossing a 90% threshold
spike-alert-test.yaml spike prometheus_text stdout Periodic spike from baseline 50 to 250 for threshold alerts
csv-replay-metrics.yaml csv_replay prometheus_text stdout Replay a real production incident from CSV
csv-replay-multi-column.yaml csv_replay prometheus_text stdout Replay three columns from a single CSV at the same time as independent metrics
csv-replay-grafana-auto.yaml csv_replay prometheus_text stdout Replay a Grafana CSV export with auto-discovered columns and labels
csv-replay-explicit-labels.yaml csv_replay prometheus_text stdout Multi-column replay with per-column labels merged with scenario labels
cardinality-alert-test.yaml constant prometheus_text http_push 500-value cardinality spike for cardinality alerts
ci-alert-validation.yaml constant prometheus_text http_push Constant 95% CPU for 30s — short enough for CI, long enough for a for: 5s alert

See the Alert Testing guide for the end-to-end walkthrough, and CI Alert Validation for automated validation in GitHub Actions.

Alerting pipeline

File Type Description
alertmanager/alerting-scenario.yaml Sonda scenario Sine wave pushing to VictoriaMetrics for alert evaluation
alertmanager/alert-rules.yml vmalert rules HighCpuUsage (>90) and ElevatedCpuUsage (>70) alerts
alertmanager/alertmanager.yml Alertmanager config Routes all alerts to the webhook receiver

These files are used with the --profile alerting Docker Compose profile. See the Alerting Pipeline guide for the full walkthrough.

Recording rules

File Generator Encoder Sink Description
recording-rule-test.yaml constant prometheus_text http_push Known value for sum-based recording rule validation
rate-rule-input.yaml sawtooth prometheus_text http_push Sawtooth pattern for rate()-based recording rule testing

See Recording Rules for the step-by-step guide.

Pipeline validation

File Generator Encoder Sink Description
e2e-scenario.yaml constant prometheus_text http_push Push a known value to VictoriaMetrics for end-to-end checks
multi-format-test.yaml constant influx_lp file InfluxDB line protocol to a file for format validation
multi-pipeline-test.yaml constant + template prom + json stdout + file Metrics and logs concurrently

See Pipeline Validation for usage patterns.

Network device telemetry

File Signal Description
network-device-baseline.yaml metrics Router with 2 uplinks: traffic counters, state, CPU, memory (9 scenarios)
network-link-failure.yaml metrics 6-scenario link-failure cycle on rtr-core-01: Gi0/0/0 down 10s, Gi0/0/1 absorbs, errors and CPU rise, then recovers

Run with sonda run:

sonda run examples/network-device-baseline.yaml
sonda run examples/network-link-failure.yaml

See Network Device Telemetry for the full walkthrough, including a 3-signal cascade using after: that you can write from scratch.

Multi-scenario

File Signal Description
multi-scenario.yaml metrics + logs Run both signal types at the same time
multi-metric-correlation.yaml metrics Correlated CPU and memory with phase_offset for compound alerts
multi-pipeline-test.yaml metrics + logs Pipeline validation with concurrent signal types

Run multi-scenario files with sonda run:

sonda run examples/multi-scenario.yaml

Tip

Override any scenario field from the CLI. For example, change the duration: sonda run examples/basic-metrics.yaml --duration 10s.