PBM-887 Documented pbm diagnostic command

docs/reference/pbm-commands.md

@@ -402,6 +402,33 @@ The output document contains the following fields:
 | `replsets`  | The list of replica sets included in the restore. Each replica set has the following fields: <br> - `name` - the replica set name <br> - `status` - the restore status on this replica set <br> - `error` - the error message for failed restore <br> - `last_transition_time` - the human-readable indication of the time when the restore process changed its status <br> - `nodes` - the list of nodes included in the restore. |
 | `replsets.nodes`     | The list of nodes included in the restore. Each node has the following fields: <br> - `name` - the node name and port <br> - `status` - the restore status on the node <br> - `error` - the error message for failed restore <br> - `last_transition_time` - the human-readable indication of the time when the restore process changed its status |
 
+## pbm diagnostic
+
+Generates the report with the detailed information about a a specific backup, restore, or other commands. The report includes the following information:
+
+* The information about the environment: pbm-agents statuses, cluster members, etc. 
+* Logs collected between the start and end time of the command execution
+* If it is a backup command, the backup metadata file.
+* If it is a restore command, the restore metadata file and the backup metadata file. 
+
+   <i warning>:material-alert: Warning:</i> Physical restore is not supported in version 2.8.0.
+
+To learn more, refer to the [Diagnostics report](../troubleshoot/pbm-report.md).
+
+The command has the following syntax:
+
+```{.bash data-prompt="$"}
+$ pbm diagnose --path path --name <backup-name> --opid <OPID>
+```
+
+The command accepts the following flags:
+
+| Flag                | Description                      |
+| ------------------- | -------------------------------- |
+| `--path`            | The path where to save the report. If the directory doesn’t exist, PBM creates it during the report generation. Make sure that the user that runs PBM CLI has write access to the specified path |
+| `--name`            | The name of the required backup or a restore |
+| `--opid`            | The unique Operation ID of the specified command. You can retrieve it from the `pbm logs`, `pbm describe-backup` / `pbm describe-restore` output. |
+| `--archive`         | Creates teh .zip archive of the report in the specified path.|
 
 
 ## pbm help

docs/troubleshoot/pbm-report.md

@@ -0,0 +1,42 @@
+# Diagnostics report
+
+!!! admonition "Version added: [2.8.0](../release-notes/2.8.0.md)"
+
+When troubleshooting issues with backups and restores, viewing logs and PBM status may sometimes not be enough to identify the root of the issue. 
+
+Starting with version 2.8.0 you can generate a diagnostics report about a specific backup, restore, or other commands. The report includes the following information:
+
+* The information about the environment: pbm-agents statuses, cluster members, etc. 
+* Logs collected between the start and end time of the command execution
+* If it is a backup command, the backup metadata file.
+* If it is a restore command, the restore metadata file and the backup metadata file. 
+
+   <i warning>:material-alert: Warning:</i> Physical restore is not supported at the moment.
+
+This data is stored in separate files in JSON format.
+
+To generate a report, run the `pbm diagnostics` command:
+
+```{.bash data-prompt="$"}
+$ pbm diagnostic --path=path --name=<backup-name> 
+```
+
+or
+
+```{.bash data-prompt="$"}
+$ pbm diagnostic --path=path --opid=<OPID> 
+```
+
+where:
+
+* `path` is the path where to save the report. If the directory doesn’t exist, PBM creates it during the report generation. Make sure that the user that runs PBM CLI has write access to the specified path.
+* `OPID` is the unique Operation ID of the specified command. You can retrieve it from the `pbm logs`, `pbm describe-backup` / `pbm describe-restore` output. 
+* `name` is the name of the required backup or a restore. You can use it instead of OPID for backups and restores.
+
+You can use the OPID to generate a diagnostics report about other operations like cleanup, cancellation, etc. In this case the report contains only the information about your environment and logs collected during the operation execution.
+
+You can also output the report into an archive file. 
+
+The diagnostics report empowers you to collect every necessary aspect for deep analysis of issues with a specific operation, all in one go. If you can't perform the analysis yourself, `pbm diagnostic` offers a quick and convenient way to collect and submit all relevant information for filing a bug report. This significantly reduces the interaction time between you and our experts, accelerating issue resolution.
+
+Percona customers have the advantage of their bug reports being prioritized higher. If you're interested in enjoying these benefits, [contact us today :octicons-link-external-16:](https://www.percona.com/about/contact).

mkdocs-base.yml

@@ -201,6 +201,7 @@ nav:
       - Overview: troubleshoot/index.md
       - 'Diagnose PBM': 'troubleshoot/troubleshooting.md'
       - 'Check status': 'troubleshoot/status.md'
+      - 'Diagnostics report': 'troubleshoot/pbm-report.md'
       - 'Troubleshoot backup management via PMM': 'troubleshoot/pbm-pmm.md'
       - troubleshoot/faq.md
   - Release notes: