PDF

NetCrunch Native Data Formats

Native payload formats used by NetCrunch to ingest external monitoring data as counters, statuses, and contextual data objects using JSON, XML, and CSV.

Purpose and Scope

NetCrunch Native Data Formats define how external systems provide monitoring results to NetCrunch in a consistent, stateless, and monitoring-oriented way.

These formats are shared across all external ingestion mechanisms, including:

  • Telemetry Node payloads
  • Script and SSH-based sensors
  • Data File sensors (FTP, FTPS, HTTP, HTTPS, SSH, TFTP, Windows/SMB)
  • Receiver and legacy receivers
  • REST and HTTP-based sensors

No matter how data arrives, NetCrunch interprets it using the same data model, so it can be used uniformly for:

  • Alerting and policies
  • Dashboards and charts
  • Node status and sensor views
  • Topology and map overlays
  • Trending and reporting

Why a Native Format Exists

External sources are often stateless:

  • scripts run periodically and just print results
  • exporters and agents push snapshots
  • devices and APIs usually return only the current state
  • most systems do not store historical context

NetCrunch is the stateful component:

  • it stores time series for counters
  • it stores the last state for statuses
  • it detects state transitions
  • it stores contextual snapshots for data

This design makes external integrations simpler and safer. You can produce meaningful monitoring data without SDKs, local storage, or remembering previous values.

Core Elements

Every native payload may contain three types of elements:

  • Counters
  • Statuses
  • Data objects

CSV supports counters only and is described at the end.

Counters

Concept

A counter represents a numeric value collected repeatedly over time. NetCrunch stores counters as time series for trending and alerting.

Typical examples of counters:

  • CPU usage percent
  • disk free bytes
  • request rate per second
  • temperature in degrees
  • queue length
  • memory free megabytes
  • network bytes per second

Counter Structure Explained

A counter is identified by up to three parts:

Object
Category grouping related measurements
Examples: Processor, Disk, NetworkInterface, Weather
Counter
The specific measured value
Examples: % Processor Time, Free Bytes, Temperature
Instance
Optional identifier of a specific object
Examples: _Total, C:, eth0, Prague

A simple mental model:

  • Object answers what kind of thing this is
  • Instance answers which one
  • Counter answers what is being measured

External Counter Path Format

When sending external data, counter paths must use:

Object/Counter.Instance

Rules:

  • Object is optional. If omitted, NetCrunch uses Default
  • Instance is optional. If omitted, there is no instance
  • The dot always introduces an instance
  • A dot cannot be part of a counter name
Instance syntax rule
The dot (.) always introduces an instance.
Weather/Temperature has no instance.
Weather/Temperature.Prague has instance Prague.
Object defaulting rule
If the object is omitted, it becomes Default.
Temperature is treated as Default/Temperature.

The documentation intentionally uses explicit object names in its examples. Relying on Default is valid, but explicit objects are clearer and scale better.

Examples of External Counter Paths

Single context counter, no instance:

  • Weather/Temperature
  • System/CPU Usage
  • Web/Latency ms

Multi instance counter, instance after dot:

  • Weather/Temperature.Prague
  • Disk/Free Bytes.C:
  • NetworkInterface/Bytes Received.eth0
  • Sensor/Value.Channel 1

Display Format in the UI

In NetCrunch UI, counters are displayed using CIM style notation:

Object(instance)\Counter

This is a display format only. External payloads use the slash-and-dot format.

Examples:

  • Weather(Prague)\Temperature
  • Disk(C:)\Free Bytes
  • Processor(_Total)\% Processor Time

Counter Declaration and Storage

To avoid uncontrolled metric growth, counters are persisted and trended only when they matter.

A counter is stored when at least one condition is true:

  • a data collector declares the counter
  • a threshold is defined on a node or through the policy (monitoring pack)
  • a sensor has an option to collect all counters enabled

If you send a counter that is neither declared nor referenced, NetCrunch may ignore it. This protects the system from accidental metric explosions caused by scripts emitting dynamic or unbounded counter names.

JSON

{
  "counters": {
    "Weather/Temperature": 18.5,
    "Weather/Temperature.Prague": 16.2,
    "Disk/Free Bytes.C:": 82463372032
  }
}

XML

<nc>
  <counters>
    <counter path="Weather/Temperature">18.5</counter>
    <counter path="Weather/Temperature.Prague">16.2</counter>
    <counter path="Disk/Free Bytes.C:">82463372032</counter>
  </counters>
</nc>

Statuses

Concept

A status represents a discrete state rather than a numeric trend.

Statuses:

  • store only the last value
  • change over time
  • are evaluated on transitions

They are ideal for stateless scripts and external sources.

Typical uses:

  • service health
  • availability checks
  • logical modes
  • environmental states

Stateless State Model

External systems report only the current state.

