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.
¿Por qué OpenTelemetry Collector?OpenTelemetry Collector proporciona una solución sostenible e independiente del proveedor para la ingestión de datos de observabilidad. Entendemos que algunas organizaciones operan flotas de miles, o incluso decenas de miles, de agentes de Elastic. Para estos usuarios, mantener la compatibilidad con la infraestructura de agentes existente puede ser fundamental. Esta documentación está pensada para dar soporte a ese escenario, al tiempo que ayuda a los equipos a pasar gradualmente a una recopilación basada en OpenTelemetry.
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 agent 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.
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.
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 # Establezca en true si está usando TLS # Los archivos a continuación se generan siguiendo 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
Configuración de TLSSi se requiere TLS mutuo, genere certificados y claves privadas siguiendo la guía de Elastic “Configurar SSL/TLS para la salida de Logstash”. Luego, puede especificarlos en la configuración, como se muestra arriba.
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:
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
# Definir claves a ignorar en el nivel raízignored_keys = ["@metadata"]# Definir prefijos de claves de recursoresource_keys = ["host", "cloud", "agent", "service"]# Crear objetos separados para los campos de recurso y de registro de logresource_obj = {}log_record_obj = {}# Copiar todas las claves raíz no ignoradas a los objetos correspondientesroot_keys = keys(.)for_each(root_keys) -> |_index, key| { if !includes(ignored_keys, key) { val, err = get(., [key]) if err == null { # Verificar si este es un campo de recurso is_resource = false if includes(resource_keys, key) { is_resource = true } # Agregar al objeto correspondiente 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 } } }}# Aplanar ambos objetos por separadoflattened_resources = flatten(resource_obj, separator: ".")flattened_logs = flatten(log_record_obj, separator: ".")# Procesar atributos de recursoresource_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) } }}# Procesar atributos de registro de loglog_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) } }}# Obtener timestamp para timeUnixNano (convertir a nanosegundos)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")}# Obtener el campo message/bodybody_value = if exists(.message) { to_string!(.message)} else if exists(.body) { to_string!(.body)} else { ""}# Crear la estructura de 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 } ] } ] } ]}
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] # recibe eventos de una transformación remap - ver más abajo protocol: type: http # Usa "grpc" para el puerto 4317 uri: http://localhost:4318/v1/logs # endpoint de logs para el 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 # Establezca en true si está usando 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: truetransforms: remap_filebeat: inputs: ["beats"] type: "remap" file: 'beat_to_otel.vrl'sinks: otlp: type: opentelemetry inputs: [remap_filebeat] protocol: type: http # Use "grpc" para el puerto 4317 uri: http://localhost:4318/v1/logs method: post encoding: codec: json framing: method: newline_delimited headers: content-type: application/json
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:
# ------------------------------ Salida de Logstash -------------------------------output.logstash: # Los hosts de Logstash hosts: ["localhost:5044"] # SSL opcional. Desactivado por defecto. # Lista de certificados raíz para verificaciones del servidor HTTPS #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] # Certificado para la autenticación de cliente SSL #ssl.certificate: "/etc/pki/client/cert.pem" # Clave del certificado de cliente #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.
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 TLS mutuo en el origen Logstash de Vector. 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
Ejecutar Elastic Agent como OpenTelemetry collector
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.
Integraciones y orquestación del agenteLos usuarios que ejecuten el collector EDOT distribuido con Elastic Agent no podrán aprovechar las integraciones existentes que ofrece el agente. Además, Fleet no puede gestionar el collector de forma centralizada, lo que obliga al usuario a ejecutar el agente en modo standalone y a administrar la configuración por su cuenta.
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: # Exportador para enviar logs y métricas a Elasticsearch Managed OTLP Input otlp: endpoint: localhost:4317 headers: authorization: ${YOUR_INGESTION_API_KEY} tls: insecure: true
Managed ClickStackDe forma predeterminada, no se requiere una clave de API para ingestión si se ejecuta un OpenTelemetry collector en modo standalone para Managed ClickStack. No obstante, la ingestión puede protegerse especificando un token de autenticación OTLP. Consulte “Cómo proteger el collector”.
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: # Exportador para enviar logs y métricas a 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
Migración desde el collector de OpenTelemetry de Elastic
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.
