docs: create troubleshooting page (#11897)

docs/usage/faq.md

@@ -58,6 +58,10 @@ Some major platform features are not supported at all by Renovate.
 
 ## What if I need to .. ?
 
+### Troubleshoot Renovate
+
+If you have problems with Renovate, or need to know where Renovate keeps the logging output then read our [troubleshooting documentation](https://docs.renovatebot.com/getting-started/troubleshooting/).
+
 ### Tell Renovate to ask for approval before creating a Pull Request
 
 The default behavior is that Renovate creates a pull request right away whenever there's an update.

docs/usage/getting-started/troubleshooting.md

@@ -0,0 +1,66 @@
+# Troubleshooting Renovate
+
+Learn how to troubleshoot problems with Renovate, where to find the logging output, and how to get help if needed.
+
+## Getting the logs
+
+Renovate's debug-level logs are usually enough to help troubleshoot most problems.
+Where you can find the logs depends on how you're running Renovate.
+
+### GitHub Hosted app
+
+Each pull request from Renovate contains a link to the WhiteSource Renovate Dashboard in the PR body text.
+
+The text you're looking for is:
+
+> This PR has been generated by WhiteSource Renovate. View repository job log here.
+
+Click on the blue text "here" to go to the WhiteSource Renovate App Dashboard.
+Sign in with your GitHub or GitLab account.
+Once you're logged in, you can see the logs for the Renovate jobs on your repository.
+You should have access to any repository which you have write access to and which has Renovate installed.
+
+Renovate only makes logs for the last 3 days available.
+
+When you've clicked on a recent job, you'll be able to select a debug level that you care about.
+For a full overview, make sure you select the `DEBUG` log level.
+
+### Self-hosted
+
+The easiest way to gather logs from Renovate for any platform is to use the default logging to `stdout`/console.
+By default, Renovate will log in a human-readable format at `INFO` level.
+
+For troubleshooting it's recommended to increase logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate.
+
+If your Renovate logs are being processed by a log service before you access them, you may find it better to have Renovate output logs in JSON format instead so that they can be reliably parsed and filtered.
+This can be achieved by adding `LOG_FORMAT=json` to your environment variables before invoking Renovate.
+
+## Log debug levels
+
+There are different severity levels for the log output.
+From least severe to most severe:
+
+- `DEBUG`
+- `INFO`
+- `WARN`
+- `ERROR`
+- `FATAL`
+
+To check for problems, look for `WARN` or `ERROR` logs (level 40 or 50 if in JSON format).
+To troubleshoot further, you usually need to look at `DEBUG` logs.
+
+## Resolving problems using logs
+
+We recommend you follow this process:
+
+1. Try to narrow in on the problem area e.g. by looking for relevant branches or `WARN` or `ERROR` messages
+1. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred
+1. Copy/paste the relevant parts of the logs into your discussion post or bug report
+
+If you cannot fix the problem yourself after reading the logs, and reading - or searching through - our documentation, search the [renovatebot/renovate discussion](https://github.com/renovatebot/renovate/discussions) forum to see if somebody has asked a similar or related question.
+
+If none of these steps have helped you, then create a new discussion post to get help from the Renovate maintainers.
+
+Please locate the relevant parts of the logs as described earlier before asking for help or posting a bug report.
+Do not expect the Renovate maintainers to read through the full logs when trying to help you, as that takes a lot of time on our part.
+If later it turns out that the full logs are necessary, you will be asked for them then.