Skip to content

Built-in packs

Sonda ships a small curated catalog of metric packs compiled into the binary. They need no --catalog and no files on disk:

sonda list
Output
KIND        NAME                     TAGS  DESCRIPTION

[application]
composable  http_server_red                Request rate, error rate and latency quantiles (RED)

[infrastructure]
composable  node_exporter_cpu              Per-CPU mode counters (node_exporter-compatible)
composable  node_exporter_memory           Memory gauge metrics (node_exporter-compatible)

[kubernetes]
composable  kube_state_metrics             Pod phase, deployment replicas and restarts (kube-state-metrics)

[network]
composable  if_mib                         IF-MIB ifTable and ifXTable, extending the Telegraf SNMP interface pack
composable  openconfig_interface           OpenConfig interface counters and status, with gNMI paths
composable  telegraf_snmp_interface        Standard SNMP interface metrics (Telegraf-normalized)

Reference one from any runnable scenario:

version: 2
kind: runnable

defaults:
  rate: 1
  duration: 30s
  encoder:
    type: prometheus_text
  sink:
    type: stdout

scenarios:
  - signal_type: metrics
    pack: http_server_red
    labels:
      service: checkout
      job: checkout

sonda show <name> prints any of them verbatim, which is the fastest way to see the metric names, ids and default generators a pack declares.

These examples have no \"Run in playground\" button

The playground runs the engine in your browser with no catalog, so it cannot resolve a pack: reference at all — every example on this page needs the CLI. They are compiled in CI like every other scenario on the site; it is only the in-page run button they cannot offer.

What each pack is for

Every pack uses the real upstream metric names and label keys, so a dashboard query or alert rule written against the real exporter works against sonda unchanged. That is the point of them — they are not illustrative names.

Pack Category Models
http_server_red application Rate, Errors, Duration for a request-serving service
if_mib network The IF-MIB ifTable and ifXTable columns of an interface, extending telegraf_snmp_interface, with typed label columns
kube_state_metrics kubernetes Pod phase, the deployment replica gap, container restarts, node readiness
node_exporter_cpu infrastructure node_cpu_seconds_total per CPU mode
node_exporter_memory infrastructure node_exporter memory gauges
openconfig_interface network OpenConfig interface counters, oper-status and admin-status, with the gNMI path and value type of each
telegraf_snmp_interface network SNMP interface counters and status, Telegraf-normalized, with the IF-MIB OID and SNMP type of each

http_server_red

http_requests_total carries one series per status class (200, 404, 500), so rate() over the whole metric is your request rate and the code="500" series is your error rate. The defaults put roughly 0.4% of requests in the 5xx bucket, which is near a typical alert threshold without being over it.

http_request_duration_seconds is exposed as pre-computed quantile series — the shape a Prometheus summary has, not a histogram. A pack emits one value per spec, so it cannot produce _bucket/_sum/_count; for real buckets and histogram_quantile(), use a signal_type: histogram entry rather than a pack.

kube_state_metrics

Enum metrics follow the upstream one-series-per-value convention: kube_pod_status_phase appears five times, one per phase, carrying 1 for the phase that holds and 0 for the rest. Those are five series of one metric, which is why each spec declares its phase as an id: — see addressing a repeated metric name.

kube_deployment_status_replicas_available cycles 60s at 3 replicas then 20s at 2, so an "unavailable replicas" rule has something to fire on. A run shorter than 60s only ever sees the healthy state.

openconfig_interface

The counters and status leaves of an OpenConfig interface (/interfaces/interface/state in the openconfig-interfaces model): in_octets, out_octets, in_pkts, out_pkts, in_errors, out_errors, in_discards, out_discards, carrier_transitions, oper_status and admin_status. The status metrics are enum codes, 1 UP, 2 DOWN, 3 TESTING, and default to UP.

Every metric carries a gnmi: hint: its OpenConfig path and value type. Under the gnmi encoder the hints fill the encoder's paths: and values:, so the encoder block needs no template:

version: 2
kind: runnable

defaults:
  rate: 1
  encoder:
    type: gnmi
    origin: openconfig-interfaces
    target_label: device
  sink:
    type: gnmi_target
    listen: 0.0.0.0:57400

scenarios:
  - signal_type: metrics
    pack: openconfig_interface
    labels: { device: rtr-edge-01, ifName: Ethernet1 }

in_octets on Ethernet1 is served at /interfaces/interface[name=Ethernet1]/state/counters/in-octets as a uint_val, and oper_status at /interfaces/interface[name=Ethernet1]/state/oper-status as the string UP. Under any other encoder the hints are not used and the pack emits plain metrics. examples/gnmi-pack.yaml runs it for two interfaces.

