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,26 @@ 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>.json` will be created with the following fields:
+
+- **`created_at`** — query start time (timestamp)
+- **`query_cluster`** — name of the cluster or provider
+- **`query_database`** — path to the database
+- **`query_id`** — unique query identifier
+- **`query_plan`** — query execution plan
+- **`query_syntax`** — query syntax used
+- **`query_text`** — text of the SQL query
+  **Note!** This field may contain sensitive or private user data, including parameter values used in the query.
+- **`query_type`** — type of the query
+- **`table_metadata`** — schemas, indexes, and table statistics involved in the query (in JSON format)
+
+> **Important:**
+> The diagnostics file may contain confidential data, especially in the **`query_text`** field. Before sharing this file with third parties (e.g., technical support), it is recommended to manually review and edit its contents to remove or replace any sensitive information.
+
 ### 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,27 @@
 ||
 |#
 
+### Сбор диагностики
+
+Опция `--diagnostics-file <path_to_diagnostics>` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл.
+
+Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `<path_to_diagnostics>.json` со следующими полями:
+
+- **`created_at`** — время начала запроса (timestamp)
+- **`query_cluster`** — название кластера или провайдера
+- **`query_database`** — путь к базе данных
+- **`query_id`** — уникальный идентификатор запроса
+- **`query_plan`** — план выполнения запроса
+- **`query_syntax`** — используемый синтаксис запроса
+- **`query_text`** — текст SQL-запроса
+
+  **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе.
+- **`query_type`** — тип запроса
+- **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (формат JSON)
+
+> **Важно:**
+> Файл диагностики может содержать конфиденциальные данные, особенно в поле `query_text`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию.
+
 ### Работа с параметризованными запросами {#parameterized-query}
 
 Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md).