LOG Message

Writes one line to the log at the level you choose. Inside a job that line lands in the job log, where an operator reads it; outside a job it goes to the server log. This is the op that tells whoever is watching what the rule decided and why.

It reports, it does not act. An Error line here marks the job as having had an error and the rule carries on regardless. To stop, use FAIL.

Fields

Text

The message. ${...} placeholders are expanded against the stash first, so Deploying ${job_name} to ${bl} reads well in the log. Nested paths and the transformation helpers work here too, as described in variable parsing; ${uc(bl)} and ${topic.title} are both valid.

The field is a multi-line box. Newlines are kept, and the whole thing is one log entry rather than one entry per line.

Two ways to write a message that never appears:

• Leave the field empty. Nothing is logged, and no warning tells you so.
• Write something that expands to 0 or to an empty string. A bare ${error_count} logs nothing at all on the happy path, which is exactly when you wanted to see the zero. Give it some prose, errors: ${error_count}, and it always appears.

Both of those apply to Info, Warning and Error. A Debug line skips that check, so an empty or zero Debug message does reach the log on a server that has debug output on.

A freshly dropped op carries the text Message. Rules that were built in a hurry are full of lines that read Message, because the op was dropped and never opened.

Long messages are cut. Past 2000 characters the line in the log is truncated with a (continue...) marker and the full text is attached to the entry as data, reachable from the actions column of the log viewer.

Anything matching the password patterns configured for the system is masked before the line is stored. The overflow text attached by the truncation above goes through the same masking, so a long message is covered end to end. The one gap is an attachment the system reads as binary, which is stored untouched.

Message Level

Four choices, and they differ by more than colour.

Level	What it does
Info	a normal entry, visible by default in the log viewer
Warning	an entry, and the job's warning count goes up
Error	an entry, and the job's error count goes up; the rule keeps running
Debug	an entry only when the server is running with debug output enabled

On a server started without debug output, a Debug op writes nothing whatsoever, not even a hidden entry, so turning on the Debug filter in the log viewer afterwards will not bring it back. Use Info for anything you want to be able to read after the fact, and keep Debug for lines that would be noise on a normal run.

Even with debug output on, a Debug entry does not push an update to an open log viewer the way the other three levels do. It is written, but you have to reload the log to see it.

The error and warning counts drive the badges in the job monitor. A rule that logs at Error for something it then recovers from leaves a job that looks failed to anyone scanning the list.

Outside a job

In an event rule, a form rule or a web service rule there is no job log, so the entry goes to the server log with its level and timestamp. Debug still depends on the server's debug setting, and password masking is not applied there.

In a YAML rule

The same op exists in rulebooks as log, with more attachment options than the designer form exposes:

- log: a plain message, logged at info level

- log:
    msg: build finished with rc={{ rc }}
    level: warn

- log:
    msg: build output
    body: "{{ output }}"
    filename: build.txt

body attaches text to the entry, named by filename. file attaches the contents of a file read from the server, resolved inside the job workspace when the rule has one. link renders the value as a link, and dump attaches a structure. Exactly one of body, file, link and dump may be present; combining two of them stops the rule from building, with a message saying so.

filename is read only alongside body. With file the attachment is named after the path, and with link or dump a filename is ignored without comment. A level the op does not recognise is quietly treated as info, so a misspelt warning gives you an info line.

Combining with other ops

Put a LOG Message on each side of a branch to make the log say which way the rule went. The condition builder in IF var condition THEN leaves no trace of its own, so an unexplained gap in the log is usually a condition that came out false.

Inside a loop, log the loop variable rather than a fixed string, or the entries are impossible to tell apart.

Before a FAIL, log the context at Info and let FAIL carry the short reason. The failure message is what the user sees in the interface; the log line is what the engineer reads afterwards.

Code blocks in Server CODE can log from inside, which is preferable to computing a value, storing it and logging it with a separate op.

Examples

Report the shape of the work at the start of a step.

Text:           Deploying ${job_name} to ${bl} with ${nchangesets} changeset(s)
Message Level:  Info

Flag a recoverable problem without stopping. The count is spelled out so the line still appears when it is zero.

Text:           Retrying after ${retry_count} failed attempt(s) on ${target_host}
Message Level:  Warning

Record a decision taken inside a branch, so the log explains the skip.

Text:           Skipping deployment: window closed, next window ${next_window}
Message Level:  Info