Configuration

Module configuration

Users can configure data storage by selecting Historian from the explorer tree menu. The following screenshot shows the different available options for Historian configuration:

Historian parameters

• Parameters:
  • Store & forward buffer limit: Maximum number of events that can be stored in the memory buffer for batch insertions in the database. If the max size is reached, links with remote nodes will automatically be paused. Once the number of events stored in the buffer decreases to a level below half the set limit, the links will automatically be enabled again. A value of `0` disables the buffer limit so that the links will never be paused. However, this is not recommended, especially in nodes receiving a large volume of events, since it may result in RAM overflow when the number of events received is higher than the number of the events processed.
  • Insert rate: Specifies the time between data insertions in the buffer to the database, displayed in milliseconds. Insertions are processed in batches by date, starting with the oldest data. The minimum value is 1000ms.

• Max days: Number of days that stored data is kept in the target database. Data older than the specified number of days will automatically be deleted.
• Database type: Select the type of database between Embedded (default) or External to use an external MongoDB instance.
  

Embedded

• Database:
  • Network interface: Specifies a comma-separated list to make the database accessible. It is important to note that the database will always listen to localhost, in addition to the interfaces selected. The option to browse and discover a network interface is also available by clicking on the button on the right. 
  • TCP port: Specifies the TCP port used to connect to the database. The default setting is the MongoDB default TCP port 27017. Valid range: 1 to 65535.
  • Database path: Directory to store the database files. Can be an absolute or relative path.

External

• Database:
  • Protocol: Specifies the MongoDB connection string format, valid values are mongodb to use the standard mode or mongodb+srv for the SRV mode.
  • Host: Hostname or IP address of the target external MongoDB engine.
  • TCP port: Specifies the TCP port used to connect to the database. The default setting is the MongoDB default TCP port 27017. Valid range: 1 to 65535.
  • Database name: Name of the database where data will be stored. If authentication is enabled, authentication will be carried out against this database.
  • Parameters: Connection parameters for MongoDB in query format, e.g. retryWrites=true&w=majority.
  • Authentication:
    • Enabled:  Enables or disables authentication to the external MongoDB engine.
    • Username: Username used to authenticate with the MongoDB database.
    • Password: Password used to authenticate with the MongoDB database.
  • TLS:
    Note:

    This feature is new in N3uron version 1.21.5.
    • Enabled: Enables TLS connection to the host.
      • CA: CA used to validate the certificate.
      • rejectUnauthorized: Reject untrusted certificates.

Tag configuration

After configuring the Historian module, users can configure the historization of specific tags. The following screenshot shows the different available options for configuring the Tag history section:

Figure 2: Tag history configuration

 History parameters:

• Enabled: Enables historization of the tag.
• Module name(s): Specifies the name(s) of the module(s) that will historize the tag. A comma-separated list can be used for multiple modules. For local Historian modules, use HistorianModuleName or ./HistorianModuleName. For remote Historian modules, use NodeName/HistorianModuleName.
  • Mode: Available mode is “Change”, which stores all changes outside of the deadband.
  • Deadband: Specifies the deadband for Change mode.
• Range Y:
  • Minimum: Default Y-axis minimum value, in engineering units.
  • Maximum: Default Y-axis maximum value, in engineering units.
• Chart:
  • Interpolation: Available options are “step” and “linear”. If “step” is selected, tags are trended as a step. If “linear” is selected, tags are trended as a line.
  • Default method: Available options are “last” and “average”. If “last” is selected, the last value in the period is provided. If “average” is selected, the average value during the period is provided.
• Rate:
  • Minimum: Minimum storage rate, displayed in milliseconds. It represents the shortest time allowed between storing two consecutive change events. It is important to note that events stored due to reaching the Maximum rate setting are not considered when determining this minimum time interval. Example: If the Minimum Rate is set to 500 milliseconds, Historian ensures that at least 500 milliseconds must elapse between the storage of any two consecutive change events.
  • Maximum: Maximum storage rate, displayed in milliseconds. This interval defines the longest time allowed between storing new records in the absence of new events. When no new events occur, Historian will store a new record with the same value at the Maximum Rate interval. Example: If the Maximum Rate is set to 1000 milliseconds, Historian will store a new record with the same value if no new events occur within a 1000-millisecond period.

Data retrieval

Historian stores events (changes in value, quality, or timestamp). Data can be retrieved from the storage in different modes:

• Raw: Data retrieved contains all values for all events stored in the database.
• Aggregated: Data is consolidated into aggregation periods. The following aggregation methods are available:
  • avg: Time-weighted average.
  • min: Minimum value during the aggregation period.
  • max: Maximum value during the aggregation period.
  • first: First value during the aggregation period.
  • last: Last value received during the aggregation period.
• Delta: The data retrieved contains all the values of all events displaying incremental changes compared to any previous event that is larger than the configured deadband. It only contains the second event (the one taking place after the first event that surpassed the deadband).
• Filter: Data retrieved contains all the values for all events displaying changes compared to any previous event that is larger than the configured deadband. In this case it contains both events, the one before the change that surpassed the deadband and the one after the change.

Figure 3: Delta and Filter chart

Data stored in Historian can be retrieved using the following methods:

• WebUI: Includes a rich HTML5 interface to retrieve and visualize data in charts and data tables (raw and aggregated data). Data can also be exported to CSV files. The historical data retrieved can be located in the same N3uron node as the WebUI or in a different N3uron node, providing that the nodes are connected through a N3uron Link.
•  REST API Server: By using the optional RestApiServer module, historical data can be retrieved in JSON format using REST API calls (raw data and aggregated data). The historical data retrieved can be located in the same N3uron node as the REST API server or in a different N3uron node, providing the nodes are connected through a N3uron Link. Several examples of historical data retrieval can be found in the Rest Api Server Manual.
• WebVision: Includes a component to retrieve and visualize data in charts and data tables similar to the interface provided by WebUI. Data can be also exported to CSV files. The historical data retrieved can be located in the same N3uron node as the WebUI or in a different N3uron node, providing that the nodes are connected through a N3uron Link.
• MongoDB client: Direct connection to the MongoDB database to retrieve data in raw mode.

Figure 4: Historian charts from the WebUI

Historian Full Product Details