server · telemetry
Telemetry that sees inside the process.
Every push, pull, and ack is timed and counted automatically. You get latency histograms, live throughput rates, and structured logs without writing any instrumentation code.
This page explains what bunqueue measures and where to read each number. For the full metric list, scrape config, dashboards, and alert rules, see [Monitoring](/guide/monitoring/).
## Latency Histograms
Every push, pull, and ack operation is timed and recorded in a Prometheus histogram (a set of counters that tracks how many operations fell under each duration threshold, which lets you compute percentiles later):
| Metric | Description |
|--------|-------------|
| `bunqueue_push_duration_seconds` | Time to push a job |
| `bunqueue_pull_duration_seconds` | Time to pull a job from a queue |
| `bunqueue_ack_duration_seconds` | Time to acknowledge a completed job |
Each exposes `_bucket`, `_sum`, and `_count` series on `/prometheus`, with bucket boundaries in seconds at `0.0001, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10`.
```bash
curl http://localhost:6790/prometheus
```
Compute percentiles in Prometheus with `histogram_quantile()`:
```text
# p99 push latency
histogram_quantile(0.99, sum by (le) (rate(bunqueue_push_duration_seconds_bucket[5m])))
# p50 pull latency
histogram_quantile(0.50, sum by (le) (rate(bunqueue_pull_duration_seconds_bucket[5m])))
```
Averages can be derived from `_sum / _count` and are in seconds in Prometheus. Latency averages returned by the `Metrics` TCP command remain in milliseconds (`avgLatencyMs` and `avgProcessingMs`); the unit change only corrects Prometheus exposition. The `bunqueue metrics` CLI prints Prometheus text, while the HTTP `/metrics` endpoint only exposes the `total*` counters.
## Throughput Rates
The server tracks live per-second rates using an exponential moving average (a smoothing technique that favors recent activity, so the number reacts quickly without jitter):
| Rate | Description |
|------|-------------|
| `pushPerSec` | Jobs pushed per second |
| `pullPerSec` | Jobs pulled per second |
| `completePerSec` | Jobs completed (acked) per second |
| `failPerSec` | Jobs failed per second |
Read them from the `/stats` HTTP endpoint:
```bash
curl http://localhost:6790/stats
```
```json
{
"ok": true,
"stats": {
"waiting": 120,
"active": 8,
"pushPerSec": 12500,
"pullPerSec": 12480,
"completePerSec": 12460,
"failPerSec": 2
}
}
```
The real response's `stats` object also includes `prioritized`, `delayed`, `dlq`, `completed`, `waiting-children`, `uptime`, the `total*` counters (failure counts appear only as `totalFailed`/`failPerSec` — there is no `failed` field), and `cronJobs`/`cronPending`; `memory` and `collections` are top-level siblings of `stats`. The example is trimmed to the rate fields.
These rates are not part of the `/prometheus` output. In Prometheus, derive rates from the counters instead:
```text
rate(bunqueue_jobs_pushed_total[5m])
```
## Per-Queue Drill-Down
The per-queue gauges (`bunqueue_queue_jobs_waiting{queue="..."}` and friends, listed in [Monitoring](/guide/monitoring/#per-queue-metrics)) let you build per-queue dashboards and alerts:
```text
bunqueue_queue_jobs_waiting{queue="emails"} # backlog of one queue
sum(bunqueue_queue_jobs_active) # active jobs across all queues
topk(5, bunqueue_queue_jobs_waiting) # top 5 queues by backlog
```
Programmatically, in embedded mode:
```typescript
const perQueue = queueManager.getPerQueueStats();
// Map