Calcs & Events Tile (version 24)

Knowledge Base / Version 24 / System Admin Duties / Canary Admin

updated 6 mths ago

Active - number of active calcs/events currently running
Tags Writing - number of tags being written to the Historian
Hourly Count - number of TVQs (timestamp value quality) written to the Historian in the last hour
Daily Count - number of TVQs written to the Historian in the last day

Calc & Events Status Screen

Status Panel - displays metrics for the entire Calculation service
Calculation Status Panel - displays metrics for the highlighted calc/event
Search Bar - filters the calc/events table based on the 'NAME' column. Keywords are separated with a space and can be prepended with an exclamation mark (!) to exclude calc/events containing that keyword.
Start - starts any calc/event(s) that is selected in the table. Use Ctrl+Click or Shift+Click to select multiple calc/events.
Stop - stops any calc/event(s) that is selected in the table
Add - opens a screen to create a new calc/event
Import - imports a group of calc/events from a JSON file
Export - exports the selected calc/events to a JSON file
Calc/Events Table - displays information of all existing calcs/events and their status

Status Panel

Active Calculations - the total number of calcs/events that are running
Tags Being Written - the total number of tags being outputted by the active calculations
Events In Progress - the total number of events that are in progress
Total Event Count - the total number of individual events that exist in the database
Calculated This Hour - the total number of calcs/events that have been evaluated from the beginning of the current hour
Calculated Today - the total number of calcs/events that have been evaluated from the beginning of the day
Calculated Total - the total number of calcs/events that have been evaluated since the start of the Calculation service

Calculation Status Panel

Last Modified - the date/time of when the calc/event was last modified
Enabled - True or False, if the calc/event is running
State
- Idle
- Waiting to Start
- Waiting for Sender Session
- Validating
- Checking for Dependencies
- Waiting on Dependencies
- Initializing
- Backfilling
- Live Mode
- Stopping
- Error
- Events Database Unavailable
Started Running At - the date/time of when the calc/event started running
Run Time - the amount of time the calc/event has been running
AssetPath * - the source view name along with any subnodes of where the asset is located
AssetType * - the name of the asset type selected from the asset path
Number of Assets * - the total number of assets discovered given the selected asset type
Active Assets * - the number of assets that have outputted a value since the start of the calculation
Init & Backfill Time - the amount of time the calc/event was in an Initialization and Backfill state upon starting
Total Output Tags - the total number of tags the calculation outputs
Total TVQ's Stored - the total number of TVQ's (timestamp, value, quality) or updates stored since the start of the calculation
Total Properties Stored - the total number of properties stored since the start of the calculation
Total Evaluations Made - the total number of times the calc has been triggered to run
Last Evaluation Was At - the actual date/time of when the calc/event last evaluated
Last Evaluation Timestamp - the date/time linked to the last evaluation
Evaluations In The Last Minute - the total number of evaluations within the last minute (Now - 1 minute)
Events In Progress ** - the total number of events that are currently in progress
New Events Since Start ** - the total number of events that have occurred since the event started
Total Events in Database ** - the total number of events stored in the database
TVQs In The Last Minute - the total number of TVQs (timestamp, value, quality) that have been outputted in the last minute (Now - 1 minute)
Last Live Mode Evaluation Time - the amount of time it took the Calculations service to evaluate the last value
Avg Live Mode Evaluation Time - the average amount of time it has taken the Canary service to do each evaluation since the calc started
Max Live Mode Evaluation Time - the max amount of time it has taken the Canary service to do an evaluation since the calc started

Calc/Events Table

