Configuration

Note:

Before starting configuration, a new module instance must be created.Click here for more information about creating Module instances.  Each module has an API and Logger section that need to be configured separately. The default settings will be sufficient for this, but users will need to actively open the API and Logger configuration settings and save the default values to fully apply the settings. Click here for more information about API and Logger Configuration.

Note:

Please note that starting from N3uron version 1.21.5, the API section has been completely removed from the configuration options.

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:

• 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.

Note:

It is strongly recommended that both the Store & Forward Buffer limit and the Insert Rate are properly configured in order to maximize data processing performance. For sites receiving a high number of events, a value between 100.000 and 200.000 for the Store & Forward Buffer limit and 5 seconds for the Insert rate is usually enough.

Note:

From N3uron version 1.21.4 onwards, this field is no longer available.

• 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

Note:

Due to backward compatibility, an older version of MongoDB is used as the embedded database. However, this version is not supported in recent OS releases (Debian 12 and later, Ubuntu 22 and later). Consequently, users with newer OS versions will need to install an external MongoDB instance.

• 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:

 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:

    • Average: Returns the weighted time average during the aggregation period.

    • Minimum: Returns the minimum value in the aggregation period.

    • Maximum: Returns the maximum value in the aggregation period.

    • First: Returns the first value in the aggregation period.

    • Last: Returns the last value in the aggregation period.

    • Delta: Returns the difference between the first and last sample during the aggregation period.

    • Standard deviation: Returns the Standard deviation during the aggregation period.

      Note:

      Delta and Standard deviation aggregates are available from N3uron version 1.21.10.

  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:

  • Average: Returns the weighted time average during the aggregation period.

  • Minimum: Returns the minimum value in the aggregation period.

  • Maximum: Returns the maximum value in the aggregation period.

  • First: Returns the first value in the aggregation period.

  • Last: Returns the last value in the aggregation period.

  • Delta: Returns the difference between the first and last sample during the aggregation period.

  • Standard deviation: Returns the Standard deviation during the aggregation period.

    Note:

    Delta and Standard deviation aggregates are available from N3uron version 1.21.10.

• 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.

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.

Historian Full Product Details