Перенос агентов из Elastic

Перенос агентов из Elastic

​

Миграция агентов из Elastic

Elastic Stack предоставляет ряд агентов для сбора данных обсервабилити. В частности:

• Семейство Beats — например, Filebeat, Metricbeat и Packetbeat — основано на библиотеке libbeat. Эти Beats поддерживают отправку данных в Elasticsearch, Kafka, Redis или Logstash по протоколу Lumberjack.
• Elastic Agent — это унифицированный агент, способный собирать журналы, метрики и трассировки. Им можно централизованно управлять через Elastic Fleet Server, также он поддерживает вывод в Elasticsearch, Logstash, Kafka или Redis.
• Elastic также предоставляет дистрибутив OpenTelemetry Collector — EDOT. Хотя сейчас им нельзя управлять через Fleet Server, он предлагает более гибкий и открытый путь при миграции на ClickStack.

Оптимальный путь миграции зависит от того, какие агенты используются сейчас. В следующих разделах мы рассматриваем варианты миграции для каждого основного типа агентов. Наша цель — свести сложности к минимуму и, где это возможно, дать вам возможность продолжать использовать существующих агентов в процессе перехода.

​

Предпочтительный путь миграции

По возможности мы рекомендуем переходить на OpenTelemetry (OTel) Collector для сбора всех логов, метрик и трасс, развёртывая collector на периферии в роли агента. Это наиболее эффективный способ отправки данных, позволяющий избежать усложнения архитектуры и преобразования данных.

Почему OpenTelemetry Collector?

OpenTelemetry Collector предоставляет устойчивое, не зависящее от вендора решение для ингестии данных обсервабилити. Мы понимаем, что некоторые организации управляют парком из тысяч — а иногда и десятков тысяч — агентов Elastic. Для таких пользователей поддержание совместимости с существующей инфраструктурой агентов может быть критически важным. Эта документация призвана поддержать такой сценарий, а также помочь командам постепенно перейти на сбор данных на базе OpenTelemetry.

​

Конечная точка ClickHouse OpenTelemetry

Все данные поступают в ClickStack через экземпляр OpenTelemetry (OTel) Collector, который служит основной точкой входа для журналов, метрик, трассировок и данных сеансов. Для этого экземпляра мы рекомендуем использовать официальный дистрибутив ClickStack для Collector, если он еще не включен в вашу модель развертывания ClickStack.

Пользователи отправляют данные в этот OTel Collector из language SDKs или через агенты сбора данных, которые собирают метрики инфраструктуры и журналы (например, OTel Collectors в роли агента или другие технологии, такие как Fluentd или Vector). Для команд, которым нужен управляемый конвейер OpenTelemetry, Bindplane предлагает решение, нативное для OpenTelemetry, со встроенным пунктом назначения ClickStack, упрощающее сбор, обработку и маршрутизацию телеметрии.

Мы предполагаем, что этот OTel Collector доступен для всех шагов миграции агентов.

​

Миграция с Beats

Пользователи с крупными развертываниями Beats могут захотеть сохранить их при переходе на ClickStack.

На данный момент этот вариант протестирован только с Filebeat, поэтому он подходит только для журналов.

Агенты Beats используют Elastic Common Schema (ECS), которая сейчас интегрируется в спецификацию OpenTelemetry, используемую ClickStack. Однако эти схемы по-прежнему существенно различаются, и сейчас пользователи сами должны преобразовывать события в формате ECS в формат OpenTelemetry перед ингестией в ClickStack.

Мы рекомендуем выполнять это преобразование с помощью Vector — лёгкого и высокопроизводительного конвейера данных для обсервабилити, который поддерживает мощный язык преобразования под названием Vector Remap Language (VRL).

Если ваши агенты Filebeat настроены на отправку данных в Kafka — один из поддерживаемых Beats выходов, — Vector может получать эти события из Kafka, применять преобразования схемы с помощью VRL, а затем пересылать их по OTLP в OpenTelemetry Collector, входящий в состав ClickStack.

Кроме того, Vector также поддерживает приём событий по протоколу Lumberjack, используемому Logstash. Это позволяет агентам Beats отправлять данные напрямую в Vector, где перед пересылкой в коллектор ClickStack OpenTelemetry по OTLP можно применить тот же процесс преобразования.

