Skip to content

Build scenarios

Sonda scenarios are YAML files you check into git alongside your alert rules and dashboards. This section is the reference for the scenario format and its parts:

  • The file structure and shared defaults.
  • The catalog of generators, encoders, and sinks.
  • Scheduling options.
  • Catalog and pack layout for many scenarios.

Start with Concepts if you have finished Get started and want the names for each part. Go to Generators, Encoders, or Sinks when you need to look up a specific type.

Start here

  • Concepts

    The four nested parts of Sonda — scenario, entry, pack, catalog — with a worked example based on a Node Exporter.

  • Scenario file format

    The full file structure: version: 2, kind: runnable, shared defaults:, after: chains, environment-variable interpolation, and the sink-error policy for sink write failures.

  • Catalogs and packs

    Organize a directory of scenarios with --catalog <dir>, and reuse metric definitions across scenarios with composable packs.

Building blocks

  • Generators

    Eight core metric generators (sine, sawtooth, step, spike, and others). Plus shortcut names for common combinations (flap, saturation, leak) and generators for logs and histograms.

  • Encoders

    Prometheus text, InfluxDB line protocol, JSON Lines, syslog, remote-write protobuf, and OTLP. Includes precision rules and feature flags.

  • Sinks

    stdout, file, TCP, UDP, HTTP push, remote_write, Loki, Kafka, and OTLP gRPC. Includes TLS, SASL, and retry-with-backoff.

Advanced

  • Scheduling

    Gaps, bursts, dynamic labels, cardinality spikes, and dependencies (after: and while:) that drive a scenario's behavior over time.

  • Sink batching

    How network sinks buffer events before delivery, the size and time thresholds that flush the buffer, and the trade-offs when tuning them.