Audit log

This page is for administrators. The gateway keeps one audit log: every attempt to change a tag value, whoever or whatever made it. It does not log configuration changes, sign-ins or reads.

What is recorded

A row is inserted before the write is attempted, against the principal that asked for it, and a write that cannot be recorded is not attempted. When the write finishes, the row gets its outcome. Each row holds:

Field	Meaning
at	When the write was asked for
principalId, principalName, principalEmail	Who: a user id, or apikey:<id> for an API key, or a module's own principal such as cron:<job>. The name is the account's current name where it still exists
operation	write for memory-tag and driver writes, publish for injected readings (POST /api/v1/runtime/tags/{id}/values)
tagId, tagPath	The tag
moduleId	The driver that owns the tag, if any
value	The value as JSON, cut to 4 KB
correlationId	Set by module scripts that pass one
outcome, error	See below
completedAt	When the outcome was known

Outcome	Meaning
accepted	The tag runtime or driver accepted it
rejected	Refused, with the reason in error: an unknown or disabled tag, say, or a device's refusal
failed	Threw or timed out, with the reason in error. After a timeout, the device may have received it
pending	The gateway never learned the result, because it stopped mid-write. The device may have received it

What is not recorded

• Writes refused at /sync or by a policy for lack of a role never reach the tag runtime, so they are not logged.
• Browser values under @gateway.browser.* are not tag writes and are not logged.
• Reads, subscriptions, alarm acknowledgements, configuration changes, sign-ins and API key use are not in this log. Sign-in failures and configuration events appear in the gateway log only as log lines.
• Values written by a driver as readings from a device are not writes and are not logged; only publish through the API is.

The Audit page

Open Gateway, then Security, then Audit. Anyone who is not an administrator sees "Only administrators can read the audit log."

The page lists entries newest first with the columns Time, Who, Tag, Value, Outcome and Detail (the error, when there is one). To see one tag, type its exact path, including capitals, into Exact tag path; Clear filter removes it. When the log is routed to an outside database, the page says "Stored in name, newest first" with a link to Storage.

The tag's Audit tab

A tag's editor in Tags and types has an Audit tab, shown to administrators, with the same entries filtered to that tag.

Where it is stored

Every entry is written to the gateway's own SQLite database first, in the same moment as the write. An administrator can route the log to a PostgreSQL, SQL Server or MySQL connection under Storage; a forwarder then copies entries to the table scadex_tag_write_audit, and the Audit page reads from there, adding entries not copied yet from the gateway. Databases and storage describes the store-and-forward, the table, and what happens when the outside database is down.

Nothing prunes the audit log. The gateway's own copy keeps every entry, and so does the outside table. If the table grows beyond what you want to keep, archive or delete rows there yourself; the gateway never reads back what it already copied.

A power cut can lose the last few seconds of commits, including audit rows, because SQLite runs with synchronous=NORMAL and checkpoints every 5 seconds. A gateway crash loses nothing.

Limits

• One filter in the dashboard: exact tag path. The API also filters by principalId.
• No export from the page; read the API or query the outside table.
• No retention setting.

API

The route needs the admin role. The full reference is in Admin API.

Route	Purpose
GET /api/v1/admin/audit/tag-writes?tag=&principalId=&before=&limit=	Newest first; tag matches the id or the exact path; limit 1 to 1000 (default 100). Pass the last id of a page as before for the next page

The response header X-Scadex-Audit-Store names the store that answered (gateway or the connection's name). X-Scadex-Audit-Warning is present when the outside database could not be read and the gateway's own copy was returned instead.