Troubleshooting potential issues in Puppet Enterprise: How to learn more

In this article, you’ll learn how to get more information about issues in your Puppet Enterprise deployment so that you can either fix the issue or resolve your Support ticket sooner.

We’ll cover:

• Checking whether PE services are up and running
• Reviewing logs of affected services
• Searching the knowledge base and documentation
• Investigating and fixing performance issues
• Collecting the support script
• Opening a ticket

Version and installation information

PE version: All supported versions

Solution

Check whether PE services are up and running

The quickest way to get the status of PE services is to run puppet infrastructure status on your primary server (formerly called the master) or compilers.

To get an easy to read JSON formatted output of the current status of Puppet Enterprise services, on the primary server, run curl -k https://localhost:8140/status/v1/services | python -m json.tool

If you’re in the console, in the upper right corner, check Puppet Services status. Refresh the console to get current information.

Review the logs of affected services

Puppet's logging is descriptive and verbose. Most logs are located in a subfolder of /var/log/puppetlabs/. However, by default, the agent writes to /var/log/messages. Check logs for the service that’s affected. If you're having an issue with PuppetDB, for instance, take a look at the most recent entries in the PuppetDB log. If you get an Error 500 message during an agent run, check the Puppet Server log.

If you know the issue affects a specific component but the logs aren't descriptive enough, turn up logging. Learn how to increase the logging level for the agent and Puppet services.

Search the knowledge base and documentation

The knowledge base and documentation are both great resources when you're researching a problem. In the knowledge base, search using symptoms and error messages.

In our docs, make sure that you’re using the right version for your deployment. Focus on the service or setting that has the problem. Check the known issues page to see if your issue has a workaround. Check the release notes for later releases to see if the issue is fixed in a later version.

If you don't find what you're looking for in the documentation or the knowledge base, please let us know. We are always looking to improve our content. Our community loves to answer questions; check out our Community Slack channel. Learn more about our Community.

Investigate and fix performance issues

Do you have out of memory (OOM) errors, services going down, or connection timeouts in your logs? If you have a lack of resources, you might have performance issues. Please check the Installation requirements to confirm that the system meets the minimum requirements.

Check for performance issues by gathering metrics with the puppet_metrics_collector module. If the module is installed, metrics are automatically collected in the Support Script. Learn more about how to use and interpret the data.

You can get optimized performance settings by using the puppet infrastructure tune command. Learn how to use it. You can also learn more about performance tuning in our documentation.

One of the most common performance issues is a thundering herd where agent check-ins bunch up, creating periods of high demand and resource utilization on the primary server. This causes slow agent runs and even agent run timeouts. Learn how to fix it.

Collect the support script

The support script is a useful tool that packages up system metrics and PE-specific logs and packages for ease of transfer and readability. Since it gathers a lot of information about the system into a single location, we might ask you for a support script when you open a ticket, but it can also be a useful tool for you. You can run the support script on any Puppet Enterprise node running Red Hat, CentOS, Ubuntu, SLES, Debian, and in 2018.1.5 and newer, Windows operating systems. To run the support, run puppet enterprise support.

Get more information about the support script.

Open a ticket

We are here to help you! If you've gone through the troubleshooting steps above and you still have an issue, open a ticket with us, and we'll work with you to identify and resolve it.

When opening a ticket, it is helpful to include:

1. What is the issue?

2. What is the impact of the issue on business operations?

3. How did you notice the issue was occurring?

4. Did this issue suddenly appear or has it been happening for a while? If it suddenly started, what (if any) changes were made around the same time?

5. Is this affecting only specific agents? All agents?

6. If the issue is related to a module, what module is it? What version is the module?

7. Is this an upgrade? If so, what version are you upgrading from? Upgrading to? Do you have a backup?

8. Is this issue related to code you've written yourself or an unsupported third-party product? Troubleshooting custom code is outside of the bounds of Support. Our Community Slack channel is a great resource for coding issues. Learn more about our Community.