Ниже показаны обе эти архитектуры.

В следующем примере мы приводим начальные шаги по настройке Vector для приёма событий журналов от Filebeat по протоколу Lumberjack. Мы также приводим VRL для преобразования входящих ECS-событий в формат спецификации OTel перед отправкой в коллектор ClickStack OpenTelemetry по OTLP. Пользователи, получающие события из Kafka, могут заменить источник Vector Logstash на источник Kafka — все остальные шаги остаются теми же.

1. ​

   Установка Vector

   Установите Vector, следуя официальному руководству по установке.

   Его можно установить на том же инстансе, где развернут ваш OTel collector для Elastic Stack.

   Вы можете воспользоваться рекомендациями по архитектуре и безопасности при подготовке Vector к промышленной эксплуатации.

2. ​

   Настройка vector

   Vector необходимо настроить для приёма событий по протоколу Lumberjack, имитируя экземпляр Logstash. Для этого нужно настроить источник logstash для Vector:

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Установите значение true, если используете TLS
         # Файлы ниже создаются по инструкциям по адресу https://www.elastic.co/docs/reference/fleet/secure-logstash-connections#generate-logstash-certs
         # crt_file: logstash.crt
         # key_file: logstash.key
         # ca_file: ca.crt
         # verify_certificate: true
   

   Настройка TLS

   Если требуется взаимный TLS, сгенерируйте сертификаты и ключи, следуя руководству Elastic “Настройка SSL/TLS для вывода Logstash”. Затем их можно указать в конфигурации, как показано выше.

   События будут поступать в формате ECS. Их можно преобразовать в схему OpenTelemetry с помощью трансформера Vector Remap Language (VRL). Настройка этого трансформера проста — скрипт хранится в отдельном файле:

   transforms:
     remap_filebeat:
       inputs: ["beats"]
       type: "remap"
       file: 'beat_to_otel.vrl'
   

   Обратите внимание, что он получает события из указанного выше источника beats. Скрипт переопределения приведён ниже. Он протестирован только с событиями логов, однако может служить основой для работы с другими форматами.

   VRL — из ECS в OTel

   # Определить ключи для игнорирования на корневом уровне
   ignored_keys = ["@metadata"]
   
   # Определить префиксы ключей ресурсов
   resource_keys = ["host", "cloud", "agent", "service"]
   
   # Создать отдельные объекты для полей ресурса и записи журнала
   resource_obj = {}
   log_record_obj = {}
   
   # Скопировать все неигнорируемые корневые ключи в соответствующие объекты
   root_keys = keys(.)
   for_each(root_keys) -> |_index, key| {
       if !includes(ignored_keys, key) {
           val, err = get(., [key])
           if err == null {
               # Проверить, является ли это поле полем ресурса
               is_resource = false
               if includes(resource_keys, key) {
                   is_resource = true
               }
   
               # Добавить в соответствующий объект
               if is_resource {
                   resource_obj = set(resource_obj, [key], val) ?? resource_obj
               } else {
                   log_record_obj = set(log_record_obj, [key], val) ?? log_record_obj
               }
           }
       }
   }
   
   # Выполнить выравнивание обоих объектов по отдельности
   flattened_resources = flatten(resource_obj, separator: ".")
   flattened_logs = flatten(log_record_obj, separator: ".")
   
   # Обработать атрибуты ресурса
   resource_attributes = []
   resource_keys_list = keys(flattened_resources)
   for_each(resource_keys_list) -> |_index, field_key| {
       field_value, err = get(flattened_resources, [field_key])
       if err == null && field_value != null {
           attribute, err = {
               "key": field_key,
               "value": {
                   "stringValue": to_string(field_value)
               }
           }
           if (err == null) {
               resource_attributes = push(resource_attributes, attribute)
           }
       }
   }
   
   # Обработать атрибуты записи журнала
   log_attributes = []
   log_keys_list = keys(flattened_logs)
   for_each(log_keys_list) -> |_index, field_key| {
       field_value, err = get(flattened_logs, [field_key])
       if err == null && field_value != null {
           attribute, err = {
               "key": field_key,
               "value": {
                   "stringValue": to_string(field_value)
               }
           }
           if (err == null) {
               log_attributes = push(log_attributes, attribute)
           }
       }
   }
   
   # Получить временную метку для timeUnixNano (преобразовать в наносекунды)
   timestamp_nano = if exists(.@timestamp) {
       to_unix_timestamp!(parse_timestamp!(.@timestamp, format: "%Y-%m-%dT%H:%M:%S%.3fZ"), unit: "nanoseconds")
   } else {
       to_unix_timestamp(now(), unit: "nanoseconds")
   }
   
   # Получить поле message/body
   body_value = if exists(.message) {
       to_string!(.message)
   } else if exists(.body) {
       to_string!(.body)
   } else {
       ""
   }
   
   # Создать структуру OpenTelemetry
   . = {
       "resourceLogs": [
           {
               "resource": {
                   "attributes": resource_attributes
               },
               "scopeLogs": [
                   {
                       "scope": {},
                       "logRecords": [
                           {
                               "timeUnixNano": to_string(timestamp_nano),
                               "severityNumber": 9,
                               "severityText": "info",
                               "body": {
                                   "stringValue": body_value
                               },
                               "attributes": log_attributes
                           }
                       ]
                   }
               ]
           }
       ]
   }
   

   Наконец, преобразованные события можно отправить в ClickStack через OpenTelemetry Collector по протоколу OTLP. Для этого нужно настроить OTLP-приёмник в Vector, который получает события из преобразования remap_filebeat на входе:

   sinks:
     otlp:
       type: opentelemetry
       inputs: [remap_filebeat] # получает события из преобразования remap — см. ниже
       protocol:
         type: http  # Используйте "grpc" для порта 4317
         uri: http://localhost:4318/v1/logs # конечная точка журналов для OTel collector 
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
           authorization: ${YOUR_INGESTION_API_KEY}
   

   YOUR_INGESTION_API_KEY здесь генерируется ClickStack. Ключ можно найти в интерфейсе ClickStack (HyperDX) в разделе Team Settings → API Keys.

   Итоговая полная конфигурация приведена ниже:

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Установите true, если используете TLS
           #crt_file: /data/elasticsearch-9.0.1/logstash/logstash.crt
           #key_file: /data/elasticsearch-9.0.1/logstash/logstash.key
           #ca_file: /data/elasticsearch-9.0.1/ca/ca.crt
           #verify_certificate: true
   
   transforms:
     remap_filebeat:
       inputs: ["beats"]
       type: "remap"
       file: 'beat_to_otel.vrl'
   
   sinks:
     otlp:
       type: opentelemetry
       inputs: [remap_filebeat]
       protocol:
         type: http  # Используйте "grpc" для порта 4317
         uri: http://localhost:4318/v1/logs
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
   