ACTIONS
- Start/Stop - start and stop the calc/event
- Edit - opens a window to edit the calc/event. (Double-clicking on the row will also allow the user to edit the calc/event.)
- Copy - makes a copy of the calc/event
- Delete - deletes the calc/event. (User will be prompted if they want to also delete the historical data associated with the calc/event.)
EVENTS - a "bell" icon will appear in this column for any configured event. Clicking the bell will open a new screen showing all of the current/historical events stored in the database.
STATE - the state in which the calc/event is in
- Idle
- Waiting to Start
- Waiting for Sender Session
- Validating
- Checking for Dependencies
- Waiting on Dependencies
- Initializing
- Backfilling
- Live Mode
- Stopping
- Error
- Events Database Unavailable
NAME - a unique name of the calc/event. Calcs/events can be filtered by this name using the search bar at the top of the table.
TAGS - total number of tags that have been outputted since the calc last started
RUNNING SINCE - date/time of when the calc/event started running
LAST EVALUATION - date/time of when the calc/event was last evaluated
LAST TVQ - date/time of last TVQ (timestamp, value, quality) that was outputted by the calc
ASSETPATH * - source view and path of an asset-based calc/event
ASSETTYPE * - name of the asset used in conjunction with the asset path for an asset-based calc/event

*These fields are only applicable if the calc/event is asset-based. Assets must be defined within a Virtual View of the Canary Views service.

**These fields are only applicable for events.

Calculation Group Status Screen

The Calculation Group Status screen is where users can create and configure calculations and/or events. Multiple calc tags can be outputted from a single calc group provided they are independent of each other. If a calc tag is dependent upon another, it should have its own separate configuration.

STATUS

The 'STATUS' panel contains metrics for ALL calcs/events that are configured in the Calculation service.

Active Calculations - total number of calcs/events that are running
Tags Being Written - total number of tags being outputted by the active calculations
Events In Progress - total number of events that are in progress
Total Event Count - total number of individual events that exist in the database
Calculated This Hour - total number of calcs/events that have been evaluated from the beginning of the current hour
Calculated Today - total number of calcs/events that have been evaluated from the beginning of the day
Calculated Total - total number of calcs/events that have been evaluated since the start of the Calculation service

CALCULATION STATUS

The 'CALCULATION STATUS' panel contains metrics for the current calc/event that is opened.

Last Modified - date/time of when the calc/event was last modified
Enabled - True or False, if the calc/event is running
State
- Idle
- Waiting to Start
- Waiting for Sender Session
- Validating
- Checking for Dependencies
- Waiting on Dependencies
- Initializing
- Backfilling
- Live Mode
- Stopping
- Error
- Events Database Unavailable
Started Running At - date/time of when the calc/event started running
Run Time - amount of time the calc/event has been running
AssetPath * - source view name along with any subnodes of where the asset is located
AssetType * - name of the asset selected from the asset path
Number of Assets * - total number of assets discovered given the selected asset type
Active Assets * - number of assets that have outputted a value since the start of the calculation
Init & Backfill Time - amount of time the calc/event was in an initialization and backfill state upon starting
Total Output Tags - total number of tags the calculation outputs
Total TVQ's Stored - total number of TVQ's (timestamp, value, quality) or updates stored since the start of the calculation
Total Properties Stored - total number of properties stored since the start of the calculation
Total Evaluations Made - total number of times the calc has been triggered to run
Last Evaluation Was At - actual date/time of when the calc/event last evaluated
Last Evaluation Timestamp - date/time linked to the last evaluation
Evaluations In The Last Minute - total number of evaluations within the last minute (Now - 1 minute)
Events In Progress ** - total number of events that are currently in progress
New Events Since Start ** - total number of events that have occurred since the event started
Total Events in Database ** - total number of events stored in the database
TVQs In The Last Minute - total number of TVQs (timestamp, value, quality) that have been outputted in the last minute (Now - 1 minute)
Last Live Mode Evaluation Time - amount of time it took the Calculations service to evaluate the last value
Avg Live Mode Evaluation Time - average amount of time it has taken the Canary service to do each evaluation since the calc started
Max Live Mode Evaluation Time - max amount of time it has taken the Canary service to do an evaluation since the calc started

*These fields are only applicable if the calc/event is asset-based. Assets must be defined within a Virtual View of the Canary Views service.

**These fields are only applicable for events.

Configuration

