Sonda

Sonda is a synthetic telemetry generator written in Rust. It produces realistic observability signals -- metrics and logs -- for testing pipelines, validating ingest paths, and simulating failure scenarios. Unlike pure-random noise generators, Sonda models the patterns that actually break real pipelines: gaps, micro-bursts, cardinality spikes, and shaped value sequences.

Features at a glance

Quick install

Install script (Linux and macOS):

curl -fsSL https://raw.githubusercontent.com/davidban77/sonda/main/install.sh | sh

Cargo:

cargo install sonda

Docker:

docker run --rm --entrypoint /sonda ghcr.io/davidban77/sonda:latest metrics --name up --rate 5 --duration 10s

See the Getting Started guide for all installation options.

Your first metric

Emit a constant value -- the simplest signal for health-check or baseline testing:

sonda metrics --name up --rate 1 --duration 5s --value 1

up 1 1775518552355
up 1 1775518553360
up 1 1775518554360

Shape the signal with a sine wave, labels, and any of the eight built-in generators:

sonda metrics --name cpu_usage --rate 2 --duration 5s \
  --value-mode sine --amplitude 50 --period-secs 10 --offset 50 \
  --label host=web-01

Push directly to a backend -- no scenario file needed:

sonda metrics --name cpu --rate 10 --duration 30s \
  --encoder remote_write \
  --sink remote_write --endpoint http://localhost:8428/api/v1/write

Define complex scenarios in YAML for repeatable runs with sonda metrics --scenario config.yaml. The Tutorial walks through every generator, encoder, sink, and scheduling option step by step.

Built-in scenarios

Sonda ships with 11 pre-built patterns you can run instantly -- no YAML needed:

sonda scenarios list                       # browse the catalog
sonda scenarios run cpu-spike              # run a pattern directly
sonda scenarios show memory-leak           # view the YAML to customize it
sonda metrics --scenario @cpu-spike        # @name shorthand in any subcommand

See the Built-in Scenarios guide for the full catalog and customization workflow.

Documentation

Full documentation is available at https://davidban77.github.io/sonda/.

• Getting Started -- installation, first metric, first log scenario
• Tutorial -- generators, encoders, sinks, gaps, bursts, multi-scenario runs
• Configuration Reference -- scenario files, generators, encoders, sinks
• CLI Reference -- every flag for metrics, logs, histogram, summary, and run
• Deployment -- Docker, Kubernetes, sonda-server HTTP API
• Guides -- alert testing, pipeline validation, CSV replay, example catalog

Library usage

Add sonda-core to use the generation engine programmatically:

[dependencies]
sonda-core = "0.8"

Heavy dependencies (HTTP, remote write, Kafka, OTLP) are gated behind Cargo feature flags so you only pay for what you use. See the sonda-core docs on docs.rs for API details and feature flag reference.

Contributing

sonda/
├── sonda-core/     library crate: generators, encoders, schedulers, sinks
├── sonda/          binary crate: CLI
├── sonda-server/   binary crate: HTTP API control plane
└── examples/       YAML scenario files

cargo build --workspace && cargo test --workspace

Contributions are welcome. See CONTRIBUTING.md for build instructions, coding conventions, and the pull request process.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.