Value history / analytics
OnSphere values content can be saved when used alongside an output, provided by the analytics module.
Capabilities
Capability |
Support |
Comment |
|---|---|---|
Display metrics and graphs using Grafana |
|
See Grafana |
Access to the GUI of InfluxDB |
|
|
Use other database than InfluxDB (external) |
|
The system is tightly coupled with InfluxDB and cannot be used with other databases. |
Use embedded InfluxDB (in orchestrator) |
|
|
Use an existing InfluxDB (external) |
|
|
Configure the authentication (API access) to the InfluxDB |
|
|
Use Keycloak as an identity provider |
|
See InfluxDB Auth |
High-availability of the database |
|
Not implemented in the version with InfluxDB. However, it is possible to use your own InfluxDB Clustering by using your InfluxDB instance, see Use an existing InfluxDB and InfluxDB clustering |
Configure retention size |
|
InfluxDB does not support retention size, only retention time. |
Configure retention time |
|
|
Configure different retentions policies by values |
|
|
Modify the retentions time of buckets |
|
|
Configure compression of historized values |
|
Can be implemented using InfluxDB tasks (Flux scripts) or by configuring an external InfluxDB instance, see Use an existing InfluxDB |
Delete specifics values with custom rules |
|
This feature is currently not supported. In case of interest please contact us at info@sdn.ch |
Rolling average of values |
|
This feature is currently not supported. In case of interest please contact us at info@sdn.ch |
Moving/duplicating data to another storage |
|
This feature is currently not supported. In case of interest please contact us at info@sdn.ch |
Link a measure to a value |
|
When linked a change of the value will be persisted into timeseries. See Grouping values |
Use different retention time for different values |
|
|
Save a measurement in two different buckets (retention time) |
|
This is possible by using multiples output files. But be warn that the data will be duplicated |
Support of all types of osp value |
|
The system support all the internal representation of a value. See Supported types of values |
Customize display name |
|
|
Grouping values together (classification) |
|
See Grouping values |
Tagging values |
|
See Tagging values |
Fetching the last states of a value |
|
Only with Chart. See Fetching the last states of a value |
Access to the internal InfluxDB
Concept
The InfluxDB instance is integrated into the OnSphere stack and automatically starts with it. The database includes a built-in GUI that users can access.
Warning
Configuring the InfluxDB instance is generally not recommended, as the system is managed by OnSphere. Directly modifying the database configuration may cause conflicts if the OnSphere settings are updated. Additionally, any manual configuration must be replicated across all environments (such as QA/testing) since it is not embedded in the OnSphere configuration. This can lead to errors when redeploying from scratch.
Use Cases
Accessing the InfluxDB GUI
Modifying the retention period of an existing InfluxDB bucket
Using the InfluxDB instance for other purposes
Usage
By default, the InfluxDB GUI is not accessible. To enable access, the user must add a port forwarding rule in the module.service file of the influxdb module. The following line should be added:
ports:
- 8086:8086
The default HTTP port is 8086. For the username and password, refer to the System security.
Use an existing InfluxDB
Concept
The InfluxDB instance can be either internal to the stack or external. If it is external, the InfluxDB instance must be configured to accept the values sent by the OnSphere stack.
Use-cases
Use an existing InfluxDB instance
Use an external InfluxDB instance
Usage
To connect to an existing external database, the following operations must be performed:
Configure network access to the InfluxDB instance.
Configure authentication via an API token.
Configure the module.analytics file to match the desired organization. The default organization is set to
OnSphere.Buckets are automatically created at module startup. If they already exist, they will not be updated see Modify the data retention time of data
Configure retention of values
Concept
The retention time defines how long the values will be stored inside the InfluxDB instance. After this time, the values will be deleted and not recoverable.
Use-cases
Keep the values for a specific amount of time
Automatically delete old values
Save space on the InfluxDB instance
Usage
It is possible to define data retention through the bucket. Each bucket has a data retention policy. A bucket can be defined in the module.analytics file. It is then possible to define a bucket for each value via the output.analytics file.
Warning
The minimum retention time is 1 hour.
See Modify the data retention time of data to modify the retention time of an existing bucket.
Configure the access token
OnSphere must access the data of the influxDB to create chart, this is done by using a API token.
Configure authentication via an API token.
Then the token must be configured in the module.analytics file.
Modify the data retention time of data
Hint
OnSphere does not support configuring the bucket retention time to prevent accidental data loss due to misconfiguration.
It is not possible to modify the retention time in the module.analytics file. The retention rule is only used when creating a new bucket. To modify the retention time, it must be done directly in the InfluxDB instance.
To access the InfluxDB instance, refer to Access to the internal InfluxDB. For modifying the retention time, see InfluxDB data retention.
Supported types of values
The value that can be saved are the following:
Decimal
Integers
Booleans
Text
Grouping values
Concept
A measurement allows grouping values based on a common criterion, such as the nature of the data or their origin. For example, sensors measuring temperature can be associated with a Temperature measurement.
This grouping permit to define a hierarchy of values to help to queries the system for displaying information
Use-cases
Group measurements by devices
Group measurements by type of data (like temperature, humidity, etc.)
Usage
Defining a measurement is done by defining a measure.ospp file.
Customize display name
Concept
A field associates a value with a name and a description that will be used to identify this value when we attempt to fetch its last states. If no field is bound to a value, the value name will be used instead.
Use-cases
Define a specific name to identify a historized value
Usage
Defining a field is done by defining a field.ospp file.
Save the current state of a value
Usage
Values can be saved by using outputs. When the output is called, it retrieves the measurement by searching for a mesure with the same ItemId as its own and retrieves the field name by either looking for the closest field to the value or, if none found, by directly using the value name.
With both of these information and with the value actual content, the output creates a new point inside the provided InfluxDB instance.
Tagging values
Concept
Tags are metadata that can be added to a value to provide additional information. These tags can be used to filter the values when fetching the last states of a value.
Use-cases
Add metadata to a value
Filter values by tags
Usage
Tags can be added to a data entry in the output.analytics file.
Fetching the last states of a value
Concepts
Retrieves values stored inside the InfluxDB instance by defining queries. Currently, only the front-end charts widgets can use these queries to display results.
Use-cases
Display the last values stored within a time range
Examples
Usage
Define a query and create a front-end dashboard with a chart widget.
InfluxDB tasks
Concept
The task.analytics file allows creating and managing InfluxDB tasks directly from the OnSphere configuration.
Each task defines:
A description (optional)
A Flux script executed by InfluxDB
The task name is not defined in the configuration file itself but inside the Flux script using:
option task = {name: "myTask", every: 2m}
All tasks created by OnSphere are automatically prefixed with osp- in InfluxDB.
Use-cases
Automate data processing using Flux scripts
Aggregate or downsample data over time
Transfer data from one bucket to another
Usage
Tasks are defined in the task.analytics file by providing a Flux script.
The script must be written on a single line due to JSON limitations.
Warning
JSON does not support multi-line strings. The Flux script must be written on a single line.
Warning
The analytics module option disableOspOrphanTasks is enabled by default (true). This means that any InfluxDB task starting with osp- that is not declared in the configuration will be automatically disabled.