3. ​

   Настройка Filebeat

   Существующие установки Filebeat достаточно просто перенастроить, чтобы они отправляли события в Vector. Для этого нужно настроить выход Logstash — при необходимости также можно настроить TLS:

   # ------------------------------ Logstash Output -------------------------------
   output.logstash:
     # Хосты Logstash
     hosts: ["localhost:5044"]
   
     # Необязательный SSL. По умолчанию отключён.
     # Список корневых сертификатов для проверки HTTPS-сервера
     #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
   
     # Сертификат для аутентификации SSL-клиента
     #ssl.certificate: "/etc/pki/client/cert.pem"
   
     # Ключ сертификата клиента
     #ssl.key: "/etc/pki/client/cert.key"
   

​

Переход с Elastic Agent

Elastic Agent объединяет различные Elastic Beats в единый пакет. Этот агент интегрируется с Elastic Fleet, что позволяет централизованно управлять им и настраивать его.

Для пользователей с уже развернутым Elastic Agent доступно несколько вариантов миграции:

• Настройте агент на отправку данных в конечную точку Vector по протоколу Lumberjack. На данный момент этот вариант протестирован только для пользователей, которые собирают с помощью Elastic Agent только логи. Это можно централизованно настроить через интерфейс Fleet в Kibana.
• Запустите агент как Elastic OpenTelemetry Collector (EDOT). Elastic Agent включает встроенный EDOT Collector, который позволяет один раз инструментировать приложения и инфраструктуру, а затем отправлять данные нескольким вендорам и в разные бэкенды. В этой конфигурации можно просто настроить EDOT Collector на пересылку событий в OTel collector ClickStack по OTLP. Этот подход поддерживает все типы событий.

