Writing a helpful ticket

It can be challenging to figure out what to put in your support request. Chef products are flexible by design, and can be used and deployed in many different ways depending on your organization's needs. Don't worry, we're here to help. Here are some things to consider when submitting a support request:

Has your organization encountered this issue previously?
Have you followed general troubleshooting steps?
Have you gathered enough detail to help us identify your issue?
If we need to attempt to replicate your issue in a test environment, do we have the information necessary to do so?
Are you being descriptive enough?
Are you describing the problem you're actually experiencing?

As with many things in software, you may find that, in the process of authoring an effective support request, a solution to the problem presents itself. And when that’s not the case, the easier it is for us to understand your issue, the easier it will be for us to help you resolve it.

Chef doesn’t have any kind of tiered system for Support Engineers, or a complicated priority calculation engine. We’re a small team of folks who want your experience with our products to be as positive as possible.

Has your organization encountered this issue previously?

If you've encountered this issue previously, you may be able to find steps to resolve the issue by looking at your ticket history.

Have you followed general troubleshooting steps?

If you have followed some troubleshooting steps already, it can be very helpful to share what steps you have taken and their results. Sharing code and terminal output is extremely helpful. When sharing code or terminal output, the best way to do so is to put the text in a text file and attach that to the ticket, since Zendesk does strange things to text formatting when you use the text fields.

Remember to tell us what is working! If the issue is occurring on some nodes but not on others, describe the differences clearly. Are the run lists different? Were they provisioned with different versions of Chef Infra Client?

Have you gathered enough detail to help us identify your issue?

In the case of something like a 500 error working with a Chef Infra Server or Chef Automate web console, you should share gather-logs bundles from your Chef Infra Server or cluster or from your Chef Automate server as well as details of what you were doing when the error occurred.

In the case of something like an unsuccessful Chef Infra Client or Chef InSpec run, it’s important for us to have the full run logs as well as any stack trace file called out in the run output. It could be useful to examine the run log prior to the first failed run, as well as logs from the first failed run.

If we need to attempt to replicate your issue in a test environment, do we have the information necessary to do so?

Chef Support Engineers may have to build a replication case to identify the cause of an event, or to share information about the issue with Product Engineering. In order to do this, we may need information not collected in the server gather-logs bundles or client run logs, possibly including cookbook or profile code. Please consider that we only have the information about your environment that you share, and be proactive and as complete as you can when gathering information to help us help you.

Do your systems enable host-level or network-level firewalls that might be in play, and what are those settings? What about proxies, are those set? Do you run security software on your hosts or inline on the network that could be changing how the system behaves? If you’re running in your own datacenter, what kind of disks are systems provisioned with?

Think about it like this: If you had to ask a new hire in your organization to test the issue in a sandbox environment, would they be able to take the information you’ve provided in the ticket and reproduce the problem? If so, you’ve written an awesome ticket.

Be descriptive!

The subject of the ticket should help us get a start classifying the issue. The content of the ticket should include actual commands run, actual output, and logs whenever possible. Tickets lacking this information usually take longer to resolve.

Be sure you’re describing the problem, rather than asking why your solution isn’t working

Sometimes when you’re trying to accomplish a task and it’s not proceeding as you expected, it can be easy to focus on the solution you’ve chosen and miss details of the problem you’re encountering. You can read about this pattern at http://xyproblem.info/

How do I write a helpful support ticket?