PUDA Logger
By default, the PUDA CLI uses SQLite for local storage. This is enough for a local workstation, quick experiments, and single-user development.
For backups, persistent storage, and a more reliable record of the whole runtime environment, run the PUDA logger. It should run 24/7 on an always-on machine, in a Docker container.
The recommended template is PUDAP/puda-logger. It uses Telegraf to stream PUDA command and health telemetry from NATS into a central database.
The template uses InfluxDB. Most PUDA log queries are filtered by timestamp—runs, commands, telemetry, and events over a time window.
Run the logger
Clone the logger template on an always-on machine that can reach your NATS server. This can be the same machine that runs NATS, or another reliable machine on the same network.
The database server and the logger do not need to run on the same machine. A common split is InfluxDB on a NAS for durable storage, and the logger on a mini PC closer to NATS. Each host only needs network access to the services it talks to: the server must be reachable from the logger, and the logger must be able to reach NATS.
Start InfluxDB
On the machine that will host the database—for example, a NAS—clone the template and start the server stack:
git clone https://github.com/PUDAP/puda-logger.git
cd puda-logger/influxdb/server
Create an admin token file for InfluxDB:
echo '{"token": "<token>", "name": "<name>", "description": "Preconfigured admin token for influxdb-logger"}' > admin-token.json
Copy the server environment file:
cp .env.example .env
Edit .env and set INFLUXDB_TOKEN to the same token value from admin-token.json. Change INFLUXDB_PORT only if port 8181 is already in use on this host:
INFLUXDB_PORT=8181
INFLUXDB3_NODE_IDENTIFIER_PREFIX=puda
INFLUXDB_TOKEN=<token>
INFLUXDB_DATABASE=puda
INFLUXDB3_NUM_IO_THREADS=8
INFLUXDB3_WAL_FLUSH_INTERVAL=100ms
INFLUXDB3_EXEC_MEM_POOL_BYTES=70%
INFLUXDB3_CHECKPOINT_INTERVAL=1h
Start InfluxDB:
docker compose up -d
The Compose template stores InfluxDB data in a Docker volume, so logs remain available across container restarts. The defaults raise IO threads (8), flush the WAL every 100ms, and checkpoint snapshots hourly so ingest and restarts stay tractable. After the logger writes health data, influxdb-cache-init creates a last-value cache on telemetry keyed by machine_id.
For a small NAS set INFLUXDB3_NUM_IO_THREADS=4. For a 32-core ingest host use 12–16 and put the data volume on local NVMe. InfluxDB 3 Core remains a single node with a ~72 hour query window; use Enterprise when you need HA, compaction, or longer historical queries.
Start the logger
On the machine that will run the logger—for example, a mini PC on the lab network—clone the template if needed and configure the logger stack:
git clone https://github.com/PUDAP/puda-logger.git
cd puda-logger/influxdb/logger
cp .env.example .env
Edit .env and point the logger at your InfluxDB server and NATS broker. Use the same INFLUXDB_TOKEN from Start InfluxDB. Set NATS_SERVERS to the NATS URL(s) the logger can reach—for example, nats://<nats-host>:<port>:
INFLUXDB_URL=http://<influxdb-host>:8181
INFLUXDB_TOKEN=<token>
INFLUXDB_DATABASE=puda
INFLUXDB_ORGANIZATION=bears
NATS_SERVERS=nats://<nats-host>:<port>
LOGGER_REPLICAS=1
JS_MAX_ACK_PENDING=20000
LOGGER_REPLICAS is how many Telegraf logger containers to run. They share NATS queue groups, so each message is ingested once. Start at one replica per 10–20k machines. Increase the value if Telegraf CPU is pegged or the logs show metric buffer overflow / discarded metrics. Extra replicas on a CPU-saturated host do not help — run the same logger stack on another host instead; the queue groups will split work across hosts.
Start the logger with Docker Compose. Use --build on the first run, or after Dockerfile or entrypoint changes:
docker compose up -d --build
The nats-stream-init service creates the JetStream response streams and durable consumers, then starts the Telegraf-based influxdb-logger service (LOGGER_REPLICAS containers, default 1). After changing nats-init.sh or stream settings, recreate the init job so existing NATS resources are updated:
docker compose up -d --force-recreate nats-stream-init
docker compose up -d --force-recreate influxdb-logger
If you change telegraf.conf.template, restart without rebuilding:
docker compose restart influxdb-logger
To run without Docker, export the same variables and run ./docker-entrypoint.sh from influxdb/logger. This requires telegraf and envsubst (from gettext) on your PATH.
What the logger records
The InfluxDB logger uses Telegraf to stream PUDA NATS traffic into two measurements:
| Measurement | NATS subjects | Description |
|---|---|---|
commands | puda.*.cmd.* (requests), puda.*.cmd.response.* (responses) | Command and response log |
telemetry | puda.*.tlm.health | Machine health metrics (cpu, mem, temp), stored as a 60s mean per machine |
Health is still published at 1 Hz on NATS. The logger aggregates those samples and writes one mean point per machine per 60 seconds (cpu, mem, temp; connected as a 0–1 fraction). Command rows are stored 1:1.
Command requests use a plain core NATS subscription. Command responses use durable JetStream push consumers unique to the InfluxDB logger on RESPONSE_QUEUE and RESPONSE_IMMEDIATE (interest retention, 24h max-age). nats-stream-init creates those durables with inactive-threshold 0 so they are not deleted when the logger shuts down; responses published while it is down stay in the stream until the durable acks them. Telegraf requires version 1.39+.
For the full field and tag schema, see the influxdb-logger README.
Verify logging
After the logger is running, send a command to a PUDA machine:
puda machine home <machine_id>
Then inspect the logger container:
docker compose logs -f influxdb-logger
You should see the logger connected to NATS and InfluxDB, then processing machine health and command traffic as it arrives.
Next steps
- Connect Grafana to InfluxDB for dashboards and alerts on machine health and command history.
- If you run Hermes agents, install Hermes Logger to persist agent telemetry to the same InfluxDB server.