> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Мониторинг журналов Kafka с ClickStack

> Мониторинг журналов Kafka с ClickStack

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **Кратко**

  Собирайте и визуализируйте журналы Kafka broker в формате Log4j в ClickStack с помощью OTel-приёмника `filelog`. Включает демо-набор данных и преднастроенный дашборд.
</Info>

<div id="existing-kafka">
  ## Интеграция с существующей установкой Kafka
</div>

В этом разделе описано, как настроить существующую установку Kafka для отправки журналов брокера в ClickStack, изменив конфигурацию коллектора ClickStack OTel.
Если вы хотите протестировать интеграцию журналов Kafka перед настройкой собственной среды, воспользуйтесь нашей предварительно настроенной средой и тестовыми данными из раздела ["Демо-набор данных"](/ru/clickstack/integration-examples/kafka-logs#demo-dataset).

<div id="prerequisites">
  ### Предварительные требования
</div>

* Запущенный экземпляр ClickStack
* Установленный Kafka версии 2.0 или новее
* Доступ к файлам журналов Kafka (`server.log`, `controller.log` и т. д.)

<Steps>
  <Step>
    #### Проверьте конфигурацию логирования Kafka

    Kafka использует Log4j и записывает журналы в каталог, указанный в системном свойстве `kafka.logs.dir` или переменной окружения `LOG_DIR`. Проверьте расположение файла журнала:

    ```bash theme={null}
    # Расположение по умолчанию
    ls $KAFKA_HOME/logs/      # Стандартный Apache Kafka (по умолчанию <install-dir>/logs/)
    ls /var/log/kafka/        # Установка из пакетов RPM/DEB
    ```

    Основные файлы журнала Kafka:

    * **`server.log`**: Общие журналы брокера (запуск, подключения, репликация, ошибки)
    * **`controller.log`**: События контроллера (выбор лидера, переназначение партиций)
    * **`state-change.log`**: Переходы состояний партиций и реплик

    Стандартный шаблон Log4j в Kafka создает строки вида:

    ```text theme={null}
    [2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)
    ```

    <Note>
      Для Kafka-развертываний на базе Docker (например, `confluentinc/cp-kafka`) конфигурация Log4j по умолчанию включает только консольный appender — file appender отсутствует, поэтому журналы записываются только в stdout. Чтобы использовать приёмник `filelog`, нужно перенаправить журналы в файл: либо добавив file appender в `log4j.properties`, либо перенаправив stdout через конвейер (например, `| tee /var/log/kafka/server.log`).
    </Note>
  </Step>

  <Step>
    #### Создайте пользовательскую конфигурацию OTel collector для Kafka

    ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector, подключив пользовательский файл конфигурации и задав переменную окружения. Пользовательская конфигурация объединяется с базовой конфигурацией, которой HyperDX управляет через OpAMP.

    Создайте файл с именем `kafka-logs-monitoring.yaml` со следующей конфигурацией:

    ```yaml theme={null}
    receivers:
      filelog/kafka:
        include:
          - /var/log/kafka/server.log
          - /var/log/kafka/controller.log  # необязательно, существует только если log4j настроен с отдельными файловыми аппендерами
          - /var/log/kafka/state-change.log  # необязательно, аналогично вышесказанному
        start_at: beginning
        multiline:
          line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
        operators:
          - type: regex_parser
            regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
            parse_from: body
            parse_to: attributes
            timestamp:
              parse_from: attributes.timestamp
              layout: '%Y-%m-%d %H:%M:%S,%L'
            severity:
              parse_from: attributes.severity

          - type: move
            from: attributes.message
            to: body

          - type: add
            field: attributes.source
            value: "kafka"

          - type: add
            field: resource["service.name"]
            value: "kafka-production"

    service:
      pipelines:
        logs/kafka:
          receivers: [filelog/kafka]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    ```

    <Note>
      * В пользовательской конфигурации вы определяете только новые приёмники и конвейеры. Процессоры (`memory_limiter`, `transform`, `batch`) и экспортеры (`clickhouse`) уже определены в базовой конфигурации ClickStack — здесь на них нужно только сослаться по имени.
      * Конфигурация `multiline` обеспечивает объединение трассировок стека в одну запись в журнале.
      * Эта конфигурация использует `start_at: beginning`, чтобы при запуске коллектора прочитать все существующие журналы. Для развертываний в продакшне измените значение на `start_at: end`, чтобы избежать повторного приёма журналов при перезапуске коллектора.
    </Note>
  </Step>

  <Step>
    #### Настройка ClickStack для загрузки пользовательской конфигурации

    Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

    1. Смонтировать файл пользовательской конфигурации в `/etc/otelcol-contrib/custom.config.yaml`
    2. Задать переменную окружения `CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml`
    3. Смонтировать каталог с журналами Kafka, чтобы коллектор мог их читать

    <Tabs>
      <Tab title="Docker Compose">
        Обновите конфигурацию развертывания ClickStack:

        ```yaml theme={null}
        services:
          clickstack:
            # ... существующая конфигурация ...
            environment:
              - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
              # ... другие переменные окружения ...
            volumes:
              - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
              - /var/log/kafka:/var/log/kafka:ro
              # ... другие тома ...
        ```
      </Tab>

      <Tab title="Docker Run (образ All-in-One)">
        Если вы используете all-in-one image с Docker, выполните:

        ```bash theme={null}
        docker run --name clickstack \
          -p 8080:8080 -p 4317:4317 -p 4318:4318 \
          -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
          -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
          -v /var/log/kafka:/var/log/kafka:ro \
          clickhouse/clickstack-all-in-one:latest
        ```
      </Tab>
    </Tabs>

    <Note>
      Убедитесь, что у коллектора ClickStack есть необходимые разрешения на чтение файлов журналов Kafka. В продакшне используйте монтирования только для чтения (`:ro`) и придерживайтесь принципа наименьших привилегий.
    </Note>
  </Step>

  <Step>
    #### Проверьте журналы в HyperDX

    После настройки войдите в HyperDX и убедитесь, что журналы поступают:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=0cbc6a497240c66d8cd5e701df69296a" alt="Представление Search" width="3838" height="1934" data-path="images/clickstack/kafka/logs/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=3f2cea15008a854c416a9d41a848fb97" alt="Представление логов" width="3838" height="1934" data-path="images/clickstack/kafka/logs/log-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## Демо-набор данных
</div>

Протестируйте интеграцию журналов Kafka на заранее подготовленном примере данных, прежде чем настраивать системы в продакшне.

<Steps>
  <Step>
    #### Скачайте пример данных

    Скачайте пример файла журнала:

    ```bash theme={null}
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log
    ```
  </Step>

  <Step>
    #### Создайте тестовую конфигурацию коллектора

    Создайте файл `kafka-logs-demo.yaml` со следующей конфигурацией:

    ```yaml theme={null}
    cat > kafka-logs-demo.yaml << 'EOF'
    receivers:
      filelog/kafka:
        include:
          - /tmp/kafka-demo/server.log
        start_at: beginning
        multiline:
          line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
        operators:
          - type: regex_parser
            regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
            parse_from: body
            parse_to: attributes
            timestamp:
              parse_from: attributes.timestamp
              layout: '%Y-%m-%d %H:%M:%S,%L'
            severity:
              parse_from: attributes.severity

          - type: move
            from: attributes.message
            to: body

          - type: add
            field: attributes.source
            value: "kafka-demo"

          - type: add
            field: resource["service.name"]
            value: "kafka-demo"

    service:
      pipelines:
        logs/kafka-demo:
          receivers: [filelog/kafka]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    EOF
    ```
  </Step>

  <Step>
    #### Запустите ClickStack с демо-конфигурацией

    Запустите ClickStack с демо-журналами и этой конфигурацией:

    ```bash theme={null}
    docker run --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
      clickhouse/clickstack-all-in-one:latest
    ```

    ## Проверьте журналы в HyperDX

    После запуска ClickStack:

    1. Откройте [HyperDX](http://localhost:8080/) и войдите в свою учётную запись (возможно, сначала потребуется создать её)
    2. Перейдите в представление Search и выберите источник `Logs`
    3. Установите временной диапазон, включающий **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=0cbc6a497240c66d8cd5e701df69296a" alt="Представление Search" width="3838" height="1934" data-path="images/clickstack/kafka/logs/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=3f2cea15008a854c416a9d41a848fb97" alt="Представление логов" width="3838" height="1934" data-path="images/clickstack/kafka/logs/log-view.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## Панели мониторинга и визуализация
</div>

<Steps>
  <Step>
    #### <TrackedLink href={'/ru/examples/kafka-logs-dashboard.json'} download="kafka-logs-dashboard.json" eventName="docs.kafka_logs_monitoring.dashboard_download">Скачайте</TrackedLink> конфигурацию панели мониторинга
  </Step>

  <Step>
    #### Импорт преднастроенного дашборда

    1. Откройте HyperDX и перейдите в раздел Dashboards.
    2. Нажмите "Import Dashboard" в правом верхнем углу в меню с многоточием.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="Импорт панели мониторинга" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. Загрузите файл kafka-logs-dashboard.json и нажмите finish import.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/finish-import.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=9ca23c6a49c13b817e5a1909e4741de1" alt="Завершение импорта панели мониторинга журналов Kafka" width="3382" height="1934" data-path="images/clickstack/kafka/logs/finish-import.png" />
  </Step>

  <Step>
    #### Панель мониторинга будет создана со всеми преднастроенными визуализациями

    Для демо-набора данных установите временной диапазон, включающий **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/kafka/logs/example-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=b1ebdcea60f05a9e1c85f2b6284af285" alt="Пример панели мониторинга журналов Kafka" width="3838" height="1934" data-path="images/clickstack/kafka/logs/example-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## Устранение неполадок
</div>

**Убедитесь, что фактическая конфигурация включает ваш приёмник filelog:**

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
```

**Проверьте ошибки коллектора:**

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log
```

**Проверьте, что формат логирования Kafka соответствует ожидаемому шаблону:**

```bash theme={null}
tail -1 /var/log/kafka/server.log
```

Если в вашей установке Kafka используется пользовательский шаблон Log4j, соответствующим образом настройте регулярное выражение для `regex_parser`.

<div id="next-steps">
  ## Дальнейшие шаги
</div>

* Настройте [оповещения](/ru/clickstack/features/alerts) для критически важных событий (сбои брокеров, ошибки репликации, проблемы consumer group)
* Используйте вместе с [Kafka Metrics](/ru/clickstack/integration-examples/kafka-metrics) для комплексного мониторинга Kafka
* Создайте дополнительные [панели мониторинга](/ru/clickstack/features/dashboards/overview) для конкретных сценариев использования (события контроллера, перераспределение партиций)

<div id="going-to-production">
  ## Переход в продакшн
</div>

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для развертываний в продакшне мы рекомендуем запускать собственный OTel Collector и отправлять данные в конечную точку OTLP ClickStack. См. [Отправка данных OpenTelemetry](/ru/clickstack/ingesting-data/opentelemetry) для настройки конфигурации продакшна.