Quick Start Guide (version 22)

An Overview of the Canary System

The Canary System installer consists of three component groupings:

• Historian Server
• Data Collectors
• Client Tools

If following best practices, data collection tools should be installed on a different machine than the historian and other Canary tools.  

The Canary Data Collectors should be installed as close to the data source as possible.  This likely means you will install the Canary Collectors, Canary Admin Service, and Sender Service on your OPC Server, MQTT Broker, or SCADA server.

Additionally, the Canary Historian Server software components should be installed on their own stand-alone VM or physical server.  Note, not all components are pictured.  A complete architecture of all Canary software components can be found in more in-depth architecture articles.

Installation

The same installation program is used for all parts of the Canary System.  Typically, different modules are installed based on the purpose of the server.  These purposes usually are:

• Data collection
• Data storage and contextualization
• Client tools for reporting

Data Collection Installation

Data collection from a data source involves the following components and is recommended to be done on a separate server or VM than the Canary Historian itself.

1. Use the received download link to download the Canary Installer from a Canary representative.
2. Run the file 'CanaryInstaller-*.*.*.exe' with elevated privileges.
3. Select the system modules you desire to install and deselect modules not appropriate for the desired solution.  You must install the following:
   • Canary Admin Service (required)
   • Store & Forward (required)

     Note, some components will not be able to be deselected as they are required based on other components that are currently selected (e.g., 'Sender' and 'Canary Admin Service/Client' are required for 'Store & Forward').

4. You should then choose which of the Canary Data Collectors are appropriate for your use case and install them accordingly:
   • OPC DA
   • OPC UA
   • MQTT
   • CSV
   • SQL
   • CygNet
5. Select 'Install' and complete the installation.
6. When the status bar is solid green and the 'Success' message appears, the installation is complete. Note, Canary will automatically stop and restart its services which will cause a pause during the installation. This is normal.

Above is an example of an install specifically for OPC UA data collection.  

Canary Historian Installation

1. Use the received download link to download the Canary Installer from a Canary representative.
2. Run the file 'CanaryInstaller-*.*.*.exe' with elevated privileges.
3. Select the system modules you desire to install and deselect modules not appropriate for the desired solution. Typically, the following modules are installed on a dedicated machine for the Canary Historian:
   • Historian
   • Canary Admin Service
   • Sender
   • Receiver
   • Virtual Views
   • Calc & Events
   • Axiom (refers to the Axiom Core, not an Axiom client)
   • Publisher

     Note, some components will not be able to be deselected as they are required based on other components that are currently selected (e.g., 'Store & Forward' will remain selected when the 'Sender' is selected).

4. Select 'Install' and complete the installation.
5. When the status bar is solid green and the 'Success' message appears, the installation is complete. Note, Canary will automatically stop and restart its services which will cause a pause during the installation. This is normal.

Above is an example of the recommended modules for a Canary Historian server with data collection occurring remotely. 

Client Tool Installation

Data queries can be made via the Excel Add-in client, the ODBC client, and the Axiom client tools.  Only Excel Add-in and ODBC require installation.  Axiom runs with a web browser and does not require installation.  The Axiom component listed under Historian Server refers to the Axiom Core that needs to be installed as part of the historian server.

1. Use the received download link to download the Canary Installer from a Canary representative.
2. Run the file 'CanaryInstaller-*.*.*.exe' with elevated privileges.
3. Select the system modules you desire to install and deselect modules not appropriate for the desired solution.  Choose from the following:
   • Excel Add-in
   • ODBC Client

     If installing the ODBC Client, make sure that the module 'ODBC' has been installed on the historian server.

4. Select 'Install' and complete the installation.
5. When the status bar is solid green and the 'Success' message appears, the installation is complete. Note, Canary will automatically stop and restart its services which will cause a pause during the installation. This is normal.

Licensing

Canary Historian

