Statistics¶

The statistics interface allows the retrieval of live statistics, statistical history and statistical rates for the FogLAMP device.

FogLAMP records a number of statistics values, some with fixed names and other that reflect the name of a service or an asset. The statistics counters with fixed names are given below.

Key	Description
BUFFERED	Readings currently in the FogLAMP buffer
DISCARDED	Readings discarded by the South Service before being placed in the buffer. This may be due to an error in the readings themselves.
PURGED	Readings removed from the buffer by the purge process
READINGS	Readings received by FogLAMP
UNSENT	Readings filtered out in the send process
UNSNPURGED	Readings that were purged from the buffer before being sent

In addition to these fixed names there will be;

One statistic per north service or task that is named the same as the service or task name. This will count the number of readings sent out on that service.

One statistic per asset that is named the same as the asset. This will be the number of readings that have been ingested for that asset.

One statistics per south service, that is named with the service name and -Ingest appended. This is the count of readings read in for that service.

GET statistics¶

GET /foglamp/statistics - return a general set of statistics

Response Payload

The response payload is a JSON document with statistical information (all numerical), these statistics are absolute counts since FogLAMP started.

Example

$ curl -s http://localhost:8081/foglamp/statistics
[ {
    "key": "BUFFERED",
    "description": "Readings currently in the FogLAMP buffer",
    "value": 0
  },
...
  {
    "key": "UNSNPURGED",
    "description": "Readings that were purged from the buffer before being sent",
    "value": 0
  },
... ]
$

GET statistics/history¶

GET /foglamp/statistics/history - return a historical set of statistics. This interface is normally used to check if a set of sensors or devices are sending data to FogLAMP, by comparing the recent statistics and the number of readings received for an asset.

Request Parameters

limit - limit the result set to the N most recent entries.

Response Payload

A JSON document containing an array of statistical information, these statistics are delta counts since the previous entry in the array. The time interval between values is a constant defined that runs the gathering process which populates the history statistics in the storage layer.

Key	Description
interval	The interval in seconds between successive statistics values
statistics[].BUFFERED	Readings currently in the FogLAMP buffer
statistics[].DISCARDED	Readings discarded by the South Service before being placed in the buffer. This may be due to an error in the readings themselves.
statistics[].PURGED	Readings removed from the buffer by the purge process
statistics[].READINGS	Readings received by FogLAMP
statistics[].NORTH_TASK_NAME	The number of readings sent to the upstream system by the plugin with the north instance name
statistics[].UNSENT	Readings filtered out in the send process
statistics[].UNSNPURGED	Readings that were purged from the buffer before being sent
statistics[].ASSET-CODE	The number of readings received by FogLAMP since startup with name asset-code

Example

$ curl -s http://localhost:8081/foglamp/statistics/history?limit=2
{
  "interval": 15,
  "statistics": [
    {
      "history_ts": "2020-06-01 11:21:04.357",
      "READINGS": 0,
      "BUFFERED": 0,
      "UNSENT": 0,
      "PURGED": 0,
      "UNSNPURGED": 0,
      "DISCARDED": 0,
      "Readings Sent": 0
    },
    {
      "history_ts": "2020-06-01 11:20:48.740",
      "READINGS": 0,
      "BUFFERED": 0,
      "UNSENT": 0,
      "PURGED": 0,
      "UNSNPURGED": 0,
      "DISCARDED": 0,
      "Readings Sent": 0
    }
  ]
}
$

GET statistics/rate¶

GET /foglamp/statistics/rate - return a set of rates for a set of statistics. This interface returns the rate of a statistic value in counts per minute over a specified set of averages. It is passed two parameters, a comma separated list of intervals in minutes and a comma separated list of statistics.

Request Parameters

statistics - a comma separated list of statistics keys.

periods - a comma separated list of time periods in minutes.

The corresponding rate that will be returned for a given value X is the counts per minute over the previous X minutes.

Example

$ curl -sX GET http://localhost:8081/foglamp/statistics/rate?statistics=READINGS,Readings%20Sent\&periods=1,5,15,30,60

 {
   "rates": {
     "READINGS": {
       "1": 2561.0,
       "5": 512.2,
       "15": 170.73333333333332,
       "30": 85.36666666666666,
       "60": 42.68333333333333
     },
     "Readings Sent": {
       "1": 2225.0,
       "5": 445.0,
       "15": 148.33333333333334,
       "30": 74.16666666666667,
       "60": 37.083333333333336
     }
   }
 }