Metrics with the metrics facade

Overview

whatsapp-rust ships an optional metrics Cargo feature that emits wa_* counters, histograms, and gauges through the metrics facade. Spans from the tracing feature tell you the story of a single case; metrics give you the rates and latency percentiles you need for dashboards and alerts. The library only emits through the facade. It never installs a recorder and does not depend on Prometheus or OTLP — your application chooses the recorder and exposes the scrape endpoint.

The metrics feature is off by default. With it disabled there is no metrics dependency, every emit is an inlined no-op, and the duration Timer is a zero-sized type that reads no clock. There is zero runtime cost.

When to use it

Turn on metrics when you want to:

Build Grafana, Datadog, or Honeycomb dashboards for connect success rate, IQ latency percentiles, retry receipts, send throughput, or app-state sync health.
Page on connection loss, identity-change spikes, or rising decrypt failure rates.
Compare aggregate behavior across deployments without enabling per-trace export.

If you only need to investigate a single incident or trace, prefer the tracing feature — it is the lower-cardinality counterpart and is designed to work alongside metrics.

Enabling the feature

Add whatsapp-rust with the metrics feature, plus the recorder you want to expose. The example below uses Prometheus:

Cargo.toml

[dependencies]
whatsapp-rust = { version = "0.7", features = ["metrics"] }
metrics = "0.24"
metrics-exporter-prometheus = "0.16"

For OTLP, swap in metrics-exporter-opentelemetry (or any other recorder that implements the metrics::Recorder trait).

Wiring a recorder

Install the recorder once at startup, then build your Client as usual. A runnable version of this wiring ships as examples/metrics.rs in the source repo:

src/main.rs

fn main() {
    // Install a Prometheus recorder. `install_recorder()` sets the global recorder
    // and returns a handle you can render from your own HTTP endpoint. Use
    // `PrometheusBuilder::install()` instead (inside a Tokio runtime) to serve
    // `/metrics` on 0.0.0.0:9000 automatically.
    let handle = metrics_exporter_prometheus::PrometheusBuilder::new()
        .install_recorder()
        .expect("install prometheus recorder");

    // Optional: register units and help text for the wa_* metrics.
    whatsapp_rust::telemetry::describe();

    // Build and run your `whatsapp_rust::Client` as usual; every wa_* metric is
    // recorded into the recorder above.

    // Serve `handle.render()` from your HTTP `/metrics` route.
}

Run it with the feature on:

cargo run --example metrics --features metrics

Metric catalogue

All metrics are prefixed with wa_ and emitted at the same boundaries as the matching wa.* tracing spans. Counters and gauges carry the categorical breakdown; the matching duration histograms are unlabeled.

Counters

Name	Labels	Description
`wa_recv_total`	`outcome` = `decrypted`, `duplicate`, `duplicate_resend`, `undecryptable`, `skmsg`	Inbound messages by receive-processing outcome. Most values are decrypt outcomes; `duplicate_resend` is the one post-decrypt exception — it decrypts successfully but is then suppressed by the dispatch-once gate (#1352), distinct from `duplicate`, the byte-identical redelivery the Signal ratchet itself rejects before decryption completes
`wa_send_total`	`kind` = `dm`, `group`, `status`	Outgoing send attempts by kind
`wa_retry_receipt_total`	`reason`	Retry receipts sent, by reason
`wa_iq_total`	`result` = `ok`, `timeout`, `error`	IQ requests by result
`wa_reconnect_total`	—	Reconnect attempts
`wa_stream_error_total`	—	Stream errors received
`wa_connect_total`	`outcome` = `ok`, `fail`	Connection attempts by outcome
`wa_appstate_sync_total`	`outcome` = `ok`, `fail`	App-state collection syncs by outcome
`wa_appstate_mutations_total`	—	App-state mutations applied
`wa_identity_change_total`	—	Peer identity changes that triggered a session reset
`wa_prekey_upload_total`	`outcome` = `ok`, `fail`	Pre-key uploads by outcome
`wa_session_record_quarantined_total`	—	Stored session rows that failed to decode and were treated as absent for recovery. Steady state is zero — see session row quarantine
`wa_unkeyable_device_total`	`reason` = `no_bundle`, `session_setup`, `session_lookup`, `rejected_406`, `rejected_4xx`, `rejected_5xx`, `rejected_other`, `refused_batch`, `fetch_failed`, `encrypt`	Failed attempts to obtain key material for one device, by reason (#1304)

wa_unkeyable_device_total is the rate to watch after a session-repair change, or to page on when a chat sits on “Waiting for this message”. It is an attempt counter, not a per-delivered-device one — a retry that fails the same way counts again. 406 keeps its own label since it’s the only code that changes client behavior. refused_batch is kept apart from a named rejected_* label because a batch refusal names no device. stats()’s devices_unkeyed_* fields carry the same totals without the per-code split.Both are process-wide: they say a device went unkeyed somewhere, never which message lost it. As of #1362, the per-message question is answered by SendResult::recipient_fanout instead — a DM’s result carries how many recipient devices it addressed, how many actually encrypted, and whether the recipient’s primary device was among the ones that didn’t.

Histograms (seconds)

Name	Description
`wa_iq_duration_seconds`	IQ request round-trip time
`wa_connect_duration_seconds`	Connection establishment time
`wa_decrypt_duration_seconds`	Inbound session-decrypt batch time
`wa_send_duration_seconds`	Outgoing send time
`wa_appstate_sync_duration_seconds`	App-state sync time

Gauges

Name	Description
`wa_connected`	`1` while the client is connected, `0` otherwise

Recording your own durations

The same Timer the library uses internally is part of the public API. Hold the returned guard for the scope of the operation; it records elapsed seconds on drop:

use whatsapp_rust::telemetry;

async fn do_iq() {
    let _t = telemetry::timer(telemetry::IQ_DURATION);
    // perform the IQ round-trip; the timer records on drop.
}

PII and cardinality

Labels are strictly low-cardinality categorical values (outcome, kind, result, reason). The library never uses a JID, phone number, or message ID as a label — that would explode the metrics backend and leak PII. Histograms are unlabeled; the matching _total counter carries the categorical breakdown.

This guarantee only covers identifiers the library emits. If your own code records custom metrics with raw JIDs or phone numbers as labels, you will leak PII and blow up cardinality. Use stable categorical values for your own labels too.

Overhead

Configuration	Cost
Feature off (default)	No dependency, every emit is an inlined no-op, `Timer` is zero-sized
Feature on, no recorder installed	Near-zero (the facade short-circuits)
Feature on, recorder installed	Pay per emit at the recorder’s rate

Durations use the pluggable wacore::time::Instant, so WASM and deterministic builds are unaffected.

Observability with tracing — per-case spans that complement the aggregate metrics here.
Installation — feature flags — full feature matrix including metrics, tracing, and tracing-pii.

Getting Started

Core Concepts

Guides

Advanced

Metrics with the metrics facade

Overview

When to use it

Enabling the feature

Wiring a recorder

Metric catalogue

Counters

Histograms (seconds)

Gauges

Recording your own durations

PII and cardinality

Overhead

​Overview

​When to use it

​Enabling the feature

​Wiring a recorder

​Metric catalogue

​Counters

​Histograms (seconds)

​Gauges

​Recording your own durations

​PII and cardinality

​Overhead

​Related

Overview

When to use it

Enabling the feature

Wiring a recorder

Metric catalogue

Counters

Histograms (seconds)

Gauges

Recording your own durations

PII and cardinality

Overhead

Related