Name - a unique name identifying the calc/event
Asset Path - (optional) allows the user to select a specific source view and path for the calculation. Doing so will refine which tags are available within the 'Tags' list on the right.
Asset Type* - (optional) the asset type within the 'Asset Path' that will be used to apply the calculation to. This is only applicable if a Virtual View has been created in the Canary system that contains defined assets. See Creating a Virtual View.
As soon as an 'Asset Type' is selected, an 'Asset Tags' tab will appear in the right panel from which to select asset tags from.
Meta - properties assigned to ALL output tags in the calc group. A property name and its value are separated by a double colon (e.g. Description::Volt Meter). Multiple properties are separated by a double semi-colon (e.g. Description::Volt Meter;;Eng Units::volts). Properties can be assigned using two methods:
1. Explicitly defining the property names and their values
  PropertyName1::PropertyValue1;;PropertName2::PropertyValue2;;
2. Borrowing the property value from another tag
  PropertyName1::[SourceTagName].SourceTagPropertyName1;;PropertyName2::[SourceTagName].SourceTagPropertyName2;;
Backfill To - date/time the calc/event will backfill to upon initially starting. A Data Range will appear next to the date/time picker once an expression is created and the Evaluate button is clicked. This data range indicates the history of data available for the input tags used in the calculation.
Frequency - the frequency at which the calc/event is triggered
1. Value Change - the calc/event is triggered when any tag in the expression changes or when specific tags change, depending on what tags are selected
2. Periodic - the calc/event is triggered on a set 'Interval' (1m, 1 hour, 1 day, etc.). An optional 'Offset' can be used to offset the interval. In the example below, the calc is set to run once a day at 6am.
Enable Time Extensions - allows for the last calculated value to be time-extended in the historian until the next value is calculated. Virtual time extension occurs approximately once a minute.
Delay - an amount of time the calc is delayed to prevent miscalculations due to different data stream rates. This delay should be set >= the highest latency stream in the calculation. This delay does NOT alter the timestamp of the output tag.
- If a calculation is configured to trigger on Value Change the delay takes into consideration the current local time and the timestamp of the input value that triggered the calculation. If the difference between the input timestamp and current time exceeds the configured delay, the calculation will trigger immediately. A longer delay may be needed.
- If a calculation is configured to trigger Periodically, the calculation will occur after the delay expires.
Remove Old Data - if checked, old calculated data will be removed from the Historian and the backfill process will restart using the 'Remove From' date/time as its starting point. Any data before the Remove From date/time will be left intact.

Calculation Expression

Evaluate - performs a test evaluation of the expression using the current values for all tags
Asset * - only visible if an 'Asset Type' is selected from above. Switching between assets will trigger the calc to reevaluate the expression for the given asset instance.
Output path Asset levels * - only visible if an 'Asset Type' is selected from above. Controls the number of branches within the asset path to include in the output tag name, counting from the end of the asset path
Details
- Visible - all expressions are visible
- Visible When Selected - only the selected expression is visible where other are collapsed
- Collapsed - all expressions are collapsed
+ (Add) - adds another blank expression to the calc group
Variable name - (optional) the field to the left of the "=" sign. The variable name to assign to the expression for use in subsequent expressions. Only alphanumeric characters are allowed, and only letters are allowed for the first character.
Calculation Expression - the field to the right of the "=" sign. The expression used to determine the output of the calculation. Expressions can be copied and deleted using the icons.
Quality Override - allows the quality of the output tag to be overwritten
- Condition - a conditional expression used to override the quality based on the true and false boxes
- If true - the quality to be used if the 'Condition' is true. Values can include: Good, Bad, Uncertain, NoData, NoOutput, or any expression that returns a valid numeric quality.
- If false - the quality to be used if the 'Condition' is false. Values can include: Good, Bad, Uncertain, NoData, NoOutput, or any expression that returns a valid numeric quality.
Tag - the tag name that will be outputted from the calculation. The tag must be prepended with a DataSet name. If the DataSet does not exist, it will be created upon startup of the calculation. If the calculation is asset-based, the tagname must include %Asset%. This acts as a wildcard which will be replaced with each asset instance as it appears in the 'Asset' drop-down list when it is written to the Historian.
- DataSetName.TagName
- DataSetName.%Asset%.TagName
Type - the data type of the output tag. If a data type is not selected, the service will default to the type that best fits the value.
TS (Timestamp) - allows the user to override the timestamp of the output value using a relative time. Timestamps can be normalized to the second (s), minute (m), hour (h), day (d), week (w), month (month), and year (year). For example, a timestamp of "d" would normalize to midnight of the current day. "d-1d+1h" would output a timestamp of yesterday at 1:00am.
Meta - properties assigned to the output tag. This follows the same syntax as the 'Meta' field above. Properties listed here are only applied to the individual output tag, whereas the Meta field above applies properties to ALL output tags within the calc group - if the calc is outputting multiple tags.
Event - allows the user to create an event using the configured expression. (Note: An expression does not need to generate an output tag in order to create an event.) See How to Create an Event for more details.
- Is Event Start Trigger - starts the event whenever the expression returns True. If an End Trigger is not configured, the event will end when the Start Trigger returns False.
  - Min Duration - the amount of time that must pass with the expression in a True state before an event is triggered (Ex. 1 minute (1m), 1 hour (1h)).
  - Notify Email - a comma delimited list of email addresses to send an alert to indicating the event has been triggered
