Prometheus output

The Prometheus output exposes collected telemetry as Prometheus gauge metrics on an HTTP scrape endpoint. A Prometheus server pulls the endpoint on its own schedule and feeds the data into the rest of your monitoring stack. After the first mention, this page refers to Prelude Collector as "the collector".

When to use

Pick Prometheus when you already run a Prometheus / Alertmanager / Grafana stack and want operator-facing dashboards and alerts on collected telemetry. It is not the right Output for real-time event processing — there is always a scrape-interval delay between collection and visibility. See Output selection for the trade-off versus NATS or Webhook.

How it works

The backend starts a dedicated HTTP server on a configurable port. For each numeric field in a record, it updates a GaugeVec labelled with device, device_id, and key.

Metric names are constructed as:

collector_{model}_{field}

Both {model} and {field} are sanitized — any character that is not alphanumeric or _ is replaced with _ so the result is a valid Prometheus identifier.

Labels

Every gauge carries three labels:

Metric types

Only Gauge metrics are exposed. Gauges are appropriate for telemetry values that represent a current state — utilization, queue depth, temperature, link state — rather than monotonically increasing counters.

Numeric values, and string values that parse as a 64-bit float (via strconv.ParseFloat), are exported. Booleans, nested objects, and strings that don't parse as a number are silently skipped.

Connection settings

Configure this backend through PUT /api/v1/outputs/prometheus.

No required fields — defaults are applied if both are omitted.

Authentication

The scrape endpoint is unauthenticated. Restrict access to it at the network layer (private VLAN, firewall rule, reverse proxy) — the same practice applied to Prometheus exporters generally.

Configuration example

{
  "enabled": true,
  "config": {
    "metrics-path": "/metrics/collector",
    "port": 9090
  }
}

Then add the corresponding scrape job to your prometheus.yml:

scrape_configs:
  - job_name: "prelude-collector"
    static_configs:
      - targets: ["collector.example.com:9090"]
    metrics_path: /metrics/collector

The metrics server runs on a private Prometheus registry, so the endpoint exposes only collector data — no Go runtime metrics.

Behavior on failure

Because Prometheus pulls, there is nothing for the collector to "fail" on its side: when no scraper is reading, gauges simply sit in memory and are overwritten by the next collection cycle. The backend's Output() call returns success unconditionally, so the Prometheus row on /api/v1/outputs/metrics will always show failures: 0 — use Prometheus's own up{} and scrape_duration metrics for monitoring, not this counter.

If a device stops reporting, its gauge retains the last known value until the collector restarts or the Output is reloaded. Account for this in alerting rules — use absent() or up{} checks in addition to value thresholds.

To validate that the metrics port is bindable, use POST /api/v1/outputs/prometheus/detect, which probes port-available (in-use is reported as a non-fatal warning).

Limitations

• Only gauges are emitted; counters, histograms, and summaries are not supported.
• Metric names are derived mechanically from model and field names — there is no per-metric override.
• There is no built-in authentication on the scrape endpoint; restrict access at the network layer.
• Stale gauges retain the last value; they are not automatically expired when a device stops reporting.
• The default port (9090) is also the Prometheus server's default — pick a different port if both run on the same host.

See also

• Output backends
• Output selection
• Send data to Grafana