• The Canary Historian can either be licensed for a specific number of tags or have the tag license removed for an 'unlimited' tag license.
• Tag licenses are consumed by tags being logged to the system as well as by tags generated through the Calculation Service. Virtual Views (formerly known as Asset Models) do not consume tag licenses.
• A tag's license can be revoked and applied to another tag by modifying data collection. Doing so does not purge the tag from the historical archive, but does limit clients from being able to query the tag or its historical record.

Axiom and the Excel Add-in

• Canary Systems now come with unlimited Axiom and Excel Add-in clients.

API Connector

• Version 20.0+ of the Canary System provides 25 concurrent API licenses free of charge. Should more concurrent license be required, contact your Canary representative. Additional licenses are free.

ODBC Connector

• ODBC licenses are applied by the Canary System on a one per server ratio. This allows for unlimited client queries without adding additional licensing.

Licensing with Internet Access

1. Open the Canary Admin application and select the 'Licenses' tile.
2. Find the 'ADD LICENSE THROUGH INTERNET' section on the right side of the screen.
3. Enter the required information.
4. Enter the Serial Number provided by your Canary representative.
5. Select the checkbox for all purchased products of the Canary System. By default this would be Canary Historian, Axiom, and Excel Add-in. The API Connector need not be licensed unless more than 25 concurrent connections are needed.
6. Select 'GET LICENSE'. The 'License Key' populates automatically and now the selected products are accessible.

Licensing without Internet Access

1. Copy the License Code from the 'ADD LICENSE MANUALLY' window. This code is dynamic and will change.
2. On a device connected to the Internet, navigate to canarylabs.com/support/license
3. Enter the required information, including the Serial Number provided by your Canary representative, the parts you wish to license, and the quantity. Select 'Submit'.
4. A license key appears. Enter the License Key information in the 'License Key' field.
5. Select 'Accept Key'. The Canary product(s) are now licensed.

Create DataSets

Storage Methodology

Canary has designed its solution to eliminate the need of a database administrator to manage the Historian. To achieve this, Canary uses a simple but elegant method to segment the data in two ways.

First is the creation of DataSets, or a group of tags with logically associated data. DataSets play a key role in logging, storing, and reading data. Before creating a new logging session, the admin must select a DataSet in which to send data.

Second is the Historical Database (HDB) file, segmented by time periods. These two organizational structures allow for database expansion without effecting performance or requiring any management of size or duration.

Generally, a new HDB file is created daily. Once closed, each HDB goes through loss-less compression to minimize Historian’s storage requirements. Canary stores data using lossless data compression to ensure data written to the Historian is identical to the data later read from it. Canary algorithms achieve a data compression rate beyond sixty percent.

Each HDB file contains tag names, tag properties, and TVQ units comprised of a timestamp, a value, and a quality score. Values can include Booleans, Integers, Floats, Doubles, or Strings. Canary writes all three TVQ components together ensuring the value is always paired with the correct timestamp and quality.

How to Create a New DataSet

A DataSet can be created manually within the Historian itself, or automatically, depending on the Canary Collector being used. The following steps show how to create a DataSet manually through the Historian.

1. Open the Canary Administrator application.
2. Select the 'Historian' tile, then 'Configuration', then 'NEW'.

3. Name the DataSet with a unique name that does not begin or end with a 'space' and avoids the following characters:

   Colon	:
   Equals	=
   Forward Slash	/
   Asterisk	*
   Backwards Slash	\
   Percentage Sign	%
   Question Mark	?
   Greater than or equal to	< >

4. By default, all DataSets are stored in 'C:\Historian Data'. In the 'Path' field, type a new path or select 'Browse' to change the directory location of the data for the DataSet.
5. Select 'CREATE' when finished.
6. Adjust the 'SETTINGS' available within the right window (described below).

Keep the total number of DataSets below 300 and maintain less than 40,000 tags per DataSet. While there are no hard limits coded into the historian, increasing beyond these numbers may result in performance issues or errors.

