Migração de agentes do Elastic

Migração de agentes do Elastic

​

Migrando agentes do Elastic

O Elastic Stack oferece vários agentes para coleta de dados de observabilidade. Especificamente:

• A família Beats — como Filebeat, Metricbeat e Packetbeat — todos baseados na biblioteca libbeat. Esses Beats oferecem suporte ao envio de dados para Elasticsearch, Kafka, Redis ou Logstash por meio do protocolo Lumberjack.
• O Elastic Agent fornece um agente unificado capaz de coletar logs, métricas e traces. Esse agente pode ser gerenciado centralmente pelo Elastic Fleet Server e oferece suporte ao envio para Elasticsearch, Logstash, Kafka ou Redis.
• A Elastic também fornece uma distribuição do OpenTelemetry Collector - EDOT. Embora atualmente ele não possa ser orquestrado pelo Fleet Server, oferece um caminho mais flexível e aberto se você estiver migrando para o ClickStack.

O melhor caminho de migração depende dos agentes atualmente em uso. Nas seções a seguir, documentamos as opções de migração para cada tipo principal de agente. Nosso objetivo é reduzir o atrito e, sempre que possível, permitir que você continue usando seus agentes atuais durante a transição.

​

Caminho de migração preferencial

Sempre que possível, recomendamos migrar para o OpenTelemetry (OTel) Collector para toda a coleta de logs, métricas e traces, implantando o collector na borda, no papel de agente. Essa é a forma mais eficiente de enviar dados e evita complexidade arquitetônica e transformações de dados.

Por que OpenTelemetry Collector?

O OpenTelemetry Collector oferece uma solução sustentável e independente de fornecedor para a ingestão de dados de observabilidade. Reconhecemos que algumas organizações operam frotas de milhares — ou até dezenas de milhares — de agentes da Elastic. Para esses usuários, manter a compatibilidade com a infraestrutura de agentes existente pode ser fundamental. Esta documentação foi elaborada para dar suporte a isso, ao mesmo tempo que ajuda as equipes a fazer uma transição gradual para uma coleta baseada em OpenTelemetry.

​

Endpoint OpenTelemetry do ClickHouse

Todos os dados são ingeridos no ClickStack por meio de uma instância do OTel collector (OpenTelemetry), que atua como o principal ponto de entrada para logs, métricas, traces e dados de sessão. Recomendamos usar a distribuição oficial do ClickStack do collector para essa instância, caso ela ainda não esteja incluída no seu modelo de implantação do ClickStack.

Os usuários enviam dados para esse collector a partir de SDKs de linguagem ou por meio de agentes de coleta de dados que coletam métricas e logs de infraestrutura (como OTel collectors na função de agente ou outras tecnologias, como Fluentd ou Vector). Para equipes que desejam um pipeline gerenciado do OpenTelemetry, Bindplane oferece uma solução nativa de OpenTelemetry com um destino nativo do ClickStack, simplificando a coleta, o processamento e o roteamento de telemetria.

Assumimos que esse collector esteja disponível para todas as etapas de migração do agente.

​

Migração de beats

Usuários com implantações extensas de Beat talvez queiram mantê-las ao migrar para o ClickStack.

No momento, esta opção foi testada apenas com o Filebeat e, portanto, é adequada somente para logs.

Os agentes Beats usam o Elastic Common Schema (ECS), que atualmente está em processo de incorporação à especificação OpenTelemetry usada pelo ClickStack. No entanto, esses esquemas ainda diferem significativamente, e, no momento, os usuários são responsáveis por transformar eventos formatados em ECS para o formato OpenTelemetry antes da ingestão no ClickStack.

Recomendamos realizar essa transformação usando o Vector, um pipeline de dados de observabilidade leve e de alto desempenho que oferece suporte a uma poderosa linguagem de transformação chamada Vector Remap Language (VRL).

Se os seus agentes Filebeat estiverem configurados para enviar dados ao Kafka — uma saída compatível do Beats — o Vector poderá consumir esses eventos do Kafka, aplicar transformações de esquema usando VRL e, em seguida, encaminhá-los via OTLP para o OpenTelemetry Collector distribuído com o ClickStack.

Como alternativa, o Vector também oferece suporte ao recebimento de eventos pelo protocolo Lumberjack usado pelo Logstash. Isso permite que os agentes Beats enviem dados diretamente ao Vector, onde o mesmo processo de transformação pode ser aplicado antes do encaminhamento para o ClickStack OpenTelemetry Collector via OTLP.

Ilustramos as duas arquiteturas abaixo.

