Перенос агентов из 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 для сбора всех логов, метрик и трассировок, развертывая коллектор на границе в роли агента. Это представляет собой наиболее эффективное средство передачи данных и избегает архитектурной сложности и преобразования данных.

Почему OpenTelemetry Collector?

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

ClickHouse OpenTelemetry endpoint

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

Пользователи отправляют данные в этот коллектор из SDK для языков программирования или через агентов сбора данных, собирающих метрики и логи инфраструктуры (такие как OTel коллектора в роли агента или других технологий, например, Fluentd или Vector).

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

Миграция от 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 Collector через OTLP.

Мы иллюстрируем обе эти архитектуры ниже.

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

Установите vector

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

Это можно установить на том же экземпляре, что и ваш Elastic Stack OTel collector.

Пользователи могут следовать лучшим практикам в отношении архитектуры и безопасности при перемещении Vector в продакшн.

Настройте vector

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

sources:
  beats:
    type: logstash
    address: 0.0.0.0:5044
    tls:
      enabled: false  # Set to true if you're using TLS
      # The files below are generated from the steps at 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 source. Наш сценарий remap показан ниже. Этот сценарий был протестирован только с лог-событиями, но может служить основой для других форматов.

VRL - ECS в OTel

# Define keys to ignore at root level
ignored_keys = ["@metadata"]


# Define resource key prefixes
resource_keys = ["host", "cloud", "agent", "service"]


# Create separate objects for resource and log record fields
resource_obj = {}
log_record_obj = {}


# Copy all non-ignored root keys to appropriate objects
root_keys = keys(.)
for_each(root_keys) -> |_index, key| {
    if !includes(ignored_keys, key) {
        val, err = get(., [key])
        if err == null {
            # Check if this is a resource field
            is_resource = false
            if includes(resource_keys, key) {
                is_resource = true
            }

            # Add to appropriate object
            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
            }
        }
    }
}


# Flatten both objects separately
flattened_resources = flatten(resource_obj, separator: ".")
flattened_logs = flatten(log_record_obj, separator: ".")


# Process resource attributes
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)
        }
    }
}


# Process log record attributes
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)
        }
    }
}


# Get timestamp for timeUnixNano (convert to nanoseconds)
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")
}


# Get message/body field
body_value = if exists(.message) {
    to_string!(.message)
} else if exists(.body) {
    to_string!(.body)
} else {
    ""
}


# Create the OpenTelemetry structure
. = {
    "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 sink в Vector, который принимает события из трансформации remap_filebeat в качестве входных данных:

sinks:
  otlp:
    type: opentelemetry
    inputs: [remap_filebeat] # receives events from a remap transform - see below
    protocol:
      type: http  # Use "grpc" for port 4317
      uri: http://localhost:4318/v1/logs # logs endpoint for the 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. Вы можете найти ключ в приложении HyperDX в разделе Настройки команды → Ключи API.

Наша окончательная полная конфигурация показана ниже:

sources:
  beats:
    type: logstash
    address: 0.0.0.0:5044
    tls:
      enabled: false  # Set to true if you're using 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  # Use "grpc" for port 4317
      uri: http://localhost:4318/v1/logs
      method: post
      encoding:
        codec: json
      framing:
        method: newline_delimited
      headers:
        content-type: application/json

Настройте Filebeat

Существующие установки Filebeat просто нужно изменить, чтобы они отправляли свои события в Vector. Это требует настройки вывода Logstash - опять же, TLS можно настроить опционально:

# ------------------------------ Logstash Output -------------------------------
output.logstash:
  # The Logstash hosts
  hosts: ["localhost:5044"]

  # Optional SSL. By default is off.
  # List of root certificates for HTTPS server verifications
  #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]

  # Certificate for SSL client authentication
  #ssl.certificate: "/etc/pki/client/cert.pem"

  # Client Certificate Key
  #ssl.key: "/etc/pki/client/cert.key"

Миграция от Elastic Agent

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

Пользователи с установленными Elastic Agents имеют несколько путей миграции:

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

Мы демонстрируем оба этих варианта ниже.

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

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

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

Настройте Elastic Agent

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

Централизованная конфигурация через Kibana может быть достигнута путем добавления вывода в Fleet.

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

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

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

sources:
  beats:
    type: logstash
    address: 0.0.0.0:5044
    tls:
      enabled: true  # Set to true if you're using TLS. 
      # The files below are generated from the steps at 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, который позволяет вам инструментировать ваши приложения и инфраструктуру один раз и отправлять данные нескольким поставщикам и бэкендам.

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

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

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

exporters:
  # Exporter to send logs and metrics to Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: true

YOUR_INGESTION_API_KEY здесь выдается ClickStack. Вы можете найти ключ в приложении HyperDX в разделе Настройки команды → Ключи API.

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

exporters:
  # Exporter to send logs and metrics to 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 collector через OTLP. Этапы, необходимые для этого, идентичны тем, что описаны выше для запуска Elastic Agent как OpenTelemetry collector. Этот подход можно использовать для всех типов данных.