L’Elastic Agent est un agent unifié capable de collecter des logs, des métriques et des traces. Cet agent peut être géré de façon centralisée via Elastic Fleet Server et prend en charge l’envoi vers Elasticsearch, Logstash, Kafka ou Redis.
Elastic propose également une distribution de l’OpenTelemetry Collector - EDOT. Bien qu’elle ne puisse pas encore être orchestrée par Fleet Server, elle offre une voie plus souple et plus ouverte si vous migrez vers ClickStack.
Le meilleur parcours de migration dépend des agents actuellement utilisés. Dans les sections qui suivent, nous présentons les options de migration pour chaque grand type d’agent. Notre objectif est de limiter au maximum les frictions et, lorsque c’est possible, de vous permettre de continuer à utiliser vos agents existants pendant la transition.
Dans la mesure du possible, nous recommandons de migrer vers l’OpenTelemetry (OTel) Collector pour toute la collecte des logs, métriques et traces, en déployant le collecteur en périphérie dans un rôle d’agent. C’est le moyen le plus efficace d’envoyer des données, tout en évitant la complexité architecturale et les transformations de données.
Pourquoi OpenTelemetry Collector ?L’OpenTelemetry Collector offre une solution durable et indépendante des fournisseurs pour l’ingestion des données d’observabilité. Nous savons que certaines organisations exploitent des flottes de milliers, voire de dizaines de milliers, d’agents Elastic. Pour ces utilisateurs, il peut être essentiel de préserver la compatibilité avec l’infrastructure d’agents existante. Cette documentation est conçue pour répondre à ce besoin, tout en aidant les équipes à passer progressivement à une collecte basée sur OpenTelemetry.
Toutes les données sont ingérées dans ClickStack via une instance de collecteur OpenTelemetry (OTel), qui sert de point d’entrée principal pour les logs, les métriques, les traces et les données de session. Nous recommandons d’utiliser pour cette instance la distribution ClickStack officielle du collecteur, si elle n’est pas déjà incluse dans votre déploiement ClickStack.Les utilisateurs envoient les données à ce collecteur depuis des language SDKs ou via des agents de collecte qui récupèrent les métriques d’infrastructure et les logs (comme des OTel collecteurs jouant un rôle d’agent, ou d’autres technologies, par ex. Fluentd ou Vector). Pour les équipes qui souhaitent un pipeline OpenTelemetry géré, Bindplane propose une solution native OpenTelemetry avec une destination ClickStack native, ce qui simplifie la collecte, le traitement et le routage de la télémétrie.Nous partons du principe que ce collecteur est disponible pour toutes les étapes de migration des agents.
Les utilisateurs disposant de déploiements Beats importants peuvent souhaiter les conserver lors de leur migration vers ClickStack.À ce jour, cette option n’a été testée qu’avec Filebeat et ne convient donc qu’aux logs.Les agents Beats utilisent le Elastic Common Schema (ECS), actuellement en cours d’intégration dans la spécification OpenTelemetry utilisée par ClickStack. Cependant, ces schémas diffèrent encore de manière significative, et les utilisateurs doivent pour l’instant transformer les événements au format ECS en format OpenTelemetry avant leur ingestion dans ClickStack.Nous recommandons d’effectuer cette transformation à l’aide de Vector, un pipeline de données d’observabilité léger et très performant, qui prend en charge un puissant langage de transformation appelé Vector Remap Language (VRL).Si vos agents Filebeat sont configurés pour envoyer des données à Kafka — une sortie prise en charge par Beats — Vector peut consommer ces événements depuis Kafka, appliquer des transformations de schéma avec VRL, puis les transmettre via OTLP à l’OpenTelemetry Collector distribué avec ClickStack.Vector prend également en charge la réception d’événements via le protocole Lumberjack utilisé par Logstash. Les agents Beats peuvent ainsi envoyer directement les données à Vector, où le même processus de transformation peut être appliqué avant leur transfert vers le ClickStack OpenTelemetry collecteur via OTLP.Nous illustrons ces deux architectures ci-dessous.Dans l’exemple suivant, nous présentons les premières étapes de configuration de Vector pour recevoir des événements de logs depuis Filebeat via le protocole Lumberjack. Nous fournissons du VRL pour faire correspondre les événements ECS entrants à la spécification OTel, avant de les envoyer au ClickStack OpenTelemetry collecteur via OTLP. Les utilisateurs qui consomment des événements depuis Kafka peuvent remplacer la source Logstash de Vector par la source Kafka — toutes les autres étapes restent identiques.
Installez Vector à l’aide du guide d’installation officiel.Vous pouvez l’installer sur la même instance que votre OTel collector Elastic Stack.Vous pouvez suivre les bonnes pratiques en matière d’architecture et de sécurité lors du passage de Vector en production.
Vector doit être configuré pour recevoir des événements via le protocole Lumberjack, en imitant une instance Logstash. Pour ce faire, configurez une source logstash pour 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
Configuration TLSSi le TLS mutuel est requis, générez des certificats et des clés à l’aide du guide Elastic “Configurer SSL/TLS pour la sortie Logstash”. Vous pouvez ensuite les indiquer dans la configuration, comme illustré ci-dessus.
Les événements seront reçus au format ECS. Ils peuvent être convertis vers le schéma OpenTelemetry à l’aide d’un transformateur Vector Remap Language (VRL). La configuration de ce transformateur est simple — le script étant conservé dans un fichier séparé :
Notez qu’il reçoit des événements de la source beats ci-dessus. Notre script de remappage est présenté ci-dessous. Ce script a été testé uniquement avec des événements de logs, mais peut servir de base pour d’autres formats.
VRL - d’ECS vers OTel
# Define keys to ignore at root levelignored_keys = ["@metadata"]# Define resource key prefixesresource_keys = ["host", "cloud", "agent", "service"]# Create separate objects for resource and log record fieldsresource_obj = {}log_record_obj = {}# Copy all non-ignored root keys to appropriate objectsroot_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 separatelyflattened_resources = flatten(resource_obj, separator: ".")flattened_logs = flatten(log_record_obj, separator: ".")# Process resource attributesresource_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 attributeslog_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 fieldbody_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 } ] } ] } ]}
Enfin, les événements transformés peuvent être envoyés à ClickStack via l’OpenTelemetry Collector en utilisant OTLP. Pour cela, il est nécessaire de configurer un sink OTLP dans Vector, qui prend en entrée les événements issus de la transformation remap_filebeat :
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 est générée par ClickStack. Vous pouvez retrouver la clé dans l’interface ClickStack (HyperDX) sous Team Settings → API Keys.La configuration complète finale est présentée ci-dessous :
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: truetransforms: 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
Il suffit de modifier les installations Filebeat existantes pour qu’elles envoient leurs événements à Vector. Cela nécessite de configurer une sortie Logstash — là encore, TLS peut aussi être configuré de façon facultative :
# ------------------------------ 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 regroupe les différents Elastic Beats dans un seul paquet. Cet agent s’intègre à Elastic Fleet, ce qui permet de l’orchestrer et de le configurer de façon centralisée.Les utilisateurs ayant déployé des Elastic Agents disposent de plusieurs options de migration :
Configurez l’agent pour envoyer les données vers un endpoint Vector via le protocole Lumberjack. À ce jour, cette option n’a été testée que pour les utilisateurs qui collectent uniquement des logs avec Elastic Agent. Cela peut être configuré de manière centralisée via l’interface Fleet dans Kibana.
Exécutez l’agent comme Elastic OpenTelemetry Collector (EDOT). Elastic Agent inclut un collecteur EDOT intégré qui vous permet d’instrumenter vos applications et votre infrastructure une seule fois, puis d’envoyer les données à plusieurs fournisseurs et backends. Dans cette configuration, vous pouvez simplement configurer le collecteur EDOT pour transférer les événements vers le ClickStack OTel collecteur via OTLP. Cette approche prend en charge tous les types d’événements.
Elastic Agent doit être configuré pour envoyer les données via le protocole Lumberjack de Logstash. Il s’agit d’un modèle de déploiement pris en charge, qui peut être configuré de manière centralisée ou via le fichier de configuration de l’agent elastic-agent.yaml si vous effectuez le déploiement sans Fleet.La configuration centralisée via Kibana peut se faire en ajoutant un Output à Fleet.Cet output peut ensuite être utilisé dans une stratégie d’agent. Ainsi, tous les agents qui utilisent cette stratégie enverront automatiquement leurs données à Vector.Comme cela nécessite de configurer une communication sécurisée via TLS, nous recommandons le guide “Configurer SSL/TLS pour la sortie Logstash”, que vous pouvez suivre en considérant que votre instance Vector joue le rôle de Logstash.Notez que cela impose également de configurer la source Logstash dans Vector avec le TLS mutuel. Utilisez les clés et certificats générés dans le guide pour configurer correctement l’entrée.
sources: beats: type: logstash address: 0.0.0.0:5044 tls: enabled: true # Définissez sur true si vous utilisez TLS. # Les fichiers ci-dessous sont générés à partir des étapes sur 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
Exécuter Elastic Agent comme collecteur OpenTelemetry
Elastic Agent inclut un EDOT Collector intégré qui vous permet d’instrumenter vos applications et votre infrastructure une seule fois, puis d’envoyer les données à plusieurs fournisseurs et backends.
Intégrations et orchestration de l’agentLes utilisateurs qui exécutent le collecteur EDOT distribué avec Elastic Agent ne pourront pas tirer parti des intégrations existantes proposées par l’agent. De plus, le collecteur ne peut pas être géré de manière centralisée par Fleet, ce qui oblige l’utilisateur à exécuter l’agent en mode standalone et à gérer lui-même la configuration.
Pour exécuter Elastic Agent avec le collecteur EDOT, consultez le guide officiel d’Elastic. Au lieu de configurer l’endpoint Elastic, comme indiqué dans le guide, supprimez les exporters existants et configurez la sortie OTLP pour envoyer les données au ClickStack OpenTelemetry collecteur. Par exemple, la configuration des exporters devient :
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
Managed ClickStackPar défaut, une clé d’ingestion API n’est pas requise si vous exécutez un OpenTelemetry Collector en mode standalone pour Managed ClickStack. L’ingestion peut toutefois être sécurisée en spécifiant un jeton d’authentification OTLP. Voir “Sécuriser le collecteur”.
La clé YOUR_INGESTION_API_KEY indiquée ici est générée par ClickStack. Vous pouvez la trouver dans la ClickStack UI, sous Team Settings → API Keys.Si Vector a été configuré pour utiliser le TLS mutuel, avec le certificat et les clés générés en suivant les étapes du guide “Configurer SSL/TLS pour la sortie Logstash”, l’exporter otlp devra être configuré en conséquence, par exemple.
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
Les utilisateurs qui exécutent déjà l’Elastic OpenTelemetry Collector (EDOT) peuvent simplement reconfigurer leurs agents pour envoyer leurs données au ClickStack OpenTelemetry collecteur via OTLP. Les étapes à suivre sont identiques à celles décrites ci-dessus pour exécuter l’Elastic Agent comme collecteur OpenTelemetry. Cette approche peut être utilisée pour tous les types de données.