telegraf_snmp_interface

The IF-MIB interface metrics Telegraf's inputs.snmp collects, under the names Telegraf gives them: ifOperStatus, ifHCInOctets, ifHCOutOctets, ifInErrors and ifOutErrors, labelled device, ifName, ifAlias, ifIndex and job. ifOperStatus is an enum code, 1 up, 2 down, and defaults to up.

Every metric carries an snmp: hint: its IF-MIB column, indexed by the ifIndex label, and its SNMP type. Under the snmp encoder the hints fill the encoder's oids: and types:, so the encoder block names no OIDs:

Metric OID Type
ifOperStatus 1.3.6.1.2.1.2.2.1.8.{ifIndex} integer
ifHCInOctets 1.3.6.1.2.1.31.1.1.1.6.{ifIndex} counter64
ifHCOutOctets 1.3.6.1.2.1.31.1.1.1.10.{ifIndex} counter64
ifInErrors 1.3.6.1.2.1.2.2.1.14.{ifIndex} counter32
ifOutErrors 1.3.6.1.2.1.2.2.1.20.{ifIndex} counter32

The pack's snmp_label_columns serve two labels as ifXTable columns, so a poller reads each interface's name and description beside its counters. They fill the encoder's label_columns::

Label OID
ifName 1.3.6.1.2.1.31.1.1.1.1.{ifIndex}
ifAlias 1.3.6.1.2.1.31.1.1.1.18.{ifIndex}
version: 2
kind: runnable

defaults:
  rate: 1
  encoder:
    type: snmp
    drop_labels: [job]
  sink:
    type: snmp_agent
    listen: 0.0.0.0:1161

scenarios:
  - signal_type: metrics
    pack: telegraf_snmp_interface
    labels: { device: rtr-edge-01, ifIndex: 1, ifName: Ethernet1 }

ifHCInOctets on interface 1 is served at 1.3.6.1.2.1.31.1.1.1.6.1 as a Counter64, and its name at 1.3.6.1.2.1.31.1.1.1.1.1 as the string Ethernet1. Every label is in the instance OID, is the agent label, is a label column, or is dropped: ifIndex is the index arc, device the agent label, ifName and ifAlias label columns, so only job is dropped. An oids:, types: or label_columns: entry in the encoder block wins over the pack's. Under any other encoder the hints are not used and the pack emits plain metrics. examples/snmp-telegraf.yaml runs it for four interfaces, polled by Telegraf.

if_mib

The interface as IF-MIB defines it: if_mib extends telegraf_snmp_interface, keeps its five metrics as they are, and adds five more ifTable and ifXTable columns. One pack entry is one interface. Every metric carries an snmp: hint, so under the snmp encoder the encoder block names no OIDs:

Metric OID Type Default
ifOperStatus 1.3.6.1.2.1.2.2.1.8.{ifIndex} integer 1, up
ifHCInOctets 1.3.6.1.2.1.31.1.1.1.6.{ifIndex} counter64 +125,000 a tick
ifHCOutOctets 1.3.6.1.2.1.31.1.1.1.10.{ifIndex} counter64 +62,500 a tick
ifInErrors 1.3.6.1.2.1.2.2.1.14.{ifIndex} counter32 0
ifOutErrors 1.3.6.1.2.1.2.2.1.20.{ifIndex} counter32 0
ifSpeed 1.3.6.1.2.1.2.2.1.5.{ifIndex} gauge32 1,000,000,000 (bits/s)
ifAdminStatus 1.3.6.1.2.1.2.2.1.7.{ifIndex} integer 1, up
ifInOctets 1.3.6.1.2.1.2.2.1.10.{ifIndex} counter32 +125,000 a tick, wrapping at 2³²
ifOutOctets 1.3.6.1.2.1.2.2.1.16.{ifIndex} counter32 +62,500 a tick, wrapping at 2³²
ifHighSpeed 1.3.6.1.2.1.31.1.1.1.15.{ifIndex} gauge32 1,000 (Mb/s)

Its five label columns serve the interface's labels as ifTable and ifXTable columns: the base's two, and three of its own. ifIndex and ifType are typed columns: the label's text is served as an INTEGER, as IF-MIB defines those columns.

