Skip to main content

Migrating agents from Elastic

The Elastic Stack provides a number of Observability data collection agents. Specifically: The best migration path depends on the agents currently in use. In the sections that follow, we document migration options for each major agent type. Our goal is to minimize friction and, where possible, allow you to continue using your existing agents during the transition.

Preferred migration path

Where possible we recommend migrating to the OpenTelemetry (OTel) Collector for all log, metric, and trace collection, deploying the collector at the edge in an agent role. This represents the most efficient means of sending data and avoids architectural complexity and data transformation.
Why OpenTelemetry Collector?The OpenTelemetry Collector provides a sustainable and vendor-neutral solution for observability data ingestion. We recognize that some organizations operate fleets of thousands—or even tens of thousands—of Elastic agents. For these users, maintaining compatibility with existing agent infrastructure may be critical. This documentation is designed to support this, while also helping teams gradually transition to OpenTelemetry-based collection.

ClickHouse OpenTelemetry endpoint

Configure the destination before following the agent migration steps. The Vector and EDOT examples below send OpenTelemetry data over OTLP HTTP.
Copy your OTLP HTTP endpoint and API key from Team Settings → Data → Managed Telemetry. Set these variables in the environment where Vector or EDOT runs:
Use the exact endpoint, including its port, without a /v1/logs suffix. See Sending OpenTelemetry data for connection details.

Migrating from beats

Users with extensive Beat deployments may wish to retain these when migrating to ClickHouse Observability. Currently this option has only been tested with Filebeat, and is therefore appropriate for Logs only. Beats agents use the Elastic Common Schema (ECS), which is currently in the process of being merged into the OpenTelemetry specification used by ClickHouse Observability. However, these schemas still differ significantly, and users are currently responsible for transforming ECS-formatted events into OpenTelemetry format before ingestion into ClickHouse Observability. We recommend performing this transformation using Vector, a lightweight and high-performance observability data pipeline that supports a powerful transformation language called Vector Remap Language (VRL). If your Filebeat agents are configured to send data to Kafka - a supported output by Beats - Vector can consume those events from Kafka, apply schema transformations using VRL, and then forward them via OTLP to your configured OTLP endpoint. Alternatively, Vector also supports receiving events over the Lumberjack protocol used by Logstash. This enables Beats agents to send data directly to Vector, where the same transformation process can be applied before forwarding to your configured OTLP endpoint via OTLP. We illustrate both of these architectures below. In the following example, we provide the initial steps to configure Vector to receive log events from Filebeat via the Lumberjack protocol. We provide VRL for mapping the inbound ECS events to OTel specification, before sending these to your configured OTLP endpoint via OTLP. Users consuming events from Kafka can replace the Vector Logstash source with the Kafka source - all other steps remain the same.
1

Install vector

Install Vector using the official installation guide.Install Vector on a host reachable by your Filebeat agents.You can follow best practices with regards to architecture and security when moving Vector to production.
2

Configure vector

Vector should be configured to receive events over the Lumberjack protocol, imitating a Logstash instance. This can be achieved by configuring a logstash source for Vector:
TLS configurationIf Mutual TLS is required, generate certificates and keys using the Elastic guide “Configure SSL/TLS for the Logstash output”. These can then be specified in the configuration as shown above.
Events will be received in ECS format. These can be converted to the OpenTelemetry schema using a Vector Remap Language (VRL) transformer. Configuration of this transformer is simple - with the script file held in a separate file:
Note it receives events from the above beats source. Our remap script is shown below. This script has been tested with log events only but can form the basis for other formats.
Finally, send the transformed events to your configured OTLP endpoint. This requires the configuration of a OTLP sink in Vector, which takes events from the remap_filebeat transform as input:
Use the connection variables for your deployment. The Vector URI includes /v1/logs because this output sends log records.Our final complete configuration is shown below:
3

Configure Filebeat

Configure Filebeat to use the Logstash output for Vector, replacing any existing output configuration. Replace YOUR_VECTOR_HOST with the host running Vector; use localhost only when both run on the same host. Configure TLS to match the Vector input:

Migrating from Elastic Agent

The Elastic Agent consolidates the different Elastic Beats into a single package. This agent integrates with Elastic Fleet, allowing it to be centrally orchestrated and configured. Users with Elastic Agents deployed have several migration paths:
  • Configure the agent to send to a Vector endpoint over the Lumberjack protocol. This has currently been tested for users collecting log data with the Elastic Agent only. This can be centrally configured via the Fleet UI in Kibana.
  • Run the agent as Elastic OpenTelemetry Collector (EDOT). The Elastic Agent includes an embedded EDOT Collector that allows you to instrument your applications and infrastructure once and send data to multiple vendors and backends. In this configuration, you can simply configure the EDOT collector to forward events to your configured OTLP endpoint over OTLP. This approach supports all event types.
We demonstrate both of these options below.

Sending data via Vector

1

Install and configure Vector

Install and configure Vector using the same steps as those documented for migrating from Filebeat.
2

Configure Elastic Agent

Elastic Agent needs to be configured to send data via the Logstash protocol Lumberjack. This is a supported deployment pattern and can either be configured centrally or via the agent configuration file elastic-agent.yaml if deploying without Fleet.Central configuration through Kibana can be achieved by adding an Output to Fleet.This output can then be used in an agent policy. This will automatically mean any agents using the policy will send their data to Vector.Since this requires secure communication over TLS to be configured, we recommend the guide “Configure SSL/TLS for the Logstash output”, which can be followed with the user assuming their Vector instance assumes the role of Logstash.Note that this requires users to configure the Logstash source in Vector to also mutual TLS. Use the keys and certificates generated in the guide to configure the input appropriately.

Run Elastic Agent as OpenTelemetry collector

The Elastic Agent includes an embedded EDOT Collector that allows you to instrument your applications and infrastructure once and send data to multiple vendors and backends.
Agent integrations and orchestrationUsers running the EDOT collector distributed with Elastic Agent won’t be able to exploit the existing integrations offered by the agent. Additionally, the collector can’t be centrally managed by Fleet - forcing the user to run the agent in standalone mode, managing configuration themselves.
To run the Elastic Agent with the EDOT collector, follow the official Elastic guide. Configure an OTLP HTTP exporter using your connection variables:
Add otlphttp/clickhouse to the exporters list in each logs, metrics, or traces pipeline you want to forward. Preserve the existing receivers and processors. For parallel ingestion, retain the Elastic exporter in those pipelines; remove it when you are ready to stop sending to Elastic. The exporter uses the base endpoint and appends the signal path automatically. For an HTTPS receiver using a private certificate authority, configure tls.ca_file; if that receiver requires mutual TLS, also configure tls.cert_file and tls.key_file. These settings secure the EDOT-to-OTLP connection independently of the Filebeat-to-Vector TLS configuration.

Migrating from the Elastic OpenTelemetry collector

Users already running the Elastic OpenTelemetry Collector (EDOT) can simply reconfigure their agents to send to your configured OTLP endpoint via OTLP. The steps involved are identical to those outlined above for running the Elastic Agent as an OpenTelemetry collector. This approach can be used for all data types.