PDF

Telemetry Node

A Telemetry Node is a NetCrunch node type for receiving metrics, statuses, and events from external systems via REST or OTLP. It anchors telemetry data for cloud, IoT, or custom systems, and replaces the older REST Receiver with a unified, event-capable design.

Overview

In NetCrunch, every monitoring object must be tied to a node. The Telemetry Node is purpose-built for ingesting external metrics, statuses, and events—ideal for workloads and devices that cannot be polled or exist outside the direct network (e.g., cloud, scripts, IoT, embedded).

Common uses:

  • Remote or embedded systems
  • Cloud applications & APIs
  • IoT/headless devices
  • Apps/scripts pushing telemetry

How to Add a Telemetry Node

  1. Click the Add (+) button at the top of the NetCrunch UI.
  2. In the popup menu, select:
    Telemetry Node
  3. Enter the desired node name and choose data retention time.
  4. Confirm. NetCrunch assigns a nodeId and creates the default Telemetry Sensor (sensorId).

The sensor is always created and cannot be removed, only disabled.

Node Type Transition

  • The REST Receiver node type is now deprecated and replaced by Telemetry Node.
  • Telemetry Node:
    • Supports event ingestion
    • Uses sensorId as the main identifier (not just nodeId)
    • Sensors are auto-added (can be disabled but not deleted)
    • Legacy REST Receivers still work but are superseded

Supported Input Protocols

Protocol Endpoint Type Data Format
REST (JSON) Local/Cloud REST NetCrunch JSON
OTLP OTLP Gateway OpenTelemetry (HTTP/gRPC)

All data is routed to the Telemetry Node Sensor (nodeId + sensorId).

REST Endpoints

  • Local REST:
    https://<nc-server>/api/rest/1/sensors/<sensorId>@<nodeId>/update
  • Cloud REST:
    https://gw.netcrunch.io/tm/v1/<serverId>@<sensorId>@<nodeId>/update

Example Payload


{
  "counters": { "system/cpu.load": 0.75 },
  "statuses": {
    "uptime": {
      "value": "ok",
      "data": { "statusCode": 1 },
      "message": "System running for 3 days"
    }
  }
}

OTLP Gateway (OpenTelemetry)

  • Metrics:
    https://otlp.netcrunch.io/v1/<serverId>@<sensorId>@<nodeId>/metrics
  • Logs:
    https://otlp.netcrunch.io/v1/<serverId>@<sensorId>@<nodeId>/logs
Aspect REST Endpoint OTLP Gateway
Format NetCrunch JSON OTLP Metrics/Logs
Protocol HTTPS (JSON) HTTP/HTTPS (OTLP JSON/Binary)
URL gw.netcrunch.io otlp.netcrunch.io
Processing Direct ingestion Translated to internal format

Notes:

  • Traces not supported.
  • Logs = non-active alerts. Metrics = counters.
  • Histogram support planned.

Event Ingestion Endpoints: Telemetry Node vs Web Message Sensor

Important: The endpoint for sending events is different for Telemetry Nodes compared to classic Web Message Sensors. Using the wrong endpoint means events will not be processed.

Telemetry Node Event Endpoint

For Telemetry Nodes, events must be sent to the sensor endpoint:

https://<nc-server>/api/rest/1/sensors/<sensorId>@<nodeId>/event

  • The event is linked to the specific sensor (sensorId) created for the Telemetry Node.
  • This is required for all Telemetry Node event alerts to work.

Web Message Sensor (Legacy) Event Endpoint

For legacy Web Message Sensors (non-telemetry), events must be sent to the node endpoint:

https://<nc-server>/api/rest/1/node/<nodeId>/event

  • The event is linked directly to the node (nodeId).

Why This Matters

  • Telemetry Node: expects events by sensorId.
  • Web Message Sensor: expects events by nodeId.

If you send events for a Telemetry Node to the node/<nodeId>/event endpoint, they will not be processed.

Quick Reference

Node Type Correct Endpoint
Telemetry Node https://<nc-server>/api/rest/1/sensors/<sensorId>/event
Web Message Sensor https://<nc-server>/api/rest/1/node/<nodeId>/event

Always use the sensorId endpoint for Telemetry Nodes; use nodeId only for classic Web Message Sensors.

Sending Data – Examples

Cloud REST Update


curl -X POST https://gw.netcrunch.io/tm/v1/SRV-1@sensor42@node91/update \
  -H "Content-Type: application/json" \
  -d '{"counters":{"system/disk.freeMB":12800},"statuses":{"system/fan":{"value":"ok","message":"normal"}}}'

Local REST Event


curl -X POST https://<nc-server>/api/rest/1/sensors/sensor42/event \
  -H "Content-Type: application/json" \
  -d '{"message": "failed login"}'

  • Event fields: message, description, attributes (additional params like user, time, etc.)

Alerting on Events

  • Event alerts support filtering on event fields.
  • Empty filter = match all.

Empty filters match all events. Applies to both Telemetry Node and Web Message sensors.

Node Behavior & Monitoring

  • Telemetry Node anchors all incoming metrics, statuses, and events
  • Supports dashboards, alerting, and historical data
  • Can receive Monitoring Packs and policies
  • Appears in topology views (unless hidden)

Summary

Telemetry Nodes deliver a push-based model for observability—ideal for remote/cloud/IoT data, with robust REST and OTLP support and direct event ingestion. They simplify integrating external or serverless systems with NetCrunch monitoring.

event endpointnetcrunchobservabilityotlp gatewaypush monitoringreceiver noderemote metricsrest apisensor updatetelemetry node