Create a troubleshooting guide in the Problems app

Tutorial
Published Jul 16, 2025

Troubleshooting guides in the form of notebooks and dashboards can help you and your team efficiently resolve problems that are similar to the ones you already encountered in the past and reduce the mean time to repair (MTTR).

You can create and share your own troubleshooting guides in notebooks and dashboards or retrieve the existing guides with the help of Davis CoPilot.

Who this is for

This article is for any users who want to share their troubleshooting experience to help their team quickly remediate active problems in their environment.

What you will learn

In this article, you'll learn how to create your own troubleshooting guide and documents the steps taken to resolve the issue.

Before you begin

If you create a troubleshooting guide directly from the Dashboards Dashboards or Notebooks Notebooks, you have to prefix the document title with [TSG] to indicate it is a Troubleshooting Guide.

However, dashboards and notebooks created directly from the Problems app are automatically recognized as troubleshooting guides and do not require the [TSG] prefix.

Regardless of how the document was created, it still has to be shared at the environment level to be retrievable by any member of your team.

Prior knowledge

Prerequisites

Dynatrace SaaS environment.
You have Problems installed from Hub.
You have completed the Davis CoPilot setup described in Getting started with Davis CoPilot.
You have the ALLOW davis-copilot:document-search:execute; permission. To learn how to set up the permissions, see Permissions in Grail.

Create a troubleshooting guide in Problems app

Go to Problems.
Select a problem from the list (for example, Failure rate increase) to open the problem details page.
On the problem details page, select Troubleshooting to open the troubleshooting guide tab. If you have Davis CoPilot and Davis CoPilot document suggestion available in your environment, you will see guides for similar problems.
Select New, then select Notebooks to create a new document in Notebooks or Dashboards to create a new document in Dashboards. This creates a troubleshooting guide from the existing template with a title indicating the type of the document ([TSG], troubleshooting guide) the type of the problem (for example, Failure rate increase).
Davis CoPilot only indexes documents that are recognized as troubleshooting guides. Dashboards and notebooks created directly from the Problems app are automatically recognized as troubleshooting guides and do not require the [TSG] prefix, so you can change the title of the troubleshooting guide as you see fit.
Select View Notebook or View Dashboard to open the troubleshooting guide.

Changes made to each section are saved automatically.

Select Incident summary and select Edit. Fill in the necessary details:
- Provide a short description of the problem above the list.
- Provide the information on the impact of the error in Impact summary.
- Provide the severity level (such as Critical, High, Medium or Low) in Severity level.
- Provide the category of the event (for example, Error) in Category. You can find the even category in Problems and on top of the problem details page. To learn more about existing event categories, see Categories of Davis events.
- Provide a root cause of the problem (for example, the name of the service) in Root-cause.
- Provide links to JIRA or ServiceNow tickets connected to the problem (for example, bug fix tickets) in Ticket Links.
Select Initial Response & Detection and select Edit. Provide the information on how the problem was detected, for example:
- List observed symptoms.
- Provide links or screenshots for metrics, logs or traces that were analyzed by your or your team.
- List any observed anomalies and related events or deployments that occurred before the problem appeared.
Select Troubleshooting and select Edit. Provide the information on the methods you used to find the cause of the problem, for example:
- Provide the steps you took to diagnose the problem.
- List the tools you've used to diagnose the problem.
- Provide a explanation of what was the root cause of the problem (for example, A limit that was introduced in the latest deployment led to failure rate increase).
- Provide the data gathered during the troubleshooting (for example, configuration details, DQL queries used for the troubleshooting, logs, metric and error messages).
Select Remediation Steps and select Edit. Provide a step-by-step playbook on how to fix the issue, for example:
- Provide detailed remediation steps and relevant details, such as code changes and updates that were made to fix the issue.
- Provide the rollback plan to revert to a state before the problem occurred if the remediation steps don't work.
- Provide methods that can be used to verify the stability of the service after the fixes.
Select Helpful Resources and select Edit. Provide the list of resources that helped you resolve the issue, for example:
- Links to the documentation
- A list of feature flags and toggles
- Links to communication channels, such as slack threads, JIRA comments or emails.

If you want Davis CoPilot to suggest your troubleshooting guide to other people in your team, you have to share the document on the environment level. To learn more about sharing documents, see Share documents.

Conclusion

You successfully created your own troubleshooting guide and documented all the steps taken to resolve the issue. Now, you'll be able to refer to the guide if the problem appears again.

If you have shared your guide, you and the others on your team will also have this documented suggested to them in case of encountering similar issues.