Skip to main content

log.warn

The log.warn function writes a message to the Atmos log at the warn level. Use it for a recoverable problem, such as a fallback the script took on its own.

Usage​

log.warn(message, **fields)

Arguments​

message

Required. Exactly one positional argument: the message, as a string. Passing more than one positional argument, or a value that is not a string, fails with an argument error.

**fields

(Optional) Any number of keyword arguments, written to the log as structured key/value pairs after the message. Field names must be identifiers: letters, digits, and underscores, not starting with a digit. A value that is None, a boolean, an integer, a float, or a string keeps its native type. Any other value, such as a list or dictionary, is logged using its str() form.

Returns​

The return value is None. The call is a side effect and never becomes the step value.

Behavior​

  • The message goes to the Atmos logger, so it honors --logs-level (or ATMOS_LOGS_LEVEL) and logs.file. Below the configured level, the call prints nothing. See logs configuration for the levels and the log destination.
  • Log output never goes to stdout, so it cannot change what print or output produce.
  • Every message carries a step field: the step name for a workflow or custom command step, or the script path for a standalone script.
  • Inside steps.parallel tasks, a task field names the running task, for example task=dev, or task=grp/inner for nested groups. A group with a single task adds no task field.
  • If you pass a field named step or task, your value replaces the automatic one.
  • Secrets that Atmos knows about are masked in the message and in field values.

Examples​

Log a fallback​

log.warn("falling back to the default region", region = "us-east-2", attempts = 2)
 WARN  falling back to the default region step=retry region=us-east-2 attempts=2

A warning does not stop the script. Use fail() to stop it, or ui.warning to tell the person running the program.

Fields set by Atmos​

def apply(stack):
    log.warn("applying", stack = stack)

steps.parallel(tasks = [steps.task(s, apply, args = [s]) for s in ["dev", "prod"]])

Each line carries the step field and a task field naming the task that wrote it, for example step=apply task=dev stack=dev.

Errors​

  • A call with no message, with more than one positional argument, or with a message that is not a string fails with an argument error that names log.warn.
  • A field name that is not an identifier, such as bad-name, fails with an argument error that quotes the name.

Related​