> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/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 = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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

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

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

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

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

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

<Steps>
  <Step title="Проверьте конфигурацию логирования Kafka" id="verify-kafka">
    Kafka использует Log4j и записывает журналы в каталог, указанный в системном свойстве `kafka.logs.dir` или переменной окружения `LOG_DIR`. Проверьте расположение файла журнала:

    ```bash theme={null}
    # Default locations
    ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
    ls /var/log/kafka/        # RPM/DEB package installations
    ```

    Основные файлы журнала 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 title="Создайте пользовательскую конфигурацию OTel collector для Kafka" id="custom-otel">
    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  # optional, only exists if log4j is configured with separate file appenders
          - /var/log/kafka/state-change.log  # optional, same as above
        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 title="Настройка ClickStack для загрузки пользовательской конфигурации" id="load-custom">
    Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании 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:
            # ... existing configuration ...
            environment:
              - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
              # ... other environment variables ...
            volumes:
              - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
              - /var/log/kafka:/var/log/kafka:ro
              # ... other volumes ...
        ```
      </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 title="Проверьте журналы в HyperDX" id="verifying-logs">
    После настройки войдите в HyperDX и убедитесь, что журналы поступают:

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

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

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

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

<Steps>
  <Step title="Скачать пример данных" id="download-sample">
    Скачайте пример файла журнала:

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

  <Step title="Создать тестовую конфигурацию коллектора" id="test-config">
    Создайте файл `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 title="Запустить ClickStack с демо-конфигурацией" id="run-demo">
    Запустите 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/MFPY913TqoHcFPXJ/images/clickstack/kafka/logs/search-view.webp?fit=max&auto=format&n=MFPY913TqoHcFPXJ&q=85&s=9b6f57cc232869dbcc0e69c3a60b7331" alt="Представление Search" width="3838" height="1934" data-path="images/clickstack/kafka/logs/search-view.webp" />

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

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

<Steps>
  <Step title="Скачайте конфигурацию панели мониторинга" id="download">
    <TrackedLink href={'https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/examples/kafka-logs-dashboard.json'} download="kafka-logs-dashboard.json" eventName="docs.kafka_logs_monitoring.dashboard_download">Скачайте файл конфигурации панели мониторинга</TrackedLink>.
  </Step>

  <Step title="Импорт преднастроенной панели мониторинга" id="import-dashboard">
    1. Откройте HyperDX и перейдите в раздел панелей мониторинга.
    2. Нажмите "Import Dashboard" в правом верхнем углу в меню с многоточием.

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

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

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

  <Step title="Панель мониторинга будет создана со всеми преднастроенными визуализациями" id="created-dashboard">
    Для демо-набора данных установите временной диапазон, включающий **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**.

    <Image img="https://mintcdn.com/private-7c7dfe99/MFPY913TqoHcFPXJ/images/clickstack/kafka/logs/example-dashboard.webp?fit=max&auto=format&n=MFPY913TqoHcFPXJ&q=85&s=805ba1c557f83f844eee9bcac595a5ba" alt="Пример панели мониторинга журналов Kafka" width="3838" height="1934" data-path="images/clickstack/kafka/logs/example-dashboard.webp" />
  </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>

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

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

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