Получение данных логов

Обзор

Компонент proto-log-storage принимает лог-записи по нескольким HTTP API, что позволяет интегрировать различные коллекторы и агенты:

Ниже приведены инструкции по настройке наиболее распространённых агентов и коллекторов.

OpenTelemetry Collector

OpenTelemetry Collector (https://opentelemetry.io/docs/collector/) — универсальный агент для сбора, обработки и экспорта телеметрических данных. Proto Observability Platform поддерживает приём логов от Collector по протоколу OTLP/HTTP, а также через Elasticsearch-совместимый экспортёр.

Вариант 1: OTLP/HTTP экспортёр (рекомендуется)

Используйте экспортёр otlphttp для отправки логов напрямую в proto-log-storage по протоколу OpenTelemetry.

Минимальная конфигурация Collector (otel-collector-config.yaml):

receivers:
  filelog:
    include:
      - /var/log/app/*.log
    resource:
      service.name: my-service
      deployment.environment: production

exporters:
  otlphttp:
    logs_endpoint: http://<proto-log-storage-host>:9428/insert/opentelemetry/v1/logs

service:
  pipelines:
    logs:
      receivers: [filelog]
      exporters: [otlphttp]

Замените <proto-log-storage-host> на адрес вашего экземпляра proto-log-storage.

Дополнительные параметры через HTTP-заголовки:

Все параметры управления полями можно передавать через HTTP-заголовки в блоке headers экспортёра:

exporters:
  otlphttp:
    logs_endpoint: http://<proto-log-storage-host>:9428/insert/opentelemetry/v1/logs
    headers:
      VL-Stream-Fields: host.name,service.name,deployment.environment
      VL-Ignore-Fields: internal_id,debug_token

Вариант 2: Elasticsearch экспортёр

Если в вашей инфраструктуре уже настроен Elasticsearch-совместимый экспортёр, его можно направить на proto-log-storage:

receivers:
  filelog:
    include:
      - /var/log/app/*.log
    resource:
      region: ru-central1

exporters:
  elasticsearch:
    endpoints:
      - http://<proto-log-storage-host>:9428/insert/elasticsearch
    headers:
      VL-Msg-Field: Body

service:
  pipelines:
    logs:
      receivers: [filelog]
      exporters: [elasticsearch]

Поддерживаемые ресиверы

OpenTelemetry Collector поддерживает множество ресиверов для сбора логов из различных источников:

• filelog — чтение лог-файлов с диска
• journald — сбор логов systemd journal
• syslog — приём syslog-сообщений (RFC 3164 / RFC 5424)
• tcplog / udplog — приём логов по TCP/UDP
• windowseventlog — сбор событий Windows Event Log
• otlp — приём логов от других OpenTelemetry-компонентов

Полный список ресиверов доступен в реестре OpenTelemetry Collector (https://opentelemetry.io/docs/collector/components/).

Пример: сбор логов из нескольких источников

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    resource:
      service.name: nginx

  journald:
    units:
      - my-app.service
      - another-service.service
    resource:
      service.name: systemd

exporters:
  otlphttp:
    logs_endpoint: http://<proto-log-storage-host>:9428/insert/opentelemetry/v1/logs
    headers:
      VL-Stream-Fields: service.name

processors:
  batch:
    send_batch_size: 1000
    timeout: 5s

service:
  pipelines:
    logs:
      receivers: [filelog, journald]
      processors: [batch]
      exporters: [otlphttp]

Проверка работы

После запуска Collector проверьте, что логи поступают, выполнив запрос к proto-log-storage:

curl http://<proto-log-storage-host>:9428/select/logsql/query -d 'query=*' | head

ProtoOBP Агент

ProtoOBP Агент — встроенный агент платформы Proto Observability Platform для сбора логов. Агент отправляет лог-записи через HTTP API, совместимое с DataDog Agent API, что обеспечивает надёжную передачу данных в proto-log-storage.

Требования

• Установленный ProtoOBP Агент (версия 7.x или новее)
• Сетевой доступ к proto-log-storage (порт по умолчанию: 9428)

Настройка сбора логов

Шаг 1: Включение сбора логов

В конфигурационном файле агента (pobp.yaml) включите сбор логов:

logs_enabled: true
logs_config:
  logs_pobp_url: <proto-log-storage-proxy-host>:<port>
  use_http: true

Замените <proto-log-storage-proxy-host>:<port> на адрес обратного прокси, за которым расположен proto-log-storage (см. раздел «Настройка обратного прокси» ниже).

Шаг 2: Настройка источников логов

Создайте конфигурационный файл для каждого источника логов в директории conf.d/:

Пример: сбор логов из файла (conf.d/myapp.d/conf.yaml):

logs:
  - type: file
    path: /var/log/myapp/*.log
    service: my-application
    source: myapp
    tags:
      - env:production
      - team:backend

Пример: сбор логов Docker-контейнера (conf.d/docker.d/conf.yaml):

logs:
  - type: docker
    service: my-container
    source: docker

Пример: сбор логов journald (conf.d/journald.d/conf.yaml):

logs:
  - type: journald
    include_units:
      - my-service.service
    source: journald

Шаг 3: Настройка через переменные окружения

Альтернативно, агент можно сконфигурировать полностью через переменные окружения:

Настройка обратного прокси

ProtoOBP Агент отправляет логи по фиксированным API-путям (например, /api/v2/logs), которые необходимо перенаправить на соответствующие эндпоинты proto-log-storage. Для этого используется обратный прокси.

Конфигурация обратного прокси:

unauthorized_user:
  url_map:
    - src_paths:
        - "/api/v2/logs"
        - "/api/v1/validate"
      url_prefix: http://<proto-log-storage-host>:9428/insert/datadog/

Замените <proto-log-storage-host> на адрес вашего экземпляра proto-log-storage.

Шаг 4: Перезапуск агента

После внесения изменений в конфигурацию перезапустите ProtoOBP Агент:

sudo systemctl restart protoobp-agent

Проверка работы

Убедитесь, что агент отправляет логи:

# Проверка статуса агента
sudo protoobp-agent status

# Проверка поступления логов в proto-log-storage
curl http://<proto-log-storage-host>:9428/select/logsql/query -d 'query=*' | head

DataDog Agent

Proto Observability Platform совместима с DataDog Agent для сбора логов. Если в вашей инфраструктуре уже используется DataDog Agent, его можно перенаправить на proto-log-storage с минимальными изменениями конфигурации.

Требования

• DataDog Agent версии 6.x или новее
• Обратный прокси для перенаправления запросов (DataDog Agent не поддерживает настройку произвольных URL-путей)

Настройка

Шаг 1: Настройка обратного прокси

DataDog Agent отправляет логи на фиксированные API-пути (/api/v2/logs), которые необходимо перенаправить на эндпоинты proto-log-storage.

Конфигурация обратного прокси:

unauthorized_user:
  url_map:
    - src_paths:
        - "/api/v2/logs"
        - "/api/v1/validate"
      url_prefix: http://<proto-log-storage-host>:9428/insert/datadog/
    - src_paths:
        - "/api/v1/series"
        - "/api/v2/series"
        - "/api/beta/sketches"
        - "/api/v1/check_run"
        - "/intake"
        - "/api/v1/metadata"
      url_prefix: http://<proto-metric-storage-host>:8428/datadog/

Замените <proto-log-storage-host> и <proto-metric-storage-host> на адреса ваших экземпляров.

Шаг 2: Настройка DataDog Agent

В конфигурационном файле DataDog Agent (datadog.yaml) перенаправьте отправку логов через обратный прокси:

logs_enabled: true
logs_config:
  logs_dd_url: <proxy-host>:<proxy-port>
  use_http: true

Шаг 3: Настройка источников логов

Создайте конфигурационные файлы источников логов в директории conf.d/:

Пример: сбор логов приложения (conf.d/myapp.d/conf.yaml):

logs:
  - type: file
    path: /var/log/myapp/*.log
    service: my-application
    source: myapp

Пример: сбор логов Docker-контейнера (conf.d/docker.d/conf.yaml):

logs:
  - type: docker
    service: my-container
    source: docker

Шаг 4: Настройка через переменные окружения

DataDog Agent также поддерживает настройку через переменные окружения:

Управление полями

При приёме логов от DataDog Agent можно управлять обработкой полей:

• Исключение полей: передайте список полей для исключения через заголовок VL-Ignore-Fields или параметр запроса ignore_fields. Поддерживается подстановка prefix*.
• Потоковые поля: передайте список полей для определения лог-потоков через заголовок VL-Stream-Fields или параметр запроса _stream_fields.

Проверка работы

# Проверка статуса агента
sudo datadog-agent status

# Проверка поступления логов в proto-log-storage
curl http://<proto-log-storage-host>:9428/select/logsql/query -d 'query=*' | head

Другие способы получения данных

Следующие коллекторы и агенты также совместимы с proto-log-storage. Документация по ним находится в разработке и предоставляется по запросу.

Для получения инструкций по настройке этих коллекторов обратитесь в службу технической поддержки.

Общие параметры HTTP API

Все HTTP API proto-log-storage поддерживают единый набор параметров, передаваемых как через строку запроса (query string), так и через HTTP-заголовки.

Параметры строки запроса

HTTP-заголовки

Параметры строки запроса имеют приоритет над HTTP-заголовками.

Устранение неполадок

Проверка поступления логов

Выполните запрос ко всем записям:

curl http://<proto-log-storage-host>:9428/select/logsql/query -d 'query=*' | head

Режим отладки

Для проверки формата данных без их сохранения используйте параметр debug=1:

curl -X POST -H 'Content-Type: application/json' \
  'http://<proto-log-storage-host>:9428/insert/jsonline?debug=1' \
  --data-binary '{"_msg":"test message","_time":"0"}'

В этом режиме записи логируются, но не сохраняются в хранилище.

Полезные метрики