Migración de agentes de Elastic

Elastic Stack ofrece varios agentes para recopilar datos de observabilidad. En concreto:

• La familia Beats, como Filebeat, Metricbeat y Packetbeat, todos basados en la biblioteca libbeat. Estos Beats admiten el envío de datos a Elasticsearch, Kafka, Redis o Logstash mediante el protocolo Lumberjack.
• El Elastic Agent proporciona un agente unificado capaz de recopilar logs, métricas y trazas. Este agente puede administrarse de forma centralizada a través de Elastic Fleet Server y admite la salida a Elasticsearch, Logstash, Kafka o Redis.
• Elastic también ofrece una distribución del OpenTelemetry Collector - EDOT. Aunque actualmente no puede orquestarse mediante Fleet Server, ofrece una vía más flexible y abierta si estás migrando a ClickStack.

La mejor estrategia de migración depende de los agentes que se estén utilizando actualmente. En las secciones siguientes, documentamos las opciones de migración para cada tipo principal de agente. Nuestro objetivo es minimizar la fricción y, cuando sea posible, permitirte seguir usando tus agentes actuales durante la transición.

Siempre que sea posible, recomendamos migrar a OpenTelemetry (OTel) Collector para toda la recopilación de logs, métricas y trazas, desplegando el collector en el edge con un rol de agente. Esta es la forma más eficiente de enviar datos y evita complejidad arquitectónica y transformaciones de datos.

Todos los datos se ingestan en ClickStack a través de una instancia de OpenTelemetry (OTel) collector, que actúa como punto de entrada principal para logs, métricas, trazas y datos de sesión. Recomendamos usar la distribución oficial de ClickStack del collector para esta instancia, si no ya está incluida en su modelo de despliegue de ClickStack.

Los usuarios envían datos a este collector desde SDKs de lenguajes o mediante agentes de recopilación de datos que recogen métricas de infraestructura y logs (como collectors de OTel en un rol de agente u otras tecnologías, como Fluentd o Vector). Para los equipos que quieren una pipeline de OpenTelemetry gestionada, Bindplane ofrece una solución nativa de OpenTelemetry con un destino nativo de ClickStack, lo que simplifica la recopilación, el procesamiento y el enrutamiento de telemetría.

Asumimos que este collector está disponible para todos los pasos de migración de agentes.

Los usuarios con despliegues extensos de Beats pueden querer conservarlos al migrar a ClickStack.

Actualmente, esta opción solo se ha probado con Filebeat y, por lo tanto, solo es adecuada para logs.

Los agentes de Beats usan el Elastic Common Schema (ECS), que actualmente se está integrando en la especificación de OpenTelemetry utilizada por ClickStack. Sin embargo, estos esquemas siguen difiriendo considerablemente, y actualmente son los usuarios quienes deben transformar los eventos con formato ECS al formato OpenTelemetry antes de su ingestión en ClickStack.

Recomendamos realizar esta transformación con Vector, una canalización de datos de observabilidad ligera y de alto rendimiento que admite un potente lenguaje de transformación llamado Vector Remap Language (VRL).

Si sus agentes de Filebeat están configurados para enviar datos a Kafka, una salida compatible con Beats, Vector puede consumir esos eventos desde Kafka, aplicar transformaciones de esquema con VRL y luego reenviarlos mediante OTLP al OpenTelemetry Collector distribuido con ClickStack.

Como alternativa, Vector también admite la recepción de eventos a través del protocolo Lumberjack utilizado por Logstash. Esto permite que los agentes de Beats envíen datos directamente a Vector, donde puede aplicarse el mismo proceso de transformación antes de reenviarlos al ClickStack OpenTelemetry Collector mediante OTLP.

A continuación, ilustramos ambas arquitecturas.

En el siguiente ejemplo, proporcionamos los pasos iniciales para configurar Vector de modo que reciba eventos de logs de Filebeat a través del protocolo Lumberjack. También proporcionamos VRL para mapear los eventos ECS entrantes a la especificación de OTel, antes de enviarlos al ClickStack OpenTelemetry collector mediante OTLP. Los usuarios que consumen eventos desde Kafka pueden sustituir el origen Logstash de Vector por el origen Kafka; todos los demás pasos siguen siendo los mismos.

Instalar Vector

Instale Vector mediante la guía oficial de instalación.

Puede instalarse en la misma instancia que su OTel collector de Elastic Stack.

Puede seguir las buenas prácticas en materia de arquitectura y seguridad al llevar Vector a producción.

Configurar vector

Vector debe configurarse para recibir eventos a través del protocolo Lumberjack, imitando una instancia de Logstash. Esto se puede lograr configurando un source logstash para 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

