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,61 @@ 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` or `--stats profile`), 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 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.
+
+**Example of a query containing sensitive information:**
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json
+```
+In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear:
+```json
+"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', '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>';"
+```
+Email addresses can also be found in fields such as **`plan`** and **`ast`**, for example:
+```json
+"plan":
+        ...
+        "Predicate" : "item.emails == \"alice@example.com\"",
+        ...
+```
+Such entries should also be replaced, for example:
+```json
+"plan":
+        ...
+        "Predicate" : "item.emails == \"<EMAIL>\"",
+        ...
+```
+
 ### 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,61 @@
 ||
 |#
 
+### Сбор диагностики
+
+Опция `--diagnostics-file <path_to_diagnostics>` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл.
+
+Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `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`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию.
+
+**Пример запроса с чувствительной информацией:**
+
+```bash
+ydb -e <endpoint> -d <database> sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json
+```
+В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка:
+```json
+"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');"
+```
+Здесь присутствует чувствительная информация — адрес электронной почты пользователя.
+
+Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные:
+```json
+"query_text": "SELECT * FROM users WHERE email = '<EMAIL>';"
+```
+Адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, например:
+```json
+"plan":
+        ...
+        "Predicate" : "item.emails == \"alice@example.com\"",
+        ...
+```
+Такие вхождения тоже нужно заменить, например:
+```json
+"plan":
+        ...
+        "Predicate" : "item.emails == \"<EMAIL>\"",
+        ...
+```
+
 ### Работа с параметризованными запросами {#parameterized-query}
 
 Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md).