Virtual Tag Operation
Overview
A virtual tag is a tag created by calculating values from other tags. For information on what they are and how to create them, refer to Virtual Tags in the User Guide. This page covers only what administrators need to know: where the calculation runs, when it is deployed, where failures are logged, and what factors affect performance.
One Calculation = One CEP Statement
The EQL entered in the Calculation tab of a tag is deployed as one statement in CEP.
| Item | Value |
|---|---|
| Statement ID | CALCULATION_ + tag ID (e.g., CALCULATION_TAG_V_FILTER_DP) |
| Enable/Disable Value | The use_calculation of the tag — Apply status in the Calculation tab |
| Destination of Results | A single result row becomes one point for that tag and enters the same pipeline as collection values — storage, alarms, and other calculations read it like a regular tag |
| Result Processing | When a statement produces a result, an asynchronous worker converts it into a point and places it into the pipeline |
Calculation results are the only CEP results permitted to re-enter CEP. Other CEP results are not accepted at the CEP entrance. This allows virtual tags to read other virtual tags as sources (chaining) — however, the system does not check if a calculation reads itself during storage. If a loop is created, the statement will read its own output.
Deployment Timing
| Event | Action | If Failed |
|---|---|---|
Calculation Tab Save · V5 PATCH /api/v5/tag/{tag_id}/calculation | The statement is compiled first and then saved; the old statement is removed and the new one is deployed | If compilation fails, it is not saved. If saved but deployment fails, the response is a failure — it does not report an undeployed statement as a success |
| Server Startup | All tags with use_calculation enabled are deployed 4 at a time | That specific tag is skipped and others continue to deploy. A diagnostic «Calculation Tag Deployment Failed» is triggered for that tag — See below |
| Tag Deletion | The calculation statement for the tag is removed, and the alarm settings for the tag are deleted | Even if one step fails, the next step and DB deletion continue |
| Connection Deletion | All calculations, aggregations, and alarms for all tags (including virtual tags) of that connection are removed, then deleted along with the tags | — |
Save Denied — 422
If a statement cannot be compiled during a Calculation tab save, it is denied with HTTP 422, and the cause is displayed on the screen.
| Location | Content |
|---|---|
| Guidance box directly below the EQL editor | Title «Cannot read EQL», location chip «Line N Col M», cause statement and hint, collapsed View Engine Original. The cursor moves to that position (if no position, only the statement without a chip). No separate toast appears |
Server statement (V5 response detail) | «EQL Compilation Failed (Line N Col M): …» — if no position, «EQL Compilation Failed: …» |
| V5 response extension field | reason = eql.compile, cause · compiler_message = formatted compiler statement, engine_message = original engine statement, line · col = 1-based position |
If the CEP engine is not running and cannot be checked, it returns HTTP 503, and a toast appears: «Could not verify EQL because connection to CEP engine failed.» — this is not an error in the statement, so it is not shown in the editor.
In the server log, denials are recorded as Tag calculation refused: tag_id=[…], and saves that could not reach CEP are recorded as Tag calculation not saved - CEP could not check the EQL.
The same pattern applies to all other entrances that receive EQL.
| Entrance | |
|---|---|
| Console | Tag Calculation tab · Adding/Modifying Asset Statements · Plugin Statements · Alarm Setting Save · [Execute EQL] check · Query Execution |
| V5 | Tag Formula · Asset Statement · Alarm Setting · Query Compile/Execute |
The rule is that unverified EQL is not stored in the DB. It is normal for Calculation tab saves to fail while CEP is restarting; simply save again after CEP is up.
Failures Logged in Diagnostics
When a calculation fails, it is recorded in Diagnostics in two types.
| Code | Name · Type · Severity | Message | When |
|---|---|---|---|
diagnostic.tag.calculation_deploy_failed | Calculation Tag Deployment Failed · State · ERROR | Failed to apply calculation for tag {target}({operation}): {error} | When a saved formula cannot be uploaded to the engine during startup or redeployment. One is triggered per tag and resolves automatically once deployed |
diagnostic.tag.calculation_listener_failing | State · ERROR | Calculation for tag {target} is failing. | When a statement result fails to be converted into a point. Resolves when the next result succeeds |
In the case of Calculation Tag Deployment Failed, {error} contains the statement rejected by the engine, and diagnostic arguments line · col contain the position.
The details panel in the diagnostic screen provides an «Open Page to Fix» link that goes directly to the tag's configuration form — fixing and saving in the Calculation tab redeploys it and clears the diagnostic. If diagnostic.infra.component_unreachable(cep) is also active, restore CEP first.
Since saved EQL will not run if not deployed, similar diagnostics exist per target for other areas using EQL.
| Code | Name | Target | «Open Page to Fix» Destination |
|---|---|---|---|
diagnostic.tag.calculation_deploy_failed | Calculation Tag Deployment Failed | Tag | Tag configuration form |
diagnostic.tag.alarm_deploy_failed | Tag Alarm Deployment Failed | Alarm Setting ID (Tag is tag_id) | Alarm setting form |
diagnostic.asset.statement_deploy_failed | Equipment Statement Deployment Failed | asset_id/statement_name | Statement tab of the asset |
If one of timestamp · value · quality · error_code is missing from the result row, or if value is empty, a warning log is recorded rather than an error, and the result is discarded. If virtual tag values are not being generated but diagnostics are quiet, search for Calculated point validation failed in the server log.
Performance
| Factor | Reason |
|---|---|
| Number of Virtual Tags = Number of CEP Statements | Each virtual tag runs one additional statement. Avoid having multiple virtual tags calculate the same value separately |
| Keep Source Windows Small | Pairing two or more sources creates combinations of values within the window. win:length(1) uses only one latest value per source, resulting in a single combination, but larger time windows increase combinations multiplicatively |
OUTPUT LAST EVERY n | Since calculations trigger whenever a value arrives from any source, more frequent sources lead to more frequent results. This clause is a rate limit that outputs only the last value per interval — as results are immediately stored as points, this also reduces storage volume |
| Startup Time | Calculation statements are deployed 4 at a time during startup. With many virtual tags, it may take time after startup for all calculations to begin running |
Limitations
| Item | Content |
|---|---|
| Source Tag Count Limit | No fixed product limit |
| Chaining (Virtual Tag of a Virtual Tag) | Supported |
| Circular · Self-Reference Check | None — not caught during storage |
| Formula Length | 4,000 characters when submitted via V5 API |
| Syntax | Only statements accepted by the booted CEP backend are deployed — CEP — Backends |
Configuration Keys
There are no configuration keys dedicated solely to virtual tag calculations. Which engine runs the calculation statement is determined by CEP's cep.backend (CEP — Backends).
Related Documents
- Virtual Tags — User Guide: Creation · Examples · Alarms
- Diagnostics — Where calculation failures are logged
- Performance Tuning
- CEP — Limits and Rejection Tokens