Migração de 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.

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.

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.

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.

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.

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

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

# 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 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] # 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}

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

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

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.

Instalar e configurar o Vector

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

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

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

Para executar o Elastic Agent com o EDOT Collector, 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:
  # Exporter to send logs and metrics to Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: true

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

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.