This article is a general overview of Canary, and details setting up Canary Historian in Ignition and troubleshooting tips.
What is Canary?
Canary Labs provides software that handles time-series data historians and visualizations for SCADA processed data. The Canary System can be broken down into three main components:
- Collect & Store
- Context to Data
- Maximize Operation
This article will focus primarily on setting up a Canary Historian and how the Canary module can store and display historized tag data from Canary inside of Ignition. Keep in mind that Canary Historian is a NoSQL time-series database, which means it’s different from the common SQL historical providers such as MySQL, MSSQL, etc.
Before getting started, the following prerequisites must be met:
- Licensed Tag Historian module (both query and store)
- Canary Historian module (free)
- Canary Administrator application
- Obtain a temporary License Key (to be able to use the Canary Services)
Note: Reach out to Canary Labs Support to get both the latest downloadable file for the Canary Administrator application and the license key
How Does Canary Historian Work?
The following image shows a general architecture setup that is referenced throughout this article.
In this guide, the relevant Canary services are installed locally to the same machine as Ignition. However, as per Canary’s documentation, it is considered best practice to install the Canary Historian server on a separate machine for better data buffering, but for demonstration purposes, the Historian service lives on the same machine as Ignition.
The Canary module currently utilizes their own Sender Web API protocols to collect and forward data to the Historian and the Views Web API protocols to retrieve historical data from the Canary Views. From the module, the Canary Collector collects and stores historized tag data whereas the Canary Provider acts as a historical Tag Provider to retrieve raw or processed data from Canary.
Storage Process
The Gateway can have more than one Canary Collector configured. The Collector on the Gateway and Canary’s Sender service work in tandem to log data and push them to the Receiver service. The Receiver then forwards the data to Canary’s Historian.
Ignition → Collector → Sender (Web API) → Receiver → Canary Historian.
Note: Canary Labs also recently introduced a new service called Store and Forward (SaF) in Canary version 24 which replaces the Sender/Receiver services. However, the Canary Historian module as of 23.0.1 still uses the Sender and Receiver services to store data points to the Historian.
When configuring a collector on the Gateway, there’s a DataSet property which needs to be specified so the Collector can log data to that DataSet.
Once the Historian receives the data from a Collector, they will be organized into the respective DataSet folder. A DataSet folder is a collection of tags that the Historian creates and writes to a historical database (HDB) file that includes tag names, values, and qualities, as well as other meta properties like descriptions, engineering units, and limits. A new HDB file is generated daily for all existing DataSets if data is being logged.
In this example, the “Folsom” DataSet contains 67 HDB files, which are based on the number of days the Collector has been forwarding tag data to the Historian:
Looking into the Sep 06 2024 tile/folder, you will see the timestamp, value, quality (TVQ) and data type of all the tags that were historized for that day.
In the Gateway Logs, setting the com.canarylabs.ignition.api.SenderServiceAPI logger to TRACE allows you to see the POST request being sent with the parameters (i.e. tag metadata, userToken) and the POST response stating whether storage was successful or not.
Retrieval Process
In Canary, the Views Service acts as the central communication hub between third party client applications and the Historian. All of the data aggregation/calculations are processed at the View level based on the client’s request. In this scenario, Ignition is the client sending requests to Canary to retrieve historical data from the Historian.
The Views Tile inside Canary Administration will show a collection of Views/Virtual Views that are created for the local Canary Historian.
Each View will have a collection of DataSets, similar to the ones from the Historian Tile.
Navigating further into a DataSet, you will see a list of tags with the ability to access and filter raw and processed tag data.
For example, below is a Power Chart trending historical data for a single tag between 9am and 11am requesting 300 data points with the default aggregation mode.
In the Gateway logs, set com.canarylabs.ignition.api.ViewsServiceAPI and com.canarylabs.ignition.CanaryHistoryQueryExecutor to TRACE to see the sequence of events for the retrieval process for the Power Chart.
Downloading Canary Historian Module
The Canary Historian module supports Ignition versions 8.1.5 and up. Once the Canary module is installed on the Gateway, you should see the “Configure Collectors” and the “Configure Providers” options listed under the Canary section of the Config page.
The Canary module for Ignition is built on top of the Ignition’s Tag Historian module so the process of enabling history for tags is the same. The module also uses both Ignition’s and Canary’s Store and Forward system when collecting/storing data points to the Canary Historian. This guide uses Canary Module version 23.0.0 and Canary software version 21.5.0.
Downloading Canary Services
On the same machine, run the Canary System Installer file you’ve received from the Canary Support. You should see an Installer popup asking to select which services to install.
- On the installer’s Individual Components tab, select the Historian, Canary Admin, Sender, and Receiver services. (If you'd like, you can choose to download any of the extra services.)
- After the installation is complete, you should see a green Success message.
- Launch the Canary Administrator application. You will see all of the services you’ve selected for installation in this application.
- To apply the Canary License Key, navigate to the Licenses tile. Licenses are retrieved using the serial number obtained from your Canary representative.
On the Licenses page, enter the serial number, email address, quantity, select the appropriate services and click on the Get License button.
- After the license is pulled, you will see a similar Licenses screen that states the services covered by the license, as well as how many days remaining until usage expires.
Setting up Sender Service | Canary Admin
You must configure the Sender service in Canary Admin first for the Canary Historian to collect the data sent from Ignition.
- Navigate to the Home tab and select the Sender tile. Then, go to the Configuration tab.
- Navigate to the Endpoints section on the left side of the Configuration page, and enable Http - Anonymous (Web API). Keep Port as the default 55253 and click Apply.
Since the Sender Service is installed locally to the Ignition Gateway, you can disable security by enabling the Http - Anonymous endpoint and making sure that port is available.
- Additionally, we will need to add “Anonymous Logon” as a user to access the Sender service. Navigate to the Access tab on the left side of the Configuration page and click on Add.
- Type “Anonymous Logon” under the Windows Active directory lookup and select Check Names. Once the machine locates the user, click Ok.
- Make sure to save the configuration changes by clicking Apply.
Setting Up Canary Historian on the Gateway
Creating a Canary Collector
Now that you disabled security and allowed an Anonymous user to access the Sender Service endpoint, you can set up a Canary Collector on the Gateway.
- On the Gateway Webpage, navigate to Config > Canary > Collectors and click Create new Collector:
- Fill out the Name and Sender Service fields, and set Anonymous to true. For the Sender Service field, use “localhost” since it’s installed locally to the Ignition Gateway.
- You can skip the Username and Password fields since you disabled security. In the Historian field, use “localhost” since the Canary Historian is also installed locally to Ignition. For the DataSet field, you can give it any name you like. DataSets are essentially just folder structures that get created at the highest level inside of Canary to group a bunch of tags.
- After creating the Canary Collector, you will see a new Sender Service session popup in the Sender tile in the Canary Admin application. The session will show up as Idle and Disconnected state at first because you have not configured any tags to be collected and stored.
Note: In order to maintain an active Sender Session API, tag values must be changing. Otherwise, it will put the Sender Session into an Idle state.
Enabling Tag History
Now that you have a Sender Service API established through our Canary Collector, you can enable tag history on tags from Ignition to be stored into Canary Historian. For this example, enable history for a single Sine OPC tag from a simulator device.
- Open the Tag Editor in the Designer, navigate to the History category, set the fields History Enabled to true and Storage Provider to canarycollector. Leave the other fields with the default values and click OK.
- Navigate back to the Canary Admin and select the Sender tile. Notice that our Sender Service session is now active and is collecting live tag values.
- To locate the tag and values being recorded, navigate to Home and select the Historian tile. Then select the corresponding Dataset name(Ignition) previously configured in the Canary Collector provider settings.
- After selecting your Dataset folder, select the corresponding date folder that contains all the tag values collected and stored for that day:
- You can then select a tag to view the stored tag values and other information.
Creating a Canary Provider
Since we’re able to see data being collected by the Canary Historian, we can now set up a Canary Provider to query and display the data points in Ignition.
- On the Gateway Webpage, navigate to Config > Canary > Provider and select Create new Provider.
- Fill out the History Provider Name, Hostname, Port fields, and set Anonymous to true. Specify “localhost” in the Hostname field since the Canary Historian is installed locally to the Ignition Gateway. Click Save Changes.
Displaying Tag History from Canary
Now that we have a Canary Provider configured, you can now pull and render historical data in Ignition from Canary. Below are some examples shown in Vision and Perspective components.
Vision Easy Chart
Create an Easy Chart component in Realtime chart mode and configure a new Tag History Pen through the Easy Chart Customer.
For the Tag Path, look for the canary provider name and the same tag with Tag History enabled in the previous example in this article.
Perspective PowerChart
Create a new PowerChart component and browse for the same tag under CanaryHistorian historical provider.
Troubleshooting with Canary Historian
The first step when troubleshooting is to isolate whether the issue is caused by Ignition or the Canary module. Understanding the general architecture between Ignition server and the Canary server will be helpful as well.
Ignition:
- Does the module work as expected when setting up a new Canary collector/provider on the Gateway?
- Where is the Canary installed and is it reachable by the Ignition server?
- Can Ignition’s host machine use ping/telnet towards Canary’s endpoint?
- Do any firewalls, anti-viruses software, or proxies exist between the two?
- Is the Canary software properly licensed?
- Issues regarding unusual Canary querying behaviors can be investigated by cross-referencing results from other SQL databases MySQL.
- Helpful Loggers:
- Tags.execution.actors.history
- com.canarylabs.ignition.api.SenderServiceAPI
- com.canarylabs.ignition.api.ViewsServiceAPI
- com.canarylabs.ignition.CanaryHistoryQueryExecutor
Canary:
- Sender and Receiver Tiles: It’s good to check to see the statuses of the sessions that are initiated and make sure that data is being forwarded to the Historian by the Receiver.
-
Messages Tile: Similar to logs, the Messages tile has the ability to filter and change the verbosity level of the log messages.
- Canary Community: Forums, Articles and Software Updates that can provide additional context with similar issues.
- Canary Support: Submit Support tickets to request further assistance with your issue once you have exhausted all resources and are confident that the issue is on Canary’s end. Canary can then effectively collaborate together to move towards a resolution.
Known Issues
Ignition
- IGN-9171 (Active) Visual Bug: Tag History Splitter connection appears as unavailable when one of the connections points to a Canary Historian. This does not affect the storing process as that functionality still works.
- IGN-8408 (Fixed in 8.1.33, Affected versions: 8.1.31, 8.1.32): Tag History storage wouldn't be accepted to a targeted DataSink if a matching Tag History Provider didn't exist.
Canary
- NPE Errors: When trying to query data from Canary DB and another DB simultaneously, a Null Pointer Exception error is thrown in the logs and/or the component. This appears to be resolved in one of the latest versions of the Canary module. (Version 24.0.1)
- Tag Actors: When editing or configuring a UDT; a timeout occurs on an API call with Canary. This looks to be addressed in one of the latest versions of Canary module where the timeout is now configurable. (Version 24.0.1)
- Bad Quality data not returned from Canary: When querying a set of data from tag history, data with bad qualities are not being returned from Canary. Even if IgnoreBadQualities is set to False. (Actively being investigated. Target version: TBD)
- Canary Interpolation: The interpolated tag history dataset produces different results when comparing queryTagHistory() records of the Canary Historian versus another DB Provider like MySQL.The expected interpolated value for the tag should be of the previous value or a value between the previous and the next value but instead we see the interpolated value of the next/new available value. This issue was addressed and should be fixed in one of their latest module releases. (Version 24.0.2)
Additional Resources
The Canary System -- Step 1: Collect & Store Your Data
Canary Coaching: Ignition Integration Part 1 of 2
The Canary System: Understanding How the Canary System Works
Comments
0 comments
Article is closed for comments.