devops-lib-gcp/docs/wiki/pages/concepts/observability.md

Generated 2026-05-21 at base-sha 5399a5ddc36b. Type: concept. 1 source.

Logging via log.groovy

vars/log.groovy is the closest thing this codebase has to a logger. It's a 24-line Groovy file that wraps echo with ANSI colour codes.

The three calls

log.info(msg)     // → echo "${GREEN}INFO: ${msg}${BLACK}"
log.warning(msg)  // → echo "${RED}WARNING: ${msg}${BLACK}"
log.error(msg)    // → echo "${RED}ERROR: ${msg}${BLACK}"

That's the whole API. There is no severity level configuration, no structured fields (no JSON), no destination other than the Jenkins console.

What log.info gives you over bare echo

• ANSI colour — pipeline output in the Jenkins UI is easier to scan when INFO is green and ERROR is red.
• Consistent prefix (INFO: / WARNING: / ERROR: ) — a grep ERROR pipeline.log pattern works across every service.
• Nothing else. No timestamps (Jenkins adds those via timestamps wrapper), no caller tracing, no correlation ID.

When bare echo is acceptable

Lots of existing code uses bare echo. The mix is mostly historical. New code should prefer log.info for normal messages and log.error for failures, but you'll see bare echo in:

• One-off banners (echo "==========").
• Single-line status (echo "Building module: ${m}" inside a loop).
• ANSI-coloured ad-hoc messages where the code path needs a one-off colour (some vars/eksCICD.groovy and vars/buildPipeline.groovy lines do this).

There is no policy that bans bare echo. The reconcile run's BUGS_AND_IMPROVEMENTS_REPORT.md does list "inconsistent logging" as a P1 item but no rule has been graduated into CLAUDE.md NEVER DO yet.

env.msg as failure state

A separate convention: most stages set env.msg to a human-readable failure reason before re-throwing, e.g. buildNode.groovy:21:

env.msg = 'Error in building node packages...'
log.error(env.msg)
currentBuild.result = env.FAILURE
throw e

notify.groovy then reads env.msg (and the related env.error_msg_to_db) when composing the Slack message and the deployment-tracker payload. Don't rename env.msg — too many callers read it. deployRingmaster.groovy catch blocks are inconsistent here: some set env.msg, others don't — flagged in BUGS_AND_IMPROVEMENTS_REPORT.md as standardisation work.

What this codebase doesn't have

• No structured logging (no JSON, no key-value pairs, no trace IDs).
• No log level filtering — every log.info always prints.
• No log forwarding to anything other than the Jenkins console.
• No "audit log" stream separate from the pipeline log.

If you need to instrument a pipeline run for external observability, the current convention is to POST to a downstream system directly (see how notify.groovy calls the Deployment Tracker at lines 108-152). There is no shared metric/event emitter.