PDF

Sending Data to NetCrunch

Read how to send data to NetCrunch and create a custom monitor. You can easily turn any application or script into a NetCrunch agent.

Data Receiver Sensor

You can add the Data Receiver Sensor from the sensor list on any node. The configuration here is very minimal. It needs a name, and it automatically creates an API key for an external agent expected to send data to NetCrunch. The API key consists of the sensor name (without spaces) and node id number. For example, an API key can be JMX@1034, if we name our agent "JMX."

You can add multiple sensors on a single node for each application you need to monitor.

Data Format

The sensor can process data in various formats using specific data parsers. By default, it uses native NetCrunch JSON format, but you can easily create a custom parser.

Retention Time

Because NetCrunch does not know how often you will send data to it, you need to specify a "retention time" for data, after which it will expire and be cleared out of memory.

REST API

We wanted to keep the API for the sensor straightforward. The simplest tool you can use to send requests to NetCrunch is cUrl open source project, available for almost any platform. You can find it at curl.haxx.se

The API consists of only 5 requests:

Update

POST /api/rest/1/sensors/<api-key>/update

By default, sensor expects <NetCrunch JSON> data format. So, the request payload should be application/json content type

Example
 {
    "retain": 1,
    "counters": {
        "PBX/line status.0" : 1,
        "PBX/line status.1" : 0
     },
     "statuses":  {
       "AC"  : "On",
       "Power": "On"
     }
 }

As you can see, you can send multiple statuses and counters in a single request.

Status Objects

Beside simple status values (key, value pairs), NetCrunch allows tracking of status objects. The status object can be described by the JSON object and can contain additional user data.

For example:

 {  
      "statuses" :  { 
           "Disk C:" : {
                          "value" : "ok",
                          "message" : "Working fine",
                          "retain" : 5,
                          "critical": true,
                          "data" : { 
                             "type" : "SDD", 
                             "upTimeSec" : 123431  
                          }
           }      
       }
    }

The status object can contain fields such as:

  • value - a status value that can be any string, but if one of the standard values is used, NetCrunch will use the value for calculation alert conditions. The field is required to recognize the status object, otherwise, the whole object will be treated as a text string. Standard values are: ok, error, warning, disabled, unknown.

  • name - the name of the object, it does not have to be unique. (optional)

  • message - this can be a message describing the state (for example, error message). (optional)
  • received - a time when the status has been read. (optional)

  • retain - how long status will be valid if no new status is received after this status becomes unknown. The time is in minutes.

  • data - custom data. It can be any JSON object, except if class points to one of the well-known classes, it must conform to the class data format.

  • critical - when true the sensor status will reflect highest status of a given object

Sensor Status Calculation

When your object contains the "Critical" field, it will influence whole sensor status; otherwise, sensor status is based on active alerts state.

Any object set to "critical": true will set sensor status to the highest alert level (error or warning). If the object is non-critical ("critical": false), then the sensor is in error state only if all objects are in error state, and it is in warning state when any of its objects are in error or warning state.

Counter

GET /api/rest/1/sensors/<api-key>/counter?<parameter-list>
Example
 <nc-server-address>/api/rest/1/sensors/<api-key>/counter?Temp=65&Wind=4&@retain=5

Counter/inc Counter/dec

As NetCrunch stores counter values in memory, the agent can increment it without storing its actual value. The request will increase or decrease the counter by the given value.

Example
 <nc-server-addres>/api/rest/1/sensors/<api-key>/counter/inc?Door.Opened=1

Status

GET /api/rest/1/sensors/<api-key>/status?<parameter-list>
Example
 <nc-server-address>/api/rest/1/sensors/<api-key>/status?Door=Opened&@retain=5

Sending data to multiple nodes - shared URLs

By default, the data URL is pointing to a single sensor on a single node, but if you want to supply data to multiple nodes, you can use a shared URL. To do this, check Use the shared URL option in the sensor configuration.

Generic sensor config

Now your data should be in the form of a JSON array, and each sensor object has to contain node identification, which is node DNS name or IP address depending on node Identification Type.

For example:

Example
[ 
 {
    "node": "192.168.10.1"
     "statuses":  {
       "AC"  : "On",
       "Power": "On"
     }
 } ,
 {
    "node": "test.lab"
     "statuses":  {
       "AC"  : "Off",
       "Power": "Off"
     }
 }                     
 ]

Web Messages

You can easily send event messages to NetCrunch using an HTTP request. The program accepts POST and GET requests.

Service URL
 http://<nc-server>/api/rest/1/event/<node-identification>

Node identification is a node IP address or DNS name.

Find more information below.

agentapidatadata receiverdata sensorgenericjsonmonitorobjectrestsensorstatus