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

Все данные поступают в 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

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

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

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

Настройка vector

Vector необходимо настроить для приёма событий по протоколу Lumberjack, имитируя экземпляр Logstash. Для этого нужно настроить источник logstash для 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

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

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

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

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-приёмник в 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. Ключ можно найти в интерфейсе ClickStack (HyperDX) в разделе Team Settings → API Keys.

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

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 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

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

Настройка 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 включает встроенный EDOT Collector, который позволяет один раз настроить сбор телеметрии для приложений и инфраструктуры и отправлять данные разным вендорам и backend-системам.

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

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. Найти его можно в интерфейсе ClickStack в разделе Team Settings → API Keys.

Если Vector настроен на использование взаимного TLS, а сертификат и ключи сгенерированы по инструкции из руководства "Настройка SSL/TLS для Logstash output", то экспортер 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 (EDOT), могут просто перенастроить свои агенты так, чтобы они отправляли данные в коллектор ClickStack OpenTelemetry через OTLP. Необходимые шаги полностью совпадают с описанными выше для запуска Elastic Agent в качестве OpenTelemetry Collector. Этот подход можно использовать для всех типов данных.