Skip to content

InfluxDB historians

The InfluxDB v2 Historian and the InfluxDB v3 Historian write the values of the tags in the collections you select to an InfluxDB server, and allow that history to be read back out through the APIs. They sit in the Historians category. Each recorded value belongs to a tag, identified by its tag tree path.

Use the InfluxDB v2 Historian if your InfluxDB server stores data in buckets that belong to an organisation. Use the InfluxDB v3 Historian if your InfluxDB server stores data in a single database. Both authenticate with a token. InfluxDB Cloud is supported as well as a server you host: enter the Cloud URL and a token in the same way.

flowchart LR
    subgraph Profinity["Profinity"]
        Tags --> Collections["Tag collections"] --> Historian["InfluxDB historian"]
    end
    subgraph Server["InfluxDB server"]
        Store["InfluxDB"]
    end
    Historian --> Store
An InfluxDB historian writes the tags in the selected collections to the InfluxDB server, and the APIs read the history back

Licence required

The InfluxDB v2 Historian and the InfluxDB v3 Historian require the Historians licensed feature. Refer to Licensing for the editions that include them.

Use the InfluxDB v2 Historian only with an InfluxDB v2 server, and the InfluxDB v3 Historian only with an InfluxDB v3 server. The component type must match the InfluxDB version, and a mismatch causes connection failures. Historians explains how to choose.

Adding an InfluxDB historian

To start recording, install InfluxDB v2 or v3 and confirm that it is running, then:

  1. Add an InfluxDB v2 Historian or an InfluxDB v3 Historian to your profile from the Historians category.
  2. For the v2 historian, enter InfluxDB Bucket, InfluxDB Organisation and InfluxDB Token. For the v3 historian, enter InfluxDB Database and InfluxDB Token.
  3. Under Collections, add at least one tag collection. The component does not start until one is configured.
  4. In Influx Server URL, enter the endpoint URL that InfluxDB is running on, or keep the default http://localhost:8086/.

Settings cannot be saved while a required field is empty.

These settings identify where the data is stored, and differ between the two historians.

Setting Applies to Default Purpose
InfluxDB Bucket InfluxDB v2 Historian None The InfluxDB bucket that the data is stored in. Required.
InfluxDB Organisation InfluxDB v2 Historian None The InfluxDB organisation that owns the bucket. Required.
InfluxDB Database InfluxDB v3 Historian None The InfluxDB v3 database that the data is stored in. Required.

These settings are the same on both historians.

Setting Default Purpose
InfluxDB Token None The security token of the InfluxDB user that Profinity connects as. Required, and stored encrypted.
Influx Server URL http://localhost:8086/ The endpoint URL that InfluxDB is running on.
Dashboard URL Blank The URL of the InfluxDB dashboard. Optional, and leaving it blank shows no dashboard link.
InfluxDB Health Check On Checks the health of the InfluxDB server when the component connects and again about every 30 seconds while it runs. Turn it off for InfluxDB Cloud.
Collections None The tag collections whose tags are recorded. At least one collection must be configured before the component starts.
Update Interval (Seconds) 10 The interval, in seconds, at which data is sent. From 1 to 86400.
Logging mode Snapshot Sets what is sent on each interval: Snapshot, On Change or Everything. Refer to Logging modes.
Auto Connect On Starts the historian when the profile is loaded. When off, start it with Start Logger.
Allow Retrieval On Allows data to be retrieved through this historian using the APIs.
Designated tag historian reader Off Makes this historian the store that long-range tag and history queries are read from. Enable it on one component in the profile only, and it takes effect only while Allow Retrieval is on. Refer to Historians.

Every sample is written with its quality in a quality field. A Good sample also has a value field, and a Stale sample keeps its last value with quality Stale. A tag that is Unavailable or Bad is written as a gap, with a quality field and no value, so a chart can show the gap instead of an invented reading. Only tags that hold a number are written, and a query for readings should ask for the value field.

What is stored

Each sample is stored as one point in a measurement named after the profile. For example, a motor speed signal on a component called Inverter is stored like this:

Part Example Meaning
Tag component Inverter The component that owns the tag.
Tag message Status The CAN message the signal belongs to.
Tag signal Speed The signal name.
Tag full_tag_id Inverter/DBC/Status/Speed The tag's path when the sample was written.
Field value 23.4 The reading.
Field quality Good The quality of the reading.

In InfluxDB line protocol, that point is:

MyProfile,profile=MyProfile,component=Inverter,message=Status,signal=Speed,full_tag_id=Inverter/DBC/Status/Speed value=23.4,quality="Good" 1792315200000000000

The component, message and signal tags identify the tag in the history. A CAN signal is stored under its component, message and signal names from its DBC file, and a component property is stored with the message _Property_ and its dotted name as the signal, for example Settings_Name. Any other tag is stored with the message _TagPath_, and its place inside its component, joined with underscores, as the signal. Characters other than letters and digits in these names are replaced with underscores.

InfluxDB Cloud does not support the InfluxDB Health Check API, so turn off InfluxDB Health Check when InfluxDB Cloud stores your data. For the full procedure, refer to How to Log Data to the Cloud (InfluxDB).

If data does not arrive

The Profinity system logs name the cause, and Logs describes where to read them. When the component cannot connect, it logs one error for the outage, in the form <component name>: could not connect (<reason>). Retrying every 5 s. The reason tells you what to check:

Reason in the log Meaning
credential validation failed (likely an invalid token) The token is wrong or lacks access.
the health check failed (InfluxDB Cloud has none; switch Health Check off in the settings) The server did not answer the health endpoint. Turn InfluxDB Health Check off for InfluxDB Cloud.
Any other text The connection failed for another reason, and the text is the underlying error. Check the Influx Server URL first.

For the steps to set up data logging, refer to How to Configure Data Logging. InfluxDB v1 servers use the InfluxDB v1 Logger, which is described in InfluxDB v1 Logger.