Increase the log level to debug on Windows and *nix agent nodes in Puppet Enterprise

Increase the log level for the Puppet agent service to learn when each plugin, file, fact, and resource is read and executed to troubleshoot issues with plugins, resource timeouts, unintended changes to files, or Puppet Enterprise completing operations in an unexpected order.

Version and installation information

PE version: All supported versions
OS: *nix, Windows

Solution

Increase the log level using the method that fits your issue. Increasing the log level for an extended period uses up hard drive space, so when you’re done troubleshooting, revert changes to the log level.

Note: Agent logs include sensitive information, including domain names and custom facts. Review logs and remove sensitive information before sending them to us.

The issue occurs on every agent run

If the issue occurs during every agent run, increase the log level for a single manual agent run.

Add the -d option to the agent run. If you output the logs to a file, you can attach them to a support ticket: puppet agent -td > PuppetDebug.log

The issue is intermittent

When the issue is intermittent, increase the log level for all Puppet runs. You can do this by editing either Puppet.conf or the agent service configuration.

Editing Puppet.conf:

• Works for both *nix and Windows.
• Increases the log level for all agents regardless of invocation method.
• Adds debug-level information to reports sent to the primary server.
• Does not require any service restarts.

Editing the agent service configuration:

• Allows you to target specific nodes.

Edit Puppet.conf

On Windows nodes, puppet.conf is located at %PROGRAMDATA%\PuppetLabs\puppet\etc (usually C:\ProgramData\PuppetLabs\puppet\etc)

On *nix nodes, puppet.conf is located at $confdir/puppet.conf (usually /etc/puppetlabs/puppet/puppet.conf)

On the target node, edit puppet.conf to add log_level = debug

Edit the agent service configuration

On Windows nodes

On the target node, restart the agent service using the following command: c:\>sc stop puppet && sc start puppet --debug --trace

On *nix nodes:

1. On the target node, edit the following file:

   • All *nix (except for Debian):/etc/sysconfig/puppet

   • Debian: /etc/default/puppet

     Add the following line to the end of the file:

     PUPPET_EXTRA_OPTS=--log_level=debug

2. Restart the agent service:

   `puppet resource service puppet ensure=stopped`
   `puppet resource service puppet ensure=running`

Where are the logs?

The location of the logs depends on your OS.

• On Windows, they are available in Event Viewer.
  • Select Windows Logs > Application.
• On *nix, the agent service logs messages to syslog:
  • RHEL-based OS: /var/log/messages
  • MacOS: /var/log/system.log
  • On Solaris: /var/adm/messages

Troubleshooting agent logging for *nix platforms

When the log level is increased to debug in *nix, it might be suppressed by the syslog process. In your logs, there is a lower level log output than expected and a message similar to the following:

Sep 26 07:05:58 pe-201645-agent journal: Suppressed 2367 messages from /system.slice/puppet.service

Resolve the issue by redirecting the logs to an output file.

1. On the target node, edit the following file:

   • All *nix (except for Debian): /etc/sysconfig/puppet

   • Debian: /etc/default/puppet

     Add the --logdest option to the PUPPET_EXTRA_OPT line, for example:

     PUPPET_EXTRA_OPTS=--logdest=/var/log/puppetlabs/agent.log --log_level=debug

2. Restart the agent service:

   puppet resource service puppet ensure=stopped puppet resource service puppet ensure=running