Ниже мы покажем оба варианта.

​

Отправка данных через Vector

1. ​

   Установка и настройка Vector

   Установите и настройте Vector, выполнив те же шаги, что описаны в инструкции по миграции с Filebeat.

2. ​

   Настройка Elastic Agent

   Elastic Agent необходимо настроить на отправку данных через протокол Lumberjack для Logstash. Это поддерживаемый сценарий развертывания; его можно настроить централизованно или через файл конфигурации агента elastic-agent.yaml, если развертывание выполняется без Fleet.

   Централизованную настройку через Kibana можно выполнить, добавив Output в Fleet.

   Затем этот output можно использовать в политике агента. Это означает, что все агенты, использующие эту политику, будут автоматически отправлять данные в Vector.

   Поскольку для этого требуется настроить безопасное соединение по TLS, рекомендуем руководство “Настройка SSL/TLS для Logstash output”. При его выполнении считайте, что экземпляр Vector пользователя выступает в роли Logstash.

   Обратите внимание: для этого пользователям также нужно настроить источник Logstash в Vector на взаимный TLS. Используйте ключи и сертификаты, созданные по этому руководству, чтобы соответствующим образом настроить входной источник.

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: true  # Установите значение true, если используете TLS. 
         # Файлы ниже создаются на шагах из https://www.elastic.co/docs/reference/fleet/secure-logstash-connections#generate-logstash-certs
         crt_file: logstash.crt
         key_file: logstash.key
         ca_file: ca.crt
         verify_certificate: true
   

​

Запуск Elastic Agent в качестве OpenTelemetry Collector

Elastic Agent включает встроенный EDOT Collector, который позволяет один раз настроить сбор телеметрии для приложений и инфраструктуры и отправлять данные разным вендорам и backend-системам.

Интеграции агента и оркестрация

Пользователи, запускающие коллектор EDOT, поставляемый вместе с Elastic Agent, не смогут использовать существующие интеграции агента. Кроме того, коллектором нельзя централизованно управлять через Fleet, из-за чего пользователю придется запускать агент в автономном режиме и самостоятельно управлять конфигурацией.

Чтобы запустить Elastic Agent с коллектором EDOT, см. официальное руководство Elastic. Вместо настройки конечной точки Elastic, как указано в руководстве, удалите существующие exporters и настройте вывод OTLP, чтобы отправлять данные в коллектор ClickStack OpenTelemetry. Например, конфигурация exporters будет такой:

exporters:
  # Экспортёр для отправки журналов и метрик в Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: true

Управляемый ClickStack

По умолчанию ключ API для ингестии ClickStack не требуется, если вы запускаете OpenTelemetry Collector в автономном режиме для Управляемого ClickStack. Однако ингестию можно защитить, указав токен аутентификации OTLP. См. “Защита коллектора”.

Ключ YOUR_INGESTION_API_KEY здесь генерируется в ClickStack. Найти его можно в интерфейсе ClickStack в разделе Team Settings → API Keys.

Если Vector настроен на использование взаимного TLS, а сертификат и ключи сгенерированы по инструкции из руководства “Настройка SSL/TLS для вывода Logstash”, то экспортер otlp нужно настроить соответствующим образом, например:

exporters:
  # Экспортёр для отправки журналов и метрик в Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: false
      ca_file: /path/to/ca.crt
      cert_file: /path/to/client.crt
      key_file: /path/to/client.key

​

Переход с Elastic OpenTelemetry Collector

Пользователи, уже использующие Elastic OpenTelemetry Collector (EDOT), могут просто перенастроить свои агенты так, чтобы они отправляли данные в коллектор ClickStack OpenTelemetry через OTLP. Необходимые шаги полностью совпадают с описанными выше для запуска Elastic Agent в качестве OpenTelemetry Collector. Этот подход можно использовать для всех типов данных.