Los eventos se recibirán en formato ECS. Estos pueden convertirse al esquema de OpenTelemetry mediante un transformador Vector Remap Language (VRL). La configuración de este transformador es sencilla: el script se almacena en un archivo independiente:

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

Tenga en cuenta que recibe eventos de la fuente beats indicada anteriormente. A continuación se muestra nuestro script de reasignación. Este script se ha probado únicamente con eventos de log, pero puede servir como base para otros formatos.

VRL - de ECS a 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
                        }
                    ]
                }
            ]
        }
    ]
}

Por último, los eventos transformados pueden enviarse a ClickStack a través del OpenTelemetry Collector mediante OTLP. Para ello, es necesario configurar un sink OTLP en Vector, que toma los eventos de la transformación remap_filebeat como entrada:

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}

La YOUR_INGESTION_API_KEY es generada por ClickStack. Puede encontrar la clave en la UI de ClickStack (HyperDX) en Team Settings → API Keys.

A continuación se muestra la configuración completa final:

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

Configurar Filebeat

Las instalaciones existentes de Filebeat solo deben modificarse para enviar sus eventos a Vector. Para ello, es necesario configurar una salida de Logstash; de nuevo, TLS puede configurarse de forma opcional:

# ------------------------------ 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 consolida los distintos Elastic Beats en un único paquete. Este agente se integra con Elastic Fleet, lo que permite orquestarlo y configurarlo de forma centralizada.

Los usuarios que tienen Elastic Agents desplegados disponen de varias opciones de migración:

• Configure el agente para enviar datos a un endpoint de Vector mediante el protocolo Lumberjack. Por el momento, esto solo se ha probado con usuarios que recopilan únicamente datos de logs con Elastic Agent. Esto puede configurarse de forma centralizada desde la UI de Fleet en Kibana.
• Ejecute el agente como Elastic OpenTelemetry Collector (EDOT). Elastic Agent incluye un EDOT Collector integrado que le permite instrumentar sus aplicaciones e infraestructura una sola vez y enviar datos a varios proveedores y backends. En esta configuración, basta con configurar el OTel collector de EDOT para reenviar eventos al OTel collector de ClickStack mediante OTLP. Este enfoque admite todos los tipos de eventos.

A continuación, mostramos ambas opciones.

Instalar y configurar Vector

Instala y configura Vector siguiendo los mismos pasos documentados para la migración desde Filebeat.

Configurar Elastic Agent

Elastic Agent debe configurarse para enviar datos a través del protocolo Lumberjack de Logstash. Este es un patrón de implementación compatible y puede configurarse de forma centralizada o mediante el archivo de configuración del agente elastic-agent.yaml si se implementa sin Fleet.

La configuración centralizada a través de Kibana puede hacerse añadiendo una salida en Fleet.

Esta salida puede usarse después en una política de agente. Esto implica automáticamente que cualquier agente que use esa política enviará sus datos a Vector.

Dado que esto requiere configurar comunicación segura mediante TLS, recomendamos la guía "Configure SSL/TLS for the Logstash output", que puede seguirse suponiendo que la instancia de Vector del usuario asume el rol de Logstash.

Ten en cuenta que esto también requiere que los usuarios configuren el origen Logstash en Vector con TLS mutuo. Usa las claves y los certificados generados en la guía para configurar correctamente la entrada.

sources:
  beats:
    type: logstash
    address: 0.0.0.0:5044
    tls:
      enabled: true  # Establécelo en true si estás usando TLS. 
      # Los archivos siguientes se generan a partir de los pasos en 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 incluye un collector EDOT integrado que le permite instrumentar sus aplicaciones e infraestructura una sola vez y enviar datos a varios proveedores y backends.

Para ejecutar Elastic Agent con el collector EDOT, consulte la guía oficial de Elastic. En lugar de configurar el endpoint de Elastic, como se indica en la guía, elimine los exporters existentes y configure la salida OTLP para enviar datos al ClickStack OpenTelemetry collector. Por ejemplo, la configuración de los exportadores quedaría así:

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

ClickStack genera YOUR_INGESTION_API_KEY. Puede encontrar la clave en la UI de ClickStack, en Team Settings → API Keys.

Si Vector se ha configurado para usar TLS mutuo, con el certificado y las claves generados siguiendo los pasos de la guía "Configurar SSL/TLS para la salida de Logstash", el exportador otlp deberá configurarse en consecuencia; por ejemplo:

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

Los usuarios que ya ejecutan el Elastic OpenTelemetry Collector (EDOT) pueden reconfigurar fácilmente sus agentes para enviar datos al ClickStack OpenTelemetry collector a través de OTLP. Los pasos necesarios son idénticos a los descritos anteriormente para ejecutar el Elastic Agent como collector de OpenTelemetry. Este enfoque puede utilizarse con todos los tipos de datos.