Metrics with Embedded Linux

Prerequisites

Install and configure the daemon using the Embedded Linux quickstart or Yocto integration. Its state directory must be writable even for metrics-only deployments because metric sequence numbers are persisted there.

Enable OS Metrics

OS metrics are disabled by default. Enable them in /etc/spotflow/spotflowd.toml:

[metrics]
aggregation_interval = "1m"

[metrics.os]
enabled = true
collection_interval_secs = 10

All groups below are enabled when OS collection is enabled. Availability of individual values depends on your kernel and hardware.

To reduce collection on constrained devices, disable groups or limit monitored mounts and network interfaces:

[metrics.os.groups]
disk = false
network = true

[metrics.os.disk]
mount_points = ["/"]

[metrics.os.network]
interfaces = ["eth0"]

Replace eth0 with your device's interface name. An empty interfaces list auto-detects non-loopback interfaces. Mount selection applies when the disk group is enabled.

Enable Custom Application Metrics

Enable the Unix domain socket listener:

[metrics.custom]
enabled = true
socket_path = "/run/spotflow/metrics.sock"

Restart the daemon after configuration changes:

sudo systemctl restart spotflowd
sudo spotflowd status

On Yocto SysVinit devices, use /etc/init.d/spotflowd restart as root instead.

Report Custom Values

Connect to the socket, write one or more newline-delimited JSON objects, and close the connection. Each object has a name, a numeric value, and optional string-to-string labels:

{"name":"queue_depth","value":42}
{"name":"job_duration_ms","value":183.5,"labels":{"worker":"main"}}

For a shell test using OpenBSD netcat (-N closes the connection after input ends):

echo '{"name":"queue_depth","value":42}' | nc -UN /run/spotflow/metrics.sock

BusyBox netcat may not support Unix sockets. Applications can write directly using their language's socket API, for example in Python:

import json
import socket

def send_metric(name, value, labels=None):
    message = {"name": name, "value": value}
    if labels:
        message["labels"] = labels
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
        connection.connect("/run/spotflow/metrics.sock")
        connection.sendall(json.dumps(message).encode() + b"\n")

send_metric("queue_depth", 42)
send_metric("job_duration_ms", 183.5, {"worker": "main"})

No response is sent back: writing to the socket is not an acknowledgement of cloud delivery. The socket is local-only but allows any local user to submit values by default; use it only with trusted local processes.

Analyze Metrics in Dashboards

After the aggregation window completes and the device is connected, open the Device Dashboard for device metrics. Use Custom Dashboards to visualize application-specific values and labels.