Device Telemetry

Use Nexigon Agent to emit structured events from a connected device. Events record messages, severity, categories, and attributes so operators can investigate device behavior over time.

A device property describes a current value, while an event records an occurrence. For example, a property can hold the latest sensor reading, and an event can record a disconnected sensor or a threshold crossing. Events preserve the sequence needed to understand how a device reached its current state.

Nexigon Agent sends events immediately and does not buffer them while offline. An emission fails when the device has no connection to Nexigon Hub. Handle that failure in your application if event delivery affects its behavior.

Emit an Event

Run this on a connected device:

nexigon-agent events emit '"Sensor service started"'

The body must be valid JSON. It can be a string, object, array, number, boolean, or null. To report a structured reading:

nexigon-agent events emit '{"temperature_c": 24.5, "sensor": "ambient"}'

The outer single quotes protect the JSON from the shell. A text body still needs JSON double quotes, as in the first example. The second example uses an object so consumers can read its temperature and sensor fields directly.

Open the device’s event log in Nexigon to check that the event arrived.

Classify Events

Severity describes how serious an event is. The default is info; use debug or trace for diagnostic detail, warning for a potential problem, and error or critical for failures that need attention. For example:

nexigon-agent events emit --severity error '"Sensor connection has been lost"'

Use --category for a stable event type and repeat --attribute for additional JSON values:

nexigon-agent events emit \
  --category "com.example.sensor.connection" \
  --severity error \
  --attribute 'sensorId="ambient"' \
  --attribute 'retryCount=3' \
  '"Sensor connection has been lost"'

Keep the set of categories small so operators can filter by event type. Use attributes for varying values such as serial numbers, versions, or request IDs. In the example, sensorId is a JSON string and retryCount is a JSON number. Keeping these as separate attributes lets consumers interpret the values without extracting them from the message text. Prefix custom categories with your domain to avoid name conflicts.

See the Telemetry reference for severity values and field semantics.

OpenTelemetry Compatibility

Dedicated and enterprise Nexigon instances support a per-project OTLP collector for exporting events to an observability system such as Grafana or Datadog. Ask your Nexigon Hub operator to configure the collector.

Before exporting, Nexigon Hub adds trusted device information, including the device ID. Downstream systems can use that identity to associate events with the authenticated device that emitted them.