NetCrunch:

  • stores the previous value
  • detects transitions
  • triggers alerts on change or specific transitions

This allows stateless scripts to behave like stateful monitors.

Standard Status Values

NetCrunch recognizes these standard states:

  • unknown
  • ok
  • warning
  • error
  • critical

Custom Status Values

Custom textual or numeric values are allowed:

  • Rain, Storm, Clear
  • Primary, Secondary
  • Open, Closed

Custom values may require explicit mapping in dashboards or policies.

Example: Service Health and Weather

The following example reports the health of the web service and the current weather.

JSON

{
  "statuses": {
    "WebService": "ok",
    "Weather": "Rain"
  }
}

XML

<nc>
  <statuses>
    <status name="WebService" value="ok"/>
    <status name="Weather" value="Rain"/>
  </statuses>
</nc>

Detailed Status with Metadata

Statuses may include additional context such as messages or diagnostic data.

JSON

{
  "statuses": {
    "WebService": {
      "value": "error",
      "message": "HTTP 503 from backend",
      "critical": true,
      "data": {
        "endpoint": "/api/orders",
        "retryAfter": 30
      }
    }
  }
}

XML

<nc>
  <statuses>
    <status name="WebService">
      <value>error</value>
      <message>HTTP 503 from backend</message>
      <critical>true</critical>
      <data>
        <item key="endpoint">/api/orders</item>
        <item key="retryAfter">30</item>
      </data>
    </status>
  </statuses>
</nc>

Data Objects

Concept

Data objects provide contextual monitoring information that explains what is happening right now.

They are:

  • collected during the monitoring cycle or via telemetry
  • stored as the latest snapshot only
  • displayed automatically in the Sensor View
  • not trended and not used for thresholds

Use data objects for:

  • lists of connected users or sessions
  • runtime statistics
  • diagnostic tables
  • grouped distributions

Data Views

Data Views are contextual views generated from the data branch of a native payload.

While technically represented as data objects in the payload, NetCrunch renders them as views and displays them automatically on the Sensor Views page of the node status.

Counters vs Data Objects

Use counters when you need trending or alert thresholds.

Use data objects when you need context or snapshot views and want to avoid high cardinality metrics.

Example: Connected Users Table

JSON

{
  "data": {
    "connectedUsers": {
      "type": "table",
      "name": "Connected Users",
      "columns": ["User", "Source", "Login Time"],
      "rows": [
        ["alice", "10.0.1.12", "10:21"],
        ["bob", "10.0.1.15", "09:58"]
      ]
    }
  }
}

XML

<nc>
  <data>
    <object id="connectedUsers" type="table" name="Connected Users">
      <data>
        <columns>
          <item>User</item>
          <item>Source</item>
          <item>Login Time</item>
        </columns>
        <rows>
          <row>
            <item>alice</item>
            <item>10.0.1.12</item>
            <item>10:21</item>
          </row>
          <row>
            <item>bob</item>
            <item>10.0.1.15</item>
            <item>09:58</item>
          </row>
        </rows>
      </data>
    </object>
  </data>
</nc>

Example: Contextual Time Series Snapshot

JSON

{
  "data": {
    "cpuHistory": {
      "type": "time-series",
      "name": "CPU History",
      "timestamps": [1672531200000, 1672531260000, 1672531320000],
      "values": [12, 15, 10]
    }
  }
}

XML

<nc>
  <data>
    <object id="cpuHistory" type="time-series" name="CPU History">
      <data>
        <timestamps>
          <item>1672531200000</item>
          <item>1672531260000</item>
          <item>1672531320000</item>
        </timestamps>
        <values>
          <item>12</item>
          <item>15</item>
          <item>10</item>
        </values>
      </data>
    </object>
  </data>
</nc>

Example: Category Distribution

JSON

{
  "data": {
    "httpCodes": {
      "type": "category",
      "name": "HTTP Responses",
      "categories": ["2xx", "3xx", "4xx", "5xx"],
      "values": [15230, 820, 431, 98]
    }
  }
}

XML


<nc>
  <data>
    <object id="httpCodes" type="category" name="HTTP Responses">
      <data>
        <categories>
          <item>2xx</item>
          <item>3xx</item>
          <item>4xx</item>
          <item>5xx</item>
        </categories>
        <values>
          <item>15230</item>
          <item>820</item>
          <item>431</item>
          <item>98</item>
        </values>
      </data>
    </object>
  </data>
</nc>

CSV Format

CSV is supported for counters only and is intentionally limited.

Path and Value Format


Weather/Temperature,18.5
Weather/Temperature.Prague,16.2
Disk/Free Bytes.C:,82463372032

Detailed Format


Weather,Temperature,,18.5
Weather,Temperature,Prague,16.2
Disk,Free Bytes,C:,82463372032

countersdata objectsdata viewsdata-ingestiondata-objectsformatsnativestatusestelemetry