Docs: describe diagnostics collection

ydb/docs/en/core/reference/ydb-cli/sql.md

@@ -29,6 +29,7 @@ View the description of this command by calling it with `--help` option:
 || `--explain` | Execute an explain request for the query. Displays the query's logical plan. The query is not actually executed and does not affect database data. ||
 || `--explain-ast` | Same as `--explain`, but in addition to the query's logical plan, an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) is printed. The AST section contains a representation in the internal [miniKQL](../../concepts/glossary.md#minikql) language. ||
 || `--explain-analyze` | Execute the query in `EXPLAIN ANALYZE` mode. Displays the query execution plan. Query results are ignored.<br/>**Important note: The query is actually executed, so any changes will be applied to the database**. ||
+|| `--diagnostics-file` | Path to file where the diagnostics will be saved. ||
 || `--format` | Output format.<br/>Available options:
 
 {% include notitle [format](./_includes/result_format_common.md) %}
@@ -38,6 +39,62 @@ View the description of this command by calling it with `--help` option:
 ||
 |#
 
+### Diagnostics collection
+
+The `--diagnostics-file <path_to_diagnostics>` option allows you to save extended information about SQL query execution to a separate JSON file.
+
+Diagnostics are collected when statistics gathering is enabled `--stats full`, as well as during execution of `EXPLAIN` queries. For each query, a file named `<path_to_diagnostics>` will be created with the following fields:
+
+- **`plan`** — query execution plan.
+- **`stats`** — query execution statistics.
+- **`meta`** — additional query information in JSON format, including the following fields:
+    - **`created_at`** — query start time (timestamp);
+    - **`query_cluster`** — cluster or provider name;
+    - **`query_database`** — database path;
+    - **`query_id`** — unique query identifier;
+    - **`query_syntax`** — query syntax used;
+    - **`query_text`** — SQL query text.
+
+      **Note:** This field may contain sensitive or personal data, including parameter values;
+
+    - **`query_type`** — query type;
+    - **`table_metadata`** — schemas, indexes, and statistics of the tables involved in the query (JSON format).
+- **`ast`** — abstract syntax tree (AST) for the query.
+
+> **Important:**
+> The diagnostics file may contain confidential information, especially in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data.
+
+**Examples:**
+
+Example command to collect diagnostics in the `diagnostics.json` file and check its contents:
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json
+cat diagnostics.json
+```
+
+If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an `EXPLAIN` query instead:
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json
+```
+
+In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear:
+
+```json
+"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';"
+```
+
+This contains sensitive information — a user’s email address.
+
+Before sharing the diagnostics file, it is recommended to replace actual values with placeholders:
+
+```json
+"query_text": "SELECT * FROM users WHERE email = '<EMAIL>';"
+```
+
+In this example, the email address can also be found in fields such as **`plan`** and **`ast`**, such entries should also be replaced.
+
 ### Working with parameterized queries {#parameterized-query}
 
 For a detailed description with examples on how to use parameterized queries, see [{#T}](parameterized-query-execution.md).

ydb/docs/ru/core/reference/ydb-cli/sql.md

@@ -29,6 +29,7 @@
 || `--explain` | Выполнить explain-запрос, будет выведен логический план запроса. Сам запрос не будет выполнен, поэтому не затронет данные в базе. ||
 || `--explain-ast` | То же, что и `--explain`, но вдобавок к логическому плану выводит [AST (abstract syntax tree)](https://ru.wikipedia.org/wiki/Абстрактное_синтаксическое_дерево). Раздел с AST  содержит представление на внутреннем языке [miniKQL](../../concepts/glossary.md#minikql). ||
 || `--explain-analyze` | Выполнить запрос в режиме `EXPLAIN ANALYZE`. Показывает план выполнения запроса. Возвращаемые в рамках запроса данные игнорируются.<br/>**Важное замечание: Запрос фактически выполняется, поэтому может внести изменения в базу**. ||
+|| `--diagnostics-file` | Путь для сохранения файла с диагностикой. ||
 || `--format` | Формат вывода.<br/>Возможные значения:
 
 {% include notitle [format](./_includes/result_format_common.md) %}
@@ -38,6 +39,62 @@
 ||
 |#
 
+### Сбор диагностики
+
+Опция `--diagnostics-file <path_to_diagnostics>` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл.
+
+Диагностика формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `<path_to_diagnostics>` со следующими полями:
+
+- **`plan`** — план выполнения запроса.
+- **`stats`** — статистика выполнения запроса.
+- **`meta`** — дополнительная информация о запросе в JSON-формате со следующими полями:
+    - **`created_at`** — время начала запроса (timestamp).
+    - **`query_cluster`** — название кластера или провайдера.
+    - **`query_database`** — путь к базе данных.
+    - **`query_id`** — уникальный идентификатор запроса.
+    - **`query_syntax`** — используемый синтаксис запроса.
+    - **`query_text`** — текст SQL-запроса.
+
+        **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе.
+
+    - **`query_type`** — тип запроса.
+    - **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (JSON-формат).
+- **`ast`** — абстрактное синтаксическое дерево (AST) запроса.
+
+> **Важно:**
+> Файл диагностики может содержать конфиденциальные данные, особенно в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию.
+
+**Примеры:**
+
+Пример команды, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое:
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json
+cat diagnostics.json
+```
+
+Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос:
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json
+```
+
+В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка:
+
+```json
+"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';"
+```
+
+Здесь присутствует чувствительная информация — адрес электронной почты пользователя.
+
+Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные:
+
+```json
+"query_text": "SELECT * FROM users WHERE email = '<EMAIL>';"
+```
+
+В данном примере адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, такие вхождения тоже нужно заменить.
+
 ### Работа с параметризованными запросами {#parameterized-query}
 
 Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md).