Datapoint Logs

Owned by Nina Cardillo
10-Jan-2024
9 min read

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.

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/*/*/nvoEPpos/logs/minDeltaValue


Response:

[
   {
       "id": 433,
       "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": "nvoEPpos",
       "deviceState": "provisioned",
       "deviceHealth": "normal",
       "minDeltaValue": "ALWAYS"
   }
]                                                                               

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

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.

The minDeltaTime property specifies the minimum number of seconds between logged values. If 0, there is no time throttle. 

Defaults to "0" to disable the throttle. 

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.

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

The following fields are returned if minDeltaValue or minDeltaTime are not specified: 

interval

The requested maximum interval between logged values, subject to the qualification conditions specified by minDeltaValue and minDeltaTime. Set to a number of seconds, or set to 0 to not specify a maximum interval. Defaults to "0".

retention       Retention period in days.

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.

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 level path element allows you to specify a log level. 

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

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

Returns the historical values for the specified datapoint. 

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

Each Data Log Value GET response will be an JSON encoded value with the following fields:

idA monotonic unique event record ID.
local

The local date and time when the datapoint value was captured, including the timezone where the datapoint update was captured.

For Example:  "2017-08-23 11:34:22.123 BST".

utc

The UTC date and time when the datapoint value was captured.

For Example:  "2017-08-23 10:34:22.123 UTC".

deviceIdThe device ID for the device containing the datapoint.
blockNameThe block type name for the block containing the datapoint.
blockIndexThe block handle for the block containing the datapoint.
datapointNameThe name of the datapoint on the device as defined by the block type.
deviceState

The state of the device containing the datapoint at the time the datapoint value was captured, as described in Device Status.

The possible values include "provisioned" and "unprovisioned".

deviceHealth

The health of the device containing the datapoint at the time the datapoint value was captured.

The possible values are "normal", "suspect", "down", and "nascent" (described in the health parameter in Device Status).

valueThe value of the datapoint.
tagsThe tags defined for the datapoint at the time it was logged, where each tag is a key and optional value.

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 value_param path element allows you to specify a value. 

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

PUT






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

Sets properties specifying the logging configuration for the specified datapoints and log levels. The minDeltaValue property specifies the required minimum change of value from the last logged value to log an updated value. Returns "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". 

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.

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.

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

Sets properties specifying the logging configuration for the specified datapoints and log levels. The minDeltaTime property specifies the minimum number of seconds between logged values. If 0, there is no time throttle. Defaults to "0" to disable the throttle.

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 through DLA files, as described in Creating a DLA File in Defining Datapoint Properties.

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.

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

Sets properties specifying the logging configuration for the specified group of datapoints and log levels. Any of the following fields can be specified for a level if  minDeltaValue  or  minDeltaTime are not specified: 

intervalThe requested maximum interval between logged values, subject to the qualification conditions specified by minDeltaValue and minDeltaTime. Specifies a number of seconds, or 0 if there is no maximum interval. Defaults to "0".
retention      Data retention period in days.

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 through DLA files, as described in Creating a DLA File in Defining Datapoint Properties.

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 level path element allows you to specify a log level. 

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

DELETE






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

If minDeltaValue is specified, the specified property is set to "0".

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.

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

If minDeltaTime is specified, the specified property is set to "0".

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.

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

If minDeltaValue or minDeltaTime are not specified, sets the interval to "0" and the retention interval to "0" for the specified log level.

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 level path element allows you to specify a log level. 

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

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

Deletes the specified historical values from the datapoint log.

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 value_param path element allows you to specify a value. 

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

Queries

You can include queries with your IAP/REST request to specify a selection rule for your request.  As described in Queries and Parameters, you can specify a query as a query parameter  appended to the end of your URI preceded with a "?" character, or as a path parameter within a path element of the path component.

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

Logging Configuration

Logging configuration is stored per datapoint.

  • If a GET request specifies multiple datapoints, the configuration is returned for each of the datapoints matching the query parameters. 
  • If a PUT request specifies a configuration to be stored for multiple datapoints, the same configuration is stored for each of the datapoints matching the query parameters. 
  • If a DELETE request specifies multiple datapoints, the configuration is cleared for each of the datapoints matching the query parameters.

Datapoint Log Value

The Datapoint Log Value GET and DELETE requests can include optional query parameters.  

  • If a GET request specifies multiple datapoints, the values are returned for each of the datapoints matching the query parameters.  
  • If a DELETE request specifies multiple datapoints, the historical values are deleted for each of the datapoints matching the query parameters.

Examples

Get all level 1 logged datapoints named nvoEnergy from device 17q2d95.4:

GET /iap/devs/17q2d95.4/if/*/*/*+name==nvoEnergy&tag==log_level_1/logs/value/*                                         


Get all logged datapoints named nvoEnergy, nvoVoltage, or nvoPwrFactor from device T6tWyg8.3:

GET /iap/devs/T6tWyg8.3/if/*/*/*+name=+^(nvoEnergy)%7C(nvoVoltage)%7C(nvoPwrFactor)/logs/value/*    

To implement the logical or, the | symbol is required, but cannot be included in a URI.  To include the logical-or symbol, insert %7C which is the ASCII encoding of the | symbol.


Delete all logged datapoints:

DELETE /iap/devs/*/if/*/*/*/logs/value/*                                                                                                                   


A datapoint log response for a logged Lamp nviValue datapoint:

[ {
  "id" : 19,
  "local" : "2017-08-23 11:34:22.123 BST",
  "utc" : "2017-08-23 10:34:22.123 UTC",
  "deviceId" : 17q2d95.4,
  "blockName" : "Lamp",
  "blockIndex" : "0",
  "datapointName" : "nviValue",
  "deviceState" : "provisioned"
  "deviceHealth" : "normal",
  "value" : {
    "state" : 1,
    "value" : 100
  }
  "tags":[
    {"tag1": "data_1"},
    {"tag2": "Outdoor Air Sensor"},
    {"tag3": null},
    {"tag4": "testing"}]
} ]