Label OID Served as Default
ifIndex 1.3.6.1.2.1.2.2.1.1.{ifIndex} integer —
ifDescr 1.3.6.1.2.1.2.2.1.2.{ifIndex} OCTET STRING ""
ifType 1.3.6.1.2.1.2.2.1.3.{ifIndex} integer 6, ethernetCsmacd
ifName 1.3.6.1.2.1.31.1.1.1.1.{ifIndex} OCTET STRING ""
ifAlias 1.3.6.1.2.1.31.1.1.1.18.{ifIndex} OCTET STRING ""

ifNumber, the number of interfaces (1.3.6.1.2.1.2.1.0), is not a pack metric: a pack entry is one interface, and the count belongs to the scenario, which serves it as a scalar entry of its own with its own encoder block.

version: 2
kind: runnable

defaults:
  rate: 1
  encoder:
    type: snmp
    drop_labels: [job]
  sink:
    type: snmp_agent
    listen: 0.0.0.0:1163

scenarios:
  - signal_type: metrics
    pack: if_mib
    labels: { device: sw-access-01, ifIndex: 1, ifName: Gi1/0/1, ifDescr: GigabitEthernet1/0/1 }

  - signal_type: metrics
    pack: if_mib
    labels: { device: sw-access-01, ifIndex: 2, ifName: Gi1/0/2, ifDescr: GigabitEthernet1/0/2 }

  - signal_type: metrics
    name: ifNumber
    labels: { device: sw-access-01 }
    encoder:
      type: snmp
      oids: { ifNumber: "1.3.6.1.2.1.2.1.0" }
      types: { ifNumber: integer }
    generator: { type: constant, value: 2 }

ifType.1 is served at 1.3.6.1.2.1.2.2.1.3.1 as INTEGER: 6, and ifIndex.2 at 1.3.6.1.2.1.2.2.1.1.2 as INTEGER: 2. A label a typed column cannot serve, such as ifType: copper or ifType: "6.5", is refused when the scenario is validated, naming the label, the type and the value. The pack carries no gnmi: hints: openconfig_interface is the gNMI pack. examples/if-mib-switch.yaml serves a 24-port switch on port 1163, polled by Telegraf in the interface-table layout of its documentation (examples/telegraf/telegraf-if-mib.conf).

Change one metric without editing the pack

Use overrides:, keyed by selector — a metric name, or name.id where the pack repeats that name:

version: 2
kind: runnable

defaults:
  rate: 1
  duration: 30s
  encoder:
    type: prometheus_text
  sink:
    type: stdout

scenarios:
  - signal_type: metrics
    pack: http_server_red
    labels:
      service: checkout
      job: checkout
    overrides:
      http_request_duration_seconds.p99:
        generator:
          type: spike_event
          baseline: 0.310
          spike_height: 0.900
          spike_duration: 20s
          spike_interval: 180s

That turns the p99 series into a latency incident and leaves the other six untouched — the pack emits seven series in total. A bare http_request_duration_seconds would be an error, listing the three ids to choose from — the pack repeats that name, so a bare key addresses no single metric.

Build on one instead of copying it

To model a specific platform, extend a built-in rather than forking it. The base stays where it is and you state only the difference:

version: 2
kind: composable

name: checkout_api
description: "The checkout service's RED metrics"
category: application
extends: http_server_red

shared_labels:
  service: checkout

metrics:
  - name: http_request_queue_depth
    generator:
      type: steady
      center: 4.0
      amplitude: 2.0
      period: 120s
      noise: 0.4

deviations:
  - metric: http_requests_total.server_error
    replace:
      generator:
        type: step
        start: 0.0
        step_size: 0.4

Drop that in your --catalog <dir> and reference pack: checkout_api. Because extends: resolves through the same lookup as pack:, shadowing http_server_red with your own file in that directory would change every extension built on it.

Pack defaults are a starting point, not a fixture

The generators here are chosen to look plausible and to give alert rules something to evaluate. They are not a recording of any real system. When you need exact values — a specific incident, a captured production window — use sonda capture or a csv_replay generator instead of tuning pack defaults.

Adding to the built-in set

The built-in packs live in packs/ at the repo root and are embedded with include_str!. Adding one means adding its entry to sonda-core/src/catalog/builtin.rs and moving PACK_COUNT — the count gate fails if you do only one, so a half-wired pack cannot ship quietly.

Two checks run over the whole set on every commit. Each pack must compile through the real pipeline with the real resolver, and no pack's default generator may emit a negative value: every metric these packs model is a count, a duration, a byte total or a 0/1 enum. That second gate exists because a latency series once shipped at -0.44 seconds — the steady alias defaults its noise to ±1.0 absolute, which is fine for a percentage and ruinous for a 32ms quantile. Set noise: explicitly on any small-magnitude generator.