Device Telemetry
This guide explains how to collect telemetry from your devices using Nexigon device events.
What are device events? Device events are structured JSON messages emitted by devices. They enable you to track device behavior and monitor device health, warnings, and errors in real-time.
Currently, the agent emits events immediately to Nexigon and fails when there is no connection. We plan to implement a queuing system to allow the emission of events, even if a device is offline. We would appreciate your input on how such a system should work. Care must be taken not to exhaust the storage of a device during long offline periods, making the design non-trivial. See Issue #1 for further details.
Emitting Events​
Use Nexigon Agent to emit events from your device:
nexigon-agent events emit '"This is a test event"'
The event body is an arbitrary JSON object, allowing you to include any relevant data.
Event Severity Levels​
Events support six severity levels to classify their importance:
| Severity | Use Case |
|---|---|
trace | Low-level tracing for detailed debugging. |
debug | Debugging information during development. |
info | General informational messages (default). |
warning | Potential problems that may need attention. |
error | Problems that affect functionality. |
critical | Severe issues requiring immediate attention. |
You can specify the severity when emitting events with the --severity option:
nexigon-agent events emit --severity error '"Sensor connection has been lost"'
Event Categories​
Categories are used to specify the type of an event, determining its structure. You can specify the category of an event with the --category option. The category can be an arbitrary string. To avoid conflicts, we recommend using domain prefixes. The number of categories in the system should be kept rather low, to allow for efficient filtering. If you need to attach further high-cardinality information to events, use event attributes.
Event Attributes​
You can add key-value attributes using the --attribute option for additional JSON metadata:
nexigon-agent events emit \
--category "dev.nexigon.ota" \
--attribute 'currentVersion="1.0.0"' \
--attribute 'targetVersion="1.1.0"' \
'"Installing OTA update"'
OpenTelemetry Compatibility​
Nexigon's device event system has taken inspiration from OpenTelemetry. In the future, we will support connecting an external telemetry collector to Nexigon's backend via OTLP. Prior to exporting events, Nexigon will enrich events with trusted device data (in particular, device IDs). That way, you can process device events through the systems and tools that you already like and use, including the LGTM stack und Prometheus, while also being able to trust that the events being processed have indeed been emitted by particular devices.