Advanced configuration for Embedded Linux

spotflowd reads TOML configuration from /etc/spotflow/spotflowd.toml by default. Only [device] is required; other sections have defaults. See the upstream annotated configuration for all settings.

Edit existing sections rather than declaring the same TOML table twice, then restart the service to apply changes.

Device Identity and Ingest Key

[device]
id = "linux-device-001"
ingest_key = "<your-ingest-key>"

Use a unique device ID that remains stable across reboots and software updates. Manage keys on the Ingest Keys page; see Device Authorization for their scope and lifecycle. Keep credentials out of version control and restrict configuration-file access to administrators and the service account. Provision credentials separately from reusable device images.

Validate Configuration

Run preflight validation as the account that runs the daemon:

sudo install -d -o spotflow -g spotflow -m 0755 /run/spotflow
sudo -u spotflow spotflowd config-check --config /etc/spotflow/spotflowd.toml

The first command prepares the default socket directory for a manual check before the first service start; systemd normally creates it automatically. For root-run configurations, use sudo spotflowd config-check --config /etc/spotflow/spotflowd.toml instead. Validation checks syntax, unknown keys, compiled features, numeric bounds, storage, and Unix socket access without starting collection. It uses the caller's filesystem permissions, so testing as root does not verify an unprivileged service's access.

Persistent Storage

[storage]
state_dir = "/var/lib/spotflow"

The state root must be an absolute path, writable by the service account even in metrics-only deployments.

logs.buffer.disk_max_size_mb limits only log chunks, not the entire directory. Metric values awaiting upload remain in memory, and crash records stay in their configured pstore directories until queued. Volatile storage loses state on reboot; use persistent storage when buffered logs must survive a restart.

For a custom root, provision its ownership and add it to the systemd service's ReadWritePaths using a drop-in. Changing the configured path does not move existing state files.

Tune Resource Usage

[logs.buffer]
memory_max_entries = 1000
disk_max_size_mb = 64
disk_chunk_max_entries = 200

[metrics]
aggregation_interval = "1m"

[metrics.os]
enabled = true
collection_interval_secs = 10

• The memory-first log buffer reduces flash writes; a smaller buffer spills to disk sooner.
• The disk limit is in MiB. Oldest log chunks are dropped when the spool is full.
• Larger metrics aggregation windows ("1h" or "1d") reduce upload frequency.
• Disable unused OS metric groups to reduce collection work and traffic.

MQTT Connection

[mqtt]
broker = "mqtt.spotflow.io"
port = 8883
keepalive_secs = 60

Normally these defaults should remain unchanged. Ensure outbound TCP access to the broker, working DNS, a valid device clock for certificate validation, and trusted CA certificates. The daemon maintains one TLS connection and reconnects automatically on failure.

Local Status

sudo spotflowd status
sudo spotflowd status --json

Status is read from a local Unix socket and works without internet access. It includes source health, collection times, MQTT state, queued records and bytes, oldest queued data, drops by reason, storage failures, version, and active configuration. The ingest key is redacted.

Queue totals exclude records already handed to the MQTT transport queue. connection.last_publish_ms indicates local MQTT activity, not confirmed cloud delivery.

To change the status socket:

[status]
socket_path = "/run/spotflow/custom-status.sock"

sudo spotflowd status --socket /run/spotflow/custom-status.sock

Internal Logging and Manual Runs

On systemd, view daemon logs with sudo journalctl -u spotflowd -f. To change the daemon's own verbosity, set RUST_LOG in a systemd drop-in:

[Service]
Environment=RUST_LOG=debug

Reload the unit with sudo systemctl daemon-reload and restart the service. This controls daemon diagnostics, not filtering of collected application logs.

For a foreground test, stop any existing service instance first to avoid competing for sockets and state:

sudo systemctl stop spotflowd
sudo RUST_LOG=debug spotflowd run --config /etc/spotflow/spotflowd.toml

Stop the foreground process before starting the service again. On non-systemd devices, use your init system to stop and restart the service instead.

Learn more