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.
Все данные поступают в ClickStack через экземпляр OpenTelemetry (OTel) Collector, который служит основной точкой входа для журналов, метрик, трассировок и данных сеансов. Для этого экземпляра мы рекомендуем использовать официальный дистрибутив ClickStack для Collector, если он еще не включен в вашу модель развертывания ClickStack.Пользователи отправляют данные в этот OTel Collector из language SDKs или через агенты сбора данных, которые собирают метрики инфраструктуры и журналы (например, OTel Collectors в роли агента или другие технологии, такие как Fluentd или Vector). Для команд, которым нужен управляемый конвейер OpenTelemetry, Bindplane предлагает решение, нативное для OpenTelemetry, со встроенным пунктом назначения ClickStack, упрощающее сбор, обработку и маршрутизацию телеметрии.Мы предполагаем, что этот OTel Collector доступен для всех шагов миграции агентов.
Пользователи с крупными развертываниями 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 — все остальные шаги остаются теми же.
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). Настройка этого трансформера проста — скрипт хранится в отдельном файле:
Обратите внимание, что он получает события из указанного выше источника 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/bodybody_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.Итоговая полная конфигурация приведена ниже:
Существующие установки 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 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. Этот подход поддерживает все типы событий.
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 (EDOT), могут просто перенастроить свои агенты так, чтобы они отправляли данные в коллектор ClickStack OpenTelemetry через OTLP. Необходимые шаги полностью совпадают с описанными выше для запуска Elastic Agent в качестве OpenTelemetry Collector. Этот подход можно использовать для всех типов данных.