No exemplo a seguir, apresentamos as etapas iniciais para configurar o Vector para receber eventos de log do Filebeat por meio do protocolo Lumberjack. Fornecemos o VRL para mapear os eventos ECS de entrada para a especificação OTel, antes de enviá-los ao ClickStack OpenTelemetry Collector via OTLP. Usuários que consomem eventos do Kafka podem substituir a origem Logstash do Vector pela origem Kafka — todas as outras etapas permanecem as mesmas.

1. ​

   Instalar o Vector

   Instale o Vector usando o guia oficial de instalação.

   O Vector pode ser instalado na mesma instância do OTel collector do Elastic Stack.

   Você pode seguir as melhores práticas de arquitetura e segurança ao colocar o Vector em produção.

2. ​

   Configurar o vector

   O Vector deve ser configurado para receber eventos pelo protocolo Lumberjack, imitando uma instância do Logstash. Isso pode ser feito configurando uma source logstash para o Vector:

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Defina como true se estiver usando TLS
         # Os arquivos abaixo são gerados a partir das etapas em 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
   

   Configuração de TLS

   Se o TLS mútuo for necessário, gere os certificados e as chaves usando o guia da Elastic “Configurar SSL/TLS para a saída do Logstash”. Em seguida, eles podem ser especificados na configuração, como mostrado acima.

   Os eventos serão recebidos no formato ECS. Eles podem ser convertidos para o esquema do OpenTelemetry usando um transformador Vector Remap Language (VRL). A configuração desse transformador é simples — com o arquivo de script mantido em um arquivo separado:

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

   Observe que ele recebe eventos da fonte beats mencionada acima. Nosso script de remapeamento é apresentado abaixo. Este script foi testado apenas com eventos de log, mas pode servir de base para outros formatos.

   VRL - ECS para OTel

   # Definir chaves a ignorar no nível raiz
   ignored_keys = ["@metadata"]
   
   # Definir prefixos de chaves de recurso
   resource_keys = ["host", "cloud", "agent", "service"]
   
   # Criar objetos separados para campos de recurso e de registro de log
   resource_obj = {}
   log_record_obj = {}
   
   # Copiar todas as chaves raiz não ignoradas para os objetos apropriados
   root_keys = keys(.)
   for_each(root_keys) -> |_index, key| {
       if !includes(ignored_keys, key) {
           val, err = get(., [key])
           if err == null {
               # Verificar se este é um campo de recurso
               is_resource = false
               if includes(resource_keys, key) {
                   is_resource = true
               }
   
               # Adicionar ao objeto apropriado
               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
               }
           }
       }
   }
   
   # Nivelar ambos os objetos separadamente
   flattened_resources = flatten(resource_obj, separator: ".")
   flattened_logs = flatten(log_record_obj, separator: ".")
   
   # Processar atributos de recurso
   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)
           }
       }
   }
   
   # Processar atributos de registro de log
   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)
           }
       }
   }
   
   # Obter timestamp para timeUnixNano (converter para nanossegundos)
   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")
   }
   
   # Obter campo de mensagem/corpo
   body_value = if exists(.message) {
       to_string!(.message)
   } else if exists(.body) {
       to_string!(.body)
   } else {
       ""
   }
   
   # Criar a estrutura 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 fim, os eventos transformados podem ser enviados ao ClickStack via OpenTelemetry Collector usando OTLP. Para isso, é necessário configurar um sink OTLP no Vector, que recebe os eventos da transformação remap_filebeat como entrada:

   sinks:
     otlp:
       type: opentelemetry
       inputs: [remap_filebeat] # recebe eventos de uma transformação remap - veja abaixo
       protocol:
         type: http  # Use "grpc" para a porta 4317
         uri: http://localhost:4318/v1/logs # endpoint de logs para o OTel collector 
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
           authorization: ${YOUR_INGESTION_API_KEY}
   

   A YOUR_INGESTION_API_KEY aqui é gerada pelo ClickStack. Você pode encontrar a chave na UI do ClickStack (HyperDX) em Team Settings → API Keys.

   Nossa configuração completa final está exibida abaixo:

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Defina como true se estiver 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: 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" para a porta 4317
         uri: http://localhost:4318/v1/logs
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
   
3. ​

   Configurar o Filebeat

   As instalações existentes do Filebeat só precisam ser modificadas para enviar os eventos ao Vector. Para isso, é necessário configurar uma saída do Logstash — novamente, o TLS pode ser configurado opcionalmente:

   # ------------------------------ Saída do Logstash -------------------------------
   output.logstash:
     # Os hosts do Logstash
     hosts: ["localhost:5044"]
   
     # SSL opcional. Por padrão está desativado.
     # Lista de certificados raiz para verificações do servidor HTTPS
     #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
   
     # Certificado para autenticação de cliente SSL
     #ssl.certificate: "/etc/pki/client/cert.pem"
   
     # Chave do certificado do cliente
     #ssl.key: "/etc/pki/client/cert.key"
   

