NATS output

The NATS output publishes each collected record to a NATS subject in real time. It is Prelude Collector's native streaming transport and the recommended Output for low-latency event distribution. After the first mention this page refers to Prelude Collector as "the collector".

When to use

Pick NATS when you want sub-second fan-out of telemetry to one or more downstream consumers and you already run (or are willing to run) a NATS server. It is the right default for streaming between services and pairs well with another Output (Prometheus or InfluxDB) for dashboards and history. See Output selection for the full trade-off.

How it works

For every record in a Snapshot, the backend publishes a JSON-encoded payload to a subject derived from the record's model and device:

collector.data.{model}.{deviceId}

Subscribers can use NATS wildcards to receive all models for one device (collector.data.*.42) or all devices for one model (collector.data.cpu.*).

Message format

Each message is a JSON-serialised ParsedData envelope. All field names are kebab-case:

{
  "device": "router-01",
  "device-id": 42,
  "model-name": "cpu",
  "path": "Cisco-IOS-XR-wdsysmon-fd-oper:system-monitoring/cpu-utilization",
  "key": "cpu",
  "timestamp": "2024-01-01T12:00:00Z",
  "data-hash": "sha256:8f3c…",
  "data": {
    "usage": 45.2,
    "cores": 8
  }
}

Subscribers should key on device-id (numeric uint, the device's DB id) and model-name — not the older snake-case forms. path echoes the source-protocol path that produced the record; data-hash is a content hash useful for deduplication on the consumer side.

Connection settings

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

Authentication

Two modes are supported:

• Unauthenticated — Leave seed-path empty. Suitable for local or test NATS servers on a trusted network.
• NKey — Set seed-path to a file readable by the collector process. This is the standard mode for production deployments.

client-name is optional and only affects how the collector appears in NATS monitoring dashboards.

Configuration example

{
  "enabled": true,
  "config": {
    "url": "nats://nats.example.com:4222",
    "seed-path": "/etc/prelude/nats.seed",
    "client-name": "prelude-collector"
  }
}

Apply it with:

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X PUT "$BASE/api/v1/outputs/nats" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @nats-output.json

Bruno: 08 Outputs / Update output config

Behavior on failure

Publishes are fire-and-forget — there is no per-message acknowledgement. Failures (broken connection, slow consumer, server unreachable) are surfaced through the /api/v1/outputs/metrics endpoint as a rising failures counter rather than back-pressure on the collection pipeline.

Flush() is a no-op for NATS. On graceful shutdown the backend calls Drain() to deliver any in-flight messages before closing the connection; if draining fails, a warning is logged and the process continues.

To validate connectivity proactively, use POST /api/v1/outputs/nats/detect, which probes the reachable and authenticated checks against the proposed config (or the saved one when the body is omitted).

Limitations

• The collector publishes to core NATS subjects only. JetStream streams, consumers, and persistence are out of scope of this Output — point a JetStream consumer at the subjects above if you need durability.
• Subject names are derived mechanically from {model} and {deviceId}; subject names are not configurable per Output.
• There is no client-side retry or buffering. A NATS server outage manifests as failed publishes in the metrics endpoint, not as delayed delivery.

See also

• Output backends
• Output selection
• API reference