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.
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.
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 agent 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 agent.
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.
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.
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 TLSSe 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:
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 raizignored_keys = ["@metadata"]# Definir prefixos de chaves de recursoresource_keys = ["host", "cloud", "agent", "service"]# Criar objetos separados para campos de recurso e de registro de logresource_obj = {}log_record_obj = {}# Copiar todas as chaves raiz não ignoradas para os objetos apropriadosroot_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 separadamenteflattened_resources = flatten(resource_obj, separator: ".")flattened_logs = flatten(log_record_obj, separator: ".")# Processar 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) } }}# Processar 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) } }}# 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/corpobody_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: 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 a porta 4317 uri: http://localhost:4318/v1/logs method: post encoding: codec: json framing: method: newline_delimited headers: content-type: application/json
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"
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.
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 AgentOs 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 ClickStackPor 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
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.