DataSet Settings

Dataset Directory

The 'Dataset Directory' parameter displays the location of where the HDB files are stored for the selected DataSet. If wishing to change this location, an admin would need to:

1. Stop the Historian service
2. Move the HDB files to its new desired location
3. Edit the C:\ProgramData\Canary\Historian\Historian.ini file and update the 'path' parameter of the particular DataSet with the new location.
4. Start the Historian service

If wishing to change the storage location for ALL DataSets, see How to Change the Data Historian Location.

DataSet Validation Configuration

Background validation checks all DataSets for unvalidated HDB files. An unvalidated HDB file is indicated by a clock in the top left hand corner of the tile as shown on the Dec-22 HDB file below. 

By default, background validation is turned on. The background validation process may consume additional machine resources but ensures that HDB files do not contain incomplete or corrupt data values. 

A file remains unvalidated while it is still open for logging.  Typically files are validated each night as they 'Roll-Over'. It is not recommended to uncheck background validation.

Configure Email Notifications for DataSets Not Logging Data

The Historian can be configured to send an email to the system admin(s) if a DataSet has not received any data in the specified period of time. 

1. Select the 'Email if no data received in' checkbox and configure the number of minutes. 
2. Designate the user(s) to whom the email will be sent to. Multiple recipients are separated with a comma.
    
3. Configure the Canary system to send email alerts.

Enabling this feature is a recommended precaution for monitoring the network connection break between the Sender and Receiver, monitoring the status of a logging machine, or ensuring that logging equipment maintains functionality.  

Configuring the Roll-Over Frequency for a DataSet

A Roll-Over occurs when a new HDB file is created. To ensure data integrity, it is recommended to roll-over files daily.

• When an HDB file is open for writing, it could potentially become corrupted; thus the longer an HDB file is open for writing, the greater the potential for data loss.
• Data corruption can be caused by power outages, machine restarts, and other service disruptions. 

Setting the Roll-Over to daily is a recommended best practice to take to ensure your data remains secure despite unexpected network failures. 

Configuring the Roll-Up Frequency for a DataSet

The Roll-Up setting determines how often individual HDB files get condensed into one 'rolled-up' file. A rolled-up file is either daily, weekly, monthly, or quarterly depending on how many HDB files the system administrator wishes to condense.

HDB file roll-ups lessen storage space by deleting redundant tag names and metadata property descriptions from multiple HDB files.

• For example, instead of listing Tag0001 in thirty separate HDB files, a monthly roll-up lists Tag0001 in one monthly file while retaining all of Tag0001's TVQs from the last thirty days.
• The historian will not allow a single HDB file to grow beyond 500 MB. If, through the process of rolling up daily files, a file were to exceed this limit, an additional weekly/monthly/quarterly file will be created.

The Roll-Up feature is off by default. It is not necessary, but an Admin may want to condense many HDB2 files to save some storage space. The Roll-Up feature can be most effective when using large numbers of DataSets with smaller tag counts.

Logging Data

Data Collectors

Choose the Knowledge Base article below based on the data collector you wish to use.

OPC UA

MQTT Sparkplug

OPC DA

Canary Module for Ignition

SQL

CSV File Import

Trending Data

Now that you are logging data and storing it to a DataSet, you can trend your data in Axiom.

To learn how to use the Axiom tool, visit the Canary Academy and register for the Axiom Trending module.

Launching Axiom

Launch a web browser from a machine that has network access to the Canary Historian Server.

Enter the machine name of the Canary Historian Server as the web address followed by a forward slash. For instance, if the server name is ‘CanaryHistorian’ enter the following for an anonymous unsecure connection – canaryhistorian/.

Add ‘https://’ to the beginning of the address if security is enabled.

You can now begin to use Axiom.

To download a thin-client version of Axiom that does not require browser access, click the user name in the upper right-hand corner and select ‘Download App’.

Follow the install procedures and run the Axiom application.