​

Migrando do Elastic Agent

O Elastic Agent consolida os diferentes Elastic Beats em um único pacote. Esse agente se integra ao Elastic Fleet, permitindo que seja orquestrado e configurado de forma centralizada.

Os usuários com Elastic Agents implantados têm vários caminhos de migração:

• Configure o agente para enviar para um endpoint do Vector pelo protocolo Lumberjack. No momento, isso foi testado apenas para usuários que coletam dados de log com o Elastic Agent. Isso pode ser configurado de forma centralizada pela UI do Fleet no Kibana.
• Execute o agente como Elastic OpenTelemetry Collector (EDOT). O Elastic Agent inclui um EDOT Collector incorporado que permite instrumentar seus aplicativos e sua infraestrutura uma única vez e enviar dados para vários fornecedores e backends. Nessa configuração, você pode simplesmente configurar o EDOT collector para encaminhar eventos ao OTel collector do ClickStack via OTLP. Essa abordagem oferece suporte a todos os tipos de evento.

Demonstramos essas duas opções abaixo.

​

Envio de dados via Vector

1. ​

   Instalar e configurar o Vector

   Instale e configure o Vector usando os mesmos passos documentados para a migração do Filebeat.

2. ​

   Configurar o Elastic Agent

   O Elastic Agent precisa ser configurado para enviar dados pelo protocolo Lumberjack do Logstash. Esse é um padrão de implantação compatível e pode ser configurado centralmente ou pelo arquivo de configuração do agente elastic-agent.yaml, se a implantação for feita sem o Fleet.

   A configuração central via Kibana pode ser feita adicionando um Output ao Fleet.

   Essa saída pode então ser usada em uma política de agente. Com isso, todos os agents que usarem essa política enviarão automaticamente seus dados para o Vector.

   Como isso exige a configuração de comunicação segura via TLS, recomendamos o guia “Configure SSL/TLS for the Logstash output”, que pode ser seguido considerando que a instância do Vector assume o papel do Logstash.

   Observe que isso também exige que os usuários configurem a source Logstash no Vector com TLS mútuo. Use as chaves e os certificados gerados no guia para configurar a entrada adequadamente.

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: true  # Defina como true se estiver usando TLS. 
         # Os arquivos abaixo são gerados a partir das etapas em 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
   

​

Execute o Elastic Agent como OpenTelemetry Collector

O Elastic Agent inclui um coletor EDOT integrado que permite instrumentar seus aplicativos e sua infraestrutura uma única vez e enviar dados para vários fornecedores e backends.

Integrações e orquestração do Agent

Os usuários que executam o coletor EDOT distribuído com o Elastic Agent não poderão aproveitar as integrações existentes oferecidas pelo Agent. Além disso, o coletor não pode ser gerenciado centralmente pelo Fleet, o que obriga o usuário a executar o Agent no modo standalone e gerenciar a configuração por conta própria.

Para executar o Elastic Agent com o coletor EDOT, consulte o guia oficial da Elastic. Em vez de configurar o endpoint da Elastic, como indicado no guia, remova os exporters existentes e configure a saída OTLP para enviar dados ao ClickStack OpenTelemetry Collector. Por exemplo, a configuração dos exporters passa a ser:

exporters:
  # Exportador para enviar logs e métricas para o Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: true

Managed ClickStack

Por padrão, não é necessário uma chave de API de ingestão ao executar um OpenTelemetry Collector em modo standalone para o Managed ClickStack. No entanto, é possível proteger a ingestão especificando um token de autenticação OTLP. Consulte “Protegendo o collector”.

A YOUR_INGESTION_API_KEY aqui é gerada pelo ClickStack. Você pode encontrar essa chave na UI do ClickStack em Team Settings → API Keys.

Se o Vector tiver sido configurado para usar TLS mútuo, com o certificado e as chaves gerados seguindo as etapas do guia “Configurar SSL/TLS para a saída do Logstash”, o exportador otlp precisará ser configurado adequadamente, por exemplo.

exporters:
  # Exportador para enviar logs e métricas para o 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

​

Migração do Elastic OpenTelemetry Collector

Os usuários que já executam o Elastic OpenTelemetry Collector (EDOT) podem simplesmente reconfigurar seus agents para enviar ao ClickStack OpenTelemetry Collector via OTLP. As etapas envolvidas são idênticas às descritas acima para executar o Elastic Agent como um OpenTelemetry Collector. Essa abordagem pode ser usada para todos os tipos de dados.