/
Datapoint Logs

Datapoint Logs

You can use datapoint logs to maintain a historical record of selected datapoint values.  You can use historical datapoint values for displaying trends, data analytics, and historical reference.  You can use the CMS to specify which datapoints to log, how often to log them, and how long to retain them.  You can specify the same parameters using IAP/REST requests as described on this page.  You can also delete datapoints from the log using IAP/REST requests as described on this page.

Additional methods of viewing the data that has been added to the log file is described in Datapoint Monitor or Log Events.

You can specify up to three logging interval/retention period pairs for each datapoint to prune data as it ages and manage the maximum log size.  For example, log specifications for an energy datapoint may specify a 5-minute interval data to be retained for a week, 1-hour interval data to be retained for 6 months, and daily data to be retained for 5 years. The retention intervals are requests since the amount of data that can be retained is limited by available storage. The three logging levels in this example mean that you can displfay an energy trend chart with up to 5 minute resolution for the previous week, up to hourly resolution for the six months, and up to daily resolution for the previous 5 years. The data outside the retention periods is pruned to save storage space.

There can be multiple historical datapoint values returned in response to a request. The values are sorted by UTC timestamp.

URI Definition

Method          

URI and Fields

GET









/iap/devs/{id}/if/{block}/{block_index}/{datapoint_name}/logs

Returns the properties describing the logging configuration for the specified datapoints and log levels. Historical datapoint values can be stored for use for trend display, data analytics, and historical reference. Up to three logging interval/retention period pairs can be specified to prune data as it ages. 

XIFname vs Instance Name

  • The block path element uses the block XIFname.
  • The datapoint_name path element uses the datapoint instance name.

Path Parameters

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.

Example

https://localhost/iap/devs/*/if/*/*/nviPT/logs


Response:

[
   {
       "id": 352,
       "local": "2019-01-12 02:27:46.045 Europe/Kirov",
       "utc": "2019-01-11 23:27:46.045 UTC",
       "deviceId": "2",
       "deviceName": "00D07111EAC0",
       "blockName": "device",
       "blockIndex": "0",
       "datapointName": "nviPT",
       "deviceState": "provisioned",
       "deviceHealth": "normal",
       "root": {
           "level1": {
               "interval": 60,
               "retention": 2,
               "logMultiple": null
           },
           "level2": {
               "interval": 120,
               "retention": 0,
               "logMultiple": null
           },
           "level3": {
               "interval": 180,
               "retention": 0,
               "logMultiple": null
           },
           "minDeltaTime": 0,
           "minDeltaValue": "ALWAYS"
       }
   }
]                                                                                                  

/iap/devs/{id}/if/{block}/{block_index}/{datapoint_name}/logs/minDeltaValue

Returns the properties describing the logging configuration for the specified datapoints and log levels.

The logging configuration specifies up to three levels of data retention policy for a datapoint. The level value is the log level, and can have a value of "1", "2", or "3". The configuration and meaning of the log levels is defined by the user as described in Defining Datapoint Properties. Datapoint values are logged with a tag of log_level_1, log_level_2, or log_level_3 representing the log level for the logged datapoint. A logged datapoint may have multiple log_level_x tags if the datapoint is logged as the result of two or more log level specifications at the same time.

The minDeltaValue property specifies the required minimum change of value from the last logged value to log an updated value. Set to "any", "always", or a scalar value, where:

    • "any" logs data on any change subject to qualification by minDeltaTime
    • "always" logs data on every update subject to qualification by minDeltaTime;
    • a scalar value specifies a minimum change from the last logged value.

The default for minDeltaValue is "any". 

XIFname vs Instance Name

  • The block path element uses the block XIFname.
  • The datapoint_name path element uses the datapoint instance name.