Add structured logging

Author: ilyario

docs/en/development.md

@@ -115,6 +115,33 @@ make generate
 
 Generates `DeepCopy` methods for all types in `api/v1/`.
 
+## Logging
+
+### Structured fields
+
+Operator and processor logs use consistent fields for correlation:
+
+| Field | Where | Purpose |
+|-------|-------|---------|
+| `dataflow_name` | Operator, processor, connectors | DataFlow resource name |
+| `dataflow_namespace` | Operator, processor, connectors | DataFlow namespace |
+| `reconcile_id` | Operator | Short id for one reconcile cycle (8 hex chars) |
+| `connector_type` | Processor, connectors | Connector type (e.g. `kafka-source`, `trino-sink`) |
+| `message_id` | Processor, connectors | Message id from metadata (if present) or Kafka partition/offset |
+
+Use these fields to filter logs (e.g. by `dataflow_name` and `reconcile_id`) and correlate errors with a specific DataFlow and message.
+
+### Log level (LOG_LEVEL)
+
+Operator and processor read the **LOG_LEVEL** environment variable. Allowed values (case-insensitive): `debug`, `info`, `warn`, `error`.
+
+- **Production**: set `LOG_LEVEL=info` (or leave default; Helm uses `info`) to reduce log volume.
+- **Debugging**: set `LOG_LEVEL=debug` for more verbose output.
+
+In Helm, the operator level is set via the **logLevel** value (default `"info"`), which is passed as env `LOG_LEVEL` in the operator pod.
+
+Processor pod log level is controlled by the operator env **PROCESSOR_LOG_LEVEL** (processor pods default to `LOG_LEVEL=info`). To enable verbose processor logs when debugging, set env `PROCESSOR_LOG_LEVEL=debug` in the operator Deployment.
+
 ## Testing
 
 ### Unit Tests

docs/ru/development.md

@@ -162,6 +162,33 @@ make generate
 make manifests
 ```
 
+## Логирование
+
+### Структурированные поля
+
+В логах оператора и процессора используются единые поля для корреляции:
+
+| Поле | Где | Назначение |
+|------|-----|------------|
+| `dataflow_name` | Оператор, процессор, коннекторы | Имя ресурса DataFlow |
+| `dataflow_namespace` | Оператор, процессор, коннекторы | Namespace DataFlow |
+| `reconcile_id` | Оператор | Короткий идентификатор одного цикла реконсиляции (8 hex-символов) |
+| `connector_type` | Процессор, коннекторы | Тип коннектора (например `kafka-source`, `trino-sink`) |
+| `message_id` | Процессор, коннекторы | Идентификатор сообщения из метаданных (если есть) или partition/offset для Kafka |
+
+По этим полям можно фильтровать логи в агрегаторе (например по `dataflow_name` и `reconcile_id`) и связывать ошибки с конкретным DataFlow и сообщением.
+
+### Уровень лога (LOG_LEVEL)
+
+Оператор и процессор читают переменную окружения **LOG_LEVEL**. Допустимые значения (без учёта регистра): `debug`, `info`, `warn`, `error`.
+
+- **В проде**: задайте `LOG_LEVEL=info` (или не задавайте — по умолчанию в Helm используется `info`), чтобы уменьшить объём логов.
+- **При отладке**: задайте `LOG_LEVEL=debug` для более детального вывода.
+
+В Helm для оператора уровень задаётся через value **logLevel** (по умолчанию `"info"`); он подставляется в env `LOG_LEVEL` в поде оператора.
+
+Уровень лога подов процессора задаётся переменной окружения оператора **PROCESSOR_LOG_LEVEL** (по умолчанию поды процессора получают `LOG_LEVEL=info`). Чтобы включить детальные логи процессора при отладке, задайте в Deployment оператора env `PROCESSOR_LOG_LEVEL=debug`.
+
 ## Тестирование
 
 ### Unit тесты