- Is Event End Trigger - ends the event whenever the configured expression returns True
- Is Event Start and End Trigger - starts and ends the event whenever the configured expression returns True
- Is Event Property - used to attach properties to the event. Properties MUST be assigned to a variable and contain the string 'EventDuration' for the duration parameter of the aggregate function. For example,

Functions

A list of all supported functions and aggregates. Hovering over a function will display a brief description for that particular function. Selecting a function will also provide a description below the list, as well as provide the syntax and format the function is expecting. Click the '+' next to the function to add it to the expression. Functions can be filtered using the Search bar.

Asset Tags *

A list of all asset-based tags available for the selected 'Asset Type'. (Note: This tab is only visible if an Asset Type is selected.) Click the '+' next to the tag to add it to the expression. Tags can be filtered using the Search bar.

Operators

A list of all supported operators. Hovering over an operator will display a brief description for that particular operator. Click the '+' next to the operator to add it to the expression.

*These fields are only applicable if the calc/event is asset-based. Assets must be defined within a Virtual View of the Canary Views service.

Calc & Events Settings Screen

Endpoints

IPC - endpoint used by a local Views service to read events
gRPC Admin (55340) - endpoint used specifically by the local Admin service for configuring settings and requesting status information

Settings

SERVICE SETTINGS

Delayed Start Time (seconds) - a general delay from when the service starts until calculations/events are evaluated
Destination Historians - a comma delimited list of Historian machine names where calculations will be written to
AssetInstanceCount Read Interval (seconds) - the frequency at which the service evaluates the total number of all asset instances for each asset type to be used in the 'AssetInstanceCount' function
Property Read Interval (minutes) - the frequency at which the service evaluates the properties of each tag to be used in the 'Property' function
Check for New Assets Interval (minutes) - the frequency at which the service checks for new assets that have come online
Views Service Reconnect Delay (seconds) - the frequency at which the Calculation service tries to reconnect to the Views service after a disconnect
Max backfilling calculations - a throttling mechanism used to limit the max number of calculations that are permitted to backfill simultaneously
Restart Failed Calculations Interval (minutes) - how frequently calculations in the "Error" state are restarted
Live Data Read Interval (milliseconds) - how frequently live data is retrieved from Views
SaF Keepalive Interval (seconds) - how frequently a keepalive request is made to SaF
SaF Reconnect Interval (seconds) - how quickly to reconnect to SaF when the connection is lost

IDENTITY

Identity API Token - token used to authorize tag access when the Views or SaF service is remote from the Calculation service. This token must be mapped to a user who is in the Views>BypassSecurity access control list within the Identity tile>Security>Access Control Lists screen.

EVENTS DATABASE SETTINGS

Provider - the method for storing the Events database
1. SQLite - by default, events will be stored in C:\ProgramData\Canary\Events\CanaryEvents.sqlite
2. MSSQL - events will be stored in a Microsoft SQL database determined by the remaining parameters. (See Storing Events in an External SQL Database)
Server - the machine name of the SQL server that will store the events
Name - the name of the database in which the events table will be created
User/Password - the credentials used to authenticate and write to the SQL database
Is Domain User - determines if the configured user is a domain user