Skip to main content

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.

What this solves

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​

To investigate with the event log, complete the following steps:

  1. 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.
  2. Go to Event Log.
  3. 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 $TYPE shown alongside. A date range covers both the From and the To day, in your own time zone.
  4. 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 $TYPE beneath it.
  5. Select the event's Correlation ID to see everything that shares it: the full chain from the original action.

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.

Two 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 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:BUILD or $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 is FAILED and 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:ADD for 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 is FAILED, 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 it AdHoc rather 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.

Good to know
  • 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