System Tags
Overview
Every connector you configure — regardless of protocol, driver, or device — automatically receives a small set of System Tags in addition to whatever data tags you define for it. These aren't configured; they're created and maintained by Collect itself, and exist purely to answer "is this connector healthy, and if not, why?" without needing to instrument your own program logic.
There is also a built-in Memory connector, present in every Collect instance, which doesn't talk to any device at all — its job is to report on the health of the Collect engine (the whole running process) rather than any single connection. It carries the same base set of System Tags as every other connector, plus a much larger set of Engine System Tags unique to it.
This page documents both sets: what each tag means, where its value actually comes from, and — most usefully — how to read it when you're trying to diagnose a problem (a connector that won't stay connected, a slow-running program, or a Collect instance whose memory usage keeps climbing).
Note: Every System Tag name is prefixed with % and is read-only from Collect's own perspective — you can subscribe to or display them like any other tag, but Collect itself is the only thing that ever writes to them.
Connector System Tags
These eight tags are created automatically for every connector you configure. Some are also visible per-connector in that connector's own documentation page, but their meaning and behaviour is identical everywhere — they're implemented once, centrally, not reimplemented per connector.
| Tag | Type | Description |
|---|---|---|
| %CONNECTED | Bool | Whether the connector currently believes it has a live connection to its target device/broker. Republished on every connect/disconnect transition. If this is sitting at false for longer than you'd expect, check that connector's %ERROR history for the reason the connection attempt is failing. |
| %CONNECTEDEVENTS | Counter | A running count of how many times this connector has transitioned from disconnected to connected, since Collect last started. This only increments on the transition itself — not on every retry attempt while still disconnected — so it stays a clean count of actual reconnection events. |
| %DISCONNECTEDEVENTS | Counter | The equivalent running count of disconnect transitions. %CONNECTEDEVENTS and %DISCONNECTEDEVENTS are the most direct way to spot a "flapping" connection — a device or network link that connects, drops, and reconnects repeatedly. %CONNECTED alone only shows the state at whatever instant you happen to look at it; a connector that flapped ten times in the last minute and happens to be connected right now looks identical to one that's been rock solid all day, unless you also check these two counters. |
| %HEARTBEAT | Bool | Toggles (flips true/false) approximately every 5 seconds, independent of whether the connector is currently connected or not. This exists purely to prove the connector's own background monitoring loop is still alive and running — a connector whose thread has hung or crashed will stop toggling this, even if %CONNECTED itself hasn't changed. Not present on the Memory connector — see %SYSHEARTBEAT below, which serves the same purpose at the whole-engine level. |
| %ERRORSTATE | Bool | true whenever this connector has an active (uncleared) error condition. Cross-reference against %ERROR's own history for the specific diagnostic code and description. |
| %ERROR | Diagnostic | Error-level diagnostic messages raised by this specific connector — connection failures, protocol errors, bad configuration, etc. Each connector's own documentation page lists the specific diagnostic codes it can raise here, with a plain-English description of each. |
| %DEBUG | Diagnostic | Lower-level, verbose diagnostic messages — connection setup steps, individual operation timings, and other detail that's normally only useful when actively troubleshooting rather than during routine monitoring. |
| %INFO | Diagnostic | Informational messages marking normal lifecycle events — connector started, connection (re-)established, and similar "this happened, and it's expected" events. |
Diagnostic message numbering
%ERROR, %DEBUG, and %INFO all carry a numbered diagnostic code alongside their text description (e.g. "230 — Reconnecting"). The raw code a connector's own source assigns to a given condition is always the same regardless of which of the three tags it's published through, but each tag adds its own offset for display, so the same underlying code reads differently depending on severity:
| Published via | Offset added |
|---|---|
| %ERROR | +1000 |
| %DEBUG | +2000 |
| %INFO | +3000 |
So a connector's own documentation listing code 230 as "Info — Reconnecting" is the same event you'd see reported as 3230 when actually looking at that connector's %INFO tag. This offset only affects how the code displays — it's a consistent, deliberate convention across every connector, not an error or an inconsistency between the docs and what you see live.
Engine System Tags (Memory Connector)
The Memory connector represents the Collect engine process itself, not a device connection. Alongside the eight Connector System Tags above (with %HEARTBEAT replaced by %SYSHEARTBEAT), it carries the following engine- and host-level metrics. Most of these are refreshed roughly every 20 seconds by a built-in monitoring cycle.
| Tag | Type | Description |
|---|---|---|
| %SYSHEARTBEAT | Bool | Toggles every ~20 seconds — the whole-engine equivalent of every other connector's %HEARTBEAT. If this stops toggling, the engine's core monitoring cycle itself has stalled, independent of any individual connector's state. |
| %CYCLETIME | Int (ms) | How long the engine's core scan cycle actually took to complete, in milliseconds, most recently. This is the single best indicator of overall engine performance — if it's climbing over time (rather than staying roughly flat), something is slowing the whole engine down, not just one connector, and it's worth checking %ASYNCQUEUEDEPTH/%BROKERQUEUEDEPTH and %PROCESSMEMORY next as likely contributing causes. |
| %ASYNCQUEUEDEPTH | Int | Number of Engine-program actions currently queued and waiting to run. This queue has no fixed upper limit, so a value that keeps climbing rather than staying low and bouncing around zero is an early warning that something (usually a slow connector call inside a program) is causing work to back up faster than it can be processed. |
| %BROKERQUEUEDEPTH | Int | The same idea as %ASYNCQUEUEDEPTH, specifically for tag publishes waiting to go out to a broker. A climbing value here usually means a broker connection is slow, unreachable, or has fallen behind — check that broker connector's own %CONNECTED/%ERROR history. |
| %SESSIONID | String | A random identifier generated fresh each time Collect starts, and unchanged for the lifetime of that run. Useful for confirming whether two log entries (or two readings of these tags) came from the same continuous run of the service, or whether a restart happened in between. |
| %RUNTIME | TimeSpan | How long this specific run of Collect has been up for. Resets to zero on every restart — a %RUNTIME that's much shorter than you expect, alongside an unchanged %SESSIONID history, is a sign the service has been restarting unexpectedly. |
| %ENGINEVERSION | String | The version number of the running Collect engine. Always worth including when reporting an issue. |
| %CPUUSE | Decimal (%) | Total CPU utilisation of the host machine (not just this process), sampled from Windows performance counters. |
| %CPUTEMP | Int (°C) | CPU temperature, where the host's hardware/BIOS exposes it via Windows' ACPI thermal zone interface. Many machines — including most virtual machines — don't expose this at all, in which case this reads 0; that's an expected hardware/platform limitation, not a fault in Collect. |
| %AVAILABLERAM | Decimal (KB) | Free physical memory on the host machine as a whole. On a shared machine running other software (a database, remote-management agent, etc.), this can swing by a large amount for reasons that have nothing to do with Collect — use %PROCESSMEMORY below instead when you specifically want to track Collect's own memory behaviour. |
| %PROCESSMEMORY | Decimal (MB) | Collect's own memory footprint (its Working Set — the same figure Windows Task Manager shows per-process). This is the number to watch when investigating a suspected memory leak, since unlike %AVAILABLERAM it isolates Collect's own usage from everything else running on the machine. |
| %MANAGEDMEMORY | Decimal (MB) | The portion of %PROCESSMEMORY that's on Collect's own internal (.NET) memory heap. Comparing the two together tells you where growth is coming from: if %MANAGEDMEMORY is climbing in step with %PROCESSMEMORY, the cause is inside Collect's own logic; if %PROCESSMEMORY climbs while %MANAGEDMEMORY stays flat, the growth is in an underlying driver/library instead (e.g. a third-party device SDK), which is a meaningfully different kind of problem to report. |
| %THREADCOUNT | Int | Total number of threads currently running inside the Collect process. Should stay roughly constant (proportional to how many connectors are configured) for as long as the service runs — a value that keeps climbing over time, with no corresponding increase in configured connectors, points at a thread being started somewhere without ever being cleaned up. |
| %CONSTANTCACHESIZE | Int | Size of an internal cache Collect uses to speed up repeated evaluation of Engine program logic. This should settle at a small, stable number shortly after startup (roughly one entry per fixed value used across all your Engine programs) and then stay flat. If it climbs continuously instead, particularly in proportion to how often your tags are changing value, that's a specific, identifiable fault pattern worth reporting with this tag's value included. |
| %EVENTACTIONINTERVALSIZE | Int | Number of Engine "delay"/interval-triggered actions Collect is currently tracking as pending. Should stay low and bounded, rising only briefly while delayed actions are actually in flight. |
| %EVENTACTIONINTERVALTEMPSIZE | Int | A short-lived staging count that feeds into %EVENTACTIONINTERVALSIZE above on the next engine cycle. Normally at or near zero; a persistently non-zero value here alongside a climbing %EVENTACTIONINTERVALSIZE narrows down where pending actions are accumulating. |
| %DRIVESPACE-C | Int (MB) | Free disk space on the first drive Windows reports to Collect. |
| %DRIVESPACE-D | Int (MB) | Free disk space on the second drive Windows reports to Collect. |
Note: %DRIVESPACE-C/%DRIVESPACE-D are labelled by convention, not guaranteed by drive letter — they report whichever two drives the operating system lists first, which is normally C: and D: but isn't strictly guaranteed on every machine. If a reading looks inconsistent with what you expect for your C:/D: drives specifically, verify against Windows' own disk management rather than assuming the label is wrong.
Diagnosing common issues with these tags
A connector won't stay connected / keeps dropping out. Watch %CONNECTEDEVENTS and %DISCONNECTEDEVENTS together rather than just %CONNECTED — a climbing pair of counters over a short period confirms flapping even if the connector happens to be connected at the exact moment you check. Then check that connector's %ERROR history for the specific diagnostic code explaining why each disconnect happened.
The whole Collect instance feels slow. Start with %CYCLETIME on the Memory connector — if it's trending upward over time rather than staying roughly flat, the engine's core scan is taking longer than it should. %ASYNCQUEUEDEPTH and %BROKERQUEUEDEPTH climbing alongside it usually points at the specific cause: work queuing up faster than it can be processed, often because of a slow connector call or an unreachable broker.
Memory usage on the machine seems to be climbing. Check %PROCESSMEMORY first — it isolates Collect's own memory use from everything else on the machine, which %AVAILABLERAM can't do on a shared server. If %PROCESSMEMORY is genuinely climbing (not just a temporary rise that plateaus), compare it against %MANAGEDMEMORY: growing together points at Collect's own logic, %PROCESSMEMORY alone climbing points at an underlying device driver/library instead. %CONSTANTCACHESIZE, %EVENTACTIONINTERVALSIZE, and %THREADCOUNT are useful next checks — each should stabilise shortly after startup and then stay flat, so a climbing value in any of them narrows down where the growth is coming from before you even need to send us a log file.
The service seems to have restarted unexpectedly. %RUNTIME resets to zero and %SESSIONID changes to a new value on every restart. If you're seeing a %RUNTIME shorter than expected, or a %SESSIONID that's changed since you last checked, that confirms a restart happened — worth checking Windows' own Event Viewer / Collect's own log files around that time for why.