Use the event log
The event log records everything the platform processed: every action, where it came from, and whether it worked. When you need to understand what happened, especially across a chain of related actions, this is where you look.
When something went wrong, piecing together what actually happened (which action, from where, and whether it worked) from scattered places is slow and error-prone.
Find what you need
You need the Audit History View permission to open the event log and read its events. See Who can read the event log.
To investigate with the event log, complete the following steps:
- Confirm the environment selected in the top bar is the one you want. The log follows that selection; the page no longer has its own environment list.
- Go to Operations › Event Log.
- Filter by status (
RECEIVED,PROCESSING,COMPLETED,FAILED), event type, source, a date range, or User — type a name or email to find what a given person did. Event type is a picker over the known types and you can select several, which matches events of any of them; it lists each type by its display name, grouped by category in the same order the event forms use, with the raw$TYPEshown alongside. A date range covers both the From and the To day, in the scheduler's time zone, which is the zone the list shows times in. - Open an event to see its detail: what it changed and, if it failed, the error. The list's type
column reads as the event's display name, with the raw
$TYPEbeneath it. - Select the event's Correlation ID to see everything that shares it: the full chain from the original action.
The payload holds the event as it was authored — [[…]] property tokens and all — so it cannot
tell you what a given attempt resolved them to. The detail's Attempts section can: one entry per
attempt, with its times, its outcome, and a line per token showing what it resolved to, like
[[OI.$DATE]] → 9/25/2026.
That is how you tell apart a [[$DATE]] event that failed just before midnight and succeeded the
next morning — the two attempts used different dates, and now you can see both.
A value you could not read directly is masked here too: an encrypted property shows ********, and
a plain global's value shows only if you can view that property. Events processed before this
shipped have no attempt entries. See Attempts.
Trace an event a machine raised
Filter source to AGENT to see the events raised by legacy LSAM machines themselves — a job or process on the machine wrote an event file and the agent sent it up. These events name the machine that raised them, plus the service account whose credential the line carried — verified against the identity system, and checked against that account's roles, before the event was applied.
The identity field distinguishes two cases: a verified account name, or the legacy compatibility pair, which carries no identity at all. A line whose credential fails, or whose account lacks the permission the event needs, never becomes an event, so it does not appear here. See How an agent-raised event is attributed.
A few things to know before you spend time looking:
-
A line the platform refused before it became an event isn't here. A wrong field count, an unrecognised event type, a line written in the XML event syntax rather than the comma syntax, a machine with no Default event environment set, or a credential that failed verification never produces a row. If a machine's event file did nothing and there's no row at all, that's the likeliest explanation — check the setting on the agent first, then the credential the line carries.
-
A stored properties value can be a placeholder on one of these, for
$JOB:ADD,$JOB:ADDHLD,$SCHEDULE:BUILDor$SCHEDULE:BUILDHLD. It is replaced when the event is stored, because event files are hand-written and could carry a password. To run the event again, raise it again from the machine. -
A
[[…]]token in the payload is normal, not an unresolved value. A payload is stored as the author wrote it, and for an event from a machine, the portal, the API, the CLI or a webhook the tokens are resolved when the event is processed. If such an event isFAILEDand the error names a[[…]]token, the token itself is the problem: usually a global property that doesn't exist, or one scoped to a job the event never had. The error names the token, never what it resolved to. -
A
$JOB:ADDfor a multi-instance job leaves one row per instance. The event adds several job instances at once, so it records a state change for each, named<job>.<instance>. An instance that was already running is recorded and doesn't fail the event. If the event isFAILED, read the message rather than raising the line again: some instances were added before the failure, and the message is the only place that says which — with their IDs — alongside the ones that weren't added and the ones that were added but can never start. An agent-raised add that creates a new instance names itAdHocrather than after a property value, because the properties on such a line are redacted and a job's name isn't.
See Events raised by a legacy agent.
Keep it live
Turn on live refresh (every 5, 10, 30, or 60 seconds) to watch events as they happen, or pause and refresh manually.
- To trace an incident, start at the failed event and open its correlated view. You'll see the triggering action and everything it set off.
- There is no Retry in the event log. To run a failed event again, raise it again from where it came from.
- A "completed" event means it was processed. The work it kicked off has its own status in Processes.
- A console display event is a message and nothing more, so it completes with no downstream work.
Earlier builds logged these as
FAILED— a red row for a message that had arrived fine.
Related topics
- Event log — full configuration reference and troubleshooting
- Monitor the daily run (Operator)
- Respond to a failed job (Operator)