Plan logging

You can view plan run information in log files or printed to a terminal session using the out::message function or built-in Puppet logging functions.

Outputting to the CLI or console

Use out::message to display output from plans. This function always prints message strings to STDOUT regardless of the log level and doesn't log them to the log file. When using out::message in a plan, the messages are visible on the Plan details page in the console.

Puppet log functions

In addition to out::message, you can use Puppet logging functions. Puppet logs messages to /var/log/puppetlabs/orchestration-services/orchestration-services.log

When using Puppet logging, each command's usual logging level is downgraded by one level except for warn and error.

For example, here are the Puppet logging commands with their actual level when used in plans.

```
  warning('logging text') - logs at warn level
  err('logging text') - logs at error level

  notice('logging text') - logs at info level
  info('logging text') - logs at debug level
  debug('logging text') - logs at trace level
```

The log level for orchestration-services.log is configured with normal levels. for more information about log levels for Bolt, see Puppet log functions in Bolt.

Default action logging

PE logs plan actions through the upload_file, run_command, run_script, or run_task functions. By default, it logs an info level message when an action starts and another when it completes. You can pass a description to the function to replace the generic log message.

run_task(my_task, $targets, "Better description", param1 => "val")

If your plan contains many small actions, you might want to suppress these messages and use explicit calls to the Puppet log functions instead. To do this, wrap actions in a without_default_logging block, which logs action messages at info level instead of notice.

For example, you can loop over a series of targets without logging each action.

plan deploy( TargetSpec $targets) {
  without_default_logging() || {
    get_targets($targets).each |$target| {
      run_task(deploy, $target)
    }
  }
}

To avoid complications with parser ambiguity, always call without_default_loggingwith () and empty block args ||.

Correct example

without_default_logging() || { run_command('echo hi', $targets) }

Incorrect example

without_default_logging { run_command('echo hi', $targets) }