Counter Thing
Counter Thing keeps a current, named total for selected operational outcomes. Use it when an Agent needs a small local KPI—such as completed inspections, error transitions, accepted jobs, or failed deliveries—rather than a raw event archive.
Count outcomes that support an operating decision
Most events describe activity, not a metric. A counter becomes useful only after an owner defines what one increment means, which duplicate or retry cases do not count, and when the total should be compared or reset. Counter Thing retains that chosen aggregate locally; it does not replace Event History, accounting records, or a time-series platform.
Production and inspection outcomes
Count accepted parts, rejected inspections, completed checklists, or escalated alarms for a line, station, laboratory cell, or service route. The result gives a supervisor a compact local total without treating every raw detector signal as a completed outcome.
Reliability and maintenance signals
Count transitions into a selected error state, recoveries, or confirmed intervention requests for pumps, building systems, refrigeration, network services, or specialist equipment. Keep the source event history when the team also needs the reason and exact time.
Integration quality checks
Record validated API timeouts, rejected messages, delivery retries, or successfully completed exchanges. A small business can use the same pattern for orders handed to a local service; a distributed enterprise can compare stable key totals across sites.
Focused local status pages
Expose selected totals to a local dashboard, utility, or managed web application. The page answers a narrow question—such as how many delivery exceptions occurred—without granting the user access to every Agent event.
Interpret first, then add a signed delta
Counter Thing implements the Agent event-consumer interface. While it is running, it accepts CountingEvent(key, value) events and adds the signed integer value to the matching key. A positive value increments; a negative value decrements. Empty keys and a value of zero are ignored.
Event Manager normally supplies the decision point: it selects a source event, applies the rule that defines a meaningful outcome, and uses Forward Event To Consumer to deliver the resulting counting event to Counter Thing. The counter does not infer business meaning from arbitrary source events by itself.
Interpretation rule
Decide which source condition represents one meaningful outcome and exclude duplicates or irrelevant states.
Counting event
Send a stable key and signed delta, for example inspection.pass and 1.
Current total
Read the current values through the component panel or its read-only API.
Design a bounded counter contract
Name the operational question
Write down what each key means, its owner, and the boundary it represents: a shift, a campaign, a maintenance period, or a lifetime total.
Choose stable, finite keys
Use categories such as inspection.pass, inspection.reject, or delivery.retry. Do not include timestamps, request IDs, user IDs, raw URLs, or free-form errors in a key.
Select the recovery policy
Choose in-memory storage for an intentionally temporary total. Choose Data Source storage when the total must be restored after the component restarts.
Route and test events
Use Event Manager to select the intended event flow and forward only CountingEvent values to this component. Test normal, duplicate, retry, negative-delta, and restart cases before relying on the number.
A latest-value snapshot, not an event ledger
With IN_MEMORY storage, totals exist only while Counter Thing runs. With DATA_SOURCE storage, the Thing loads its previous per-key rows at startup and periodically saves only keys that changed. A final save is attempted when the Thing stops.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Title | Yes | Display name and uniqueness key for the counter group. | Empty |
Storage strategy | Yes | IN_MEMORY keeps current runtime values only; DATA_SOURCE restores and snapshots them through a Data Source. | IN_MEMORY |
Data Source | Conditional | Active Data Source used for snapshot storage. It is required when the strategy is DATA_SOURCE. | None |
Submit delay | Yes | Minimum interval between attempts to save changed keys in Data Source mode; range 1-3600 seconds. | 5 sec |
Read totals and keep reset boundaries explicit
Read counters
The read-only readCounters API returns lifecycle state, storage mode, pending writes, total, and rows sorted by key.
Signed total
The total is the sum of all current values. A negative delta is valid and can reduce a key and the overall total.
Snapshot status
In Data Source mode, use pendingWrites and each row's pending value to identify unsaved changes.
Counter Thing has no built-in reset or delete operation. Define the reset process alongside the business metric and perform any persistent-data maintenance under a controlled, documented procedure. Reloading or redeploying is not a reset mechanism for Data Source totals.