From f329dd22b7f1e0d1a2727d98f41a9ffef84ec605 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Thu, 19 Dec 2024 10:06:04 -0500 Subject: [PATCH] Add small doc about running a standalone agent in otel mode (#1572) (#1574) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add small doc about running a standalone agent in otel mode --------- Co-authored-by: David Kilfoyle (cherry picked from commit 99836e086f6a3cd84c04b84cd071420e66026c3e) # Conflicts: # docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc Co-authored-by: Paolo Chilà --- .../otel-agent-transform.asciidoc | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc diff --git a/docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc b/docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc new file mode 100644 index 000000000..fb1c90017 --- /dev/null +++ b/docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc @@ -0,0 +1,81 @@ +[[otel-agent-transform]] +== Transform an installed {agent} to run as an OTel Collector + +preview::[] + +If you have a currently installed standalone {agent}, it can be configured to run as an <>. This allows you to run {agent} both as a service and in an OTel Collector mode. + +In order to configure an installed standalone {agent} to run as an OTel Collector, it's enough to include a valid <> configuration in the `elastic-agent.yml` file, as shown in the following example. + +=== Example: configure {agent} to ingest host logs and metrics into Elasticsearch using the OTel Collector + +**Prerequisites** + +You'll need the following: + +. A suitable <> for authenticating on Elasticsearch +. An installed standalone {agent} +. A valid OTel Collector configuration. In this example we'll use the OTel sample configuration included in the {agent} repository: `otel_samples/platformlogs_hostmetrics.yml`. +** link:https://github.com/elastic/elastic-agent/blob/main/internal/pkg/otel/samples/linux/platformlogs_hostmetrics.yml[Linux version] +** link:https://github.com/elastic/elastic-agent/blob/main/internal/pkg/otel/samples/darwin/platformlogs_hostmetrics.yml[MacOS version] + +**Steps** + +To change a running standalone {agent} to run as an OTel Collector: + +. Create a directory where the OTel Collector can save its state. In this example we use `<{agent} install directory>/data/otelcol`. +. Open the `<{agent} install directory>/otel_samples/platformlogs_hostmetrics.yml` file for editing. +. Set environment details to be used by OTel Collector: +* **Option 1:** Define environment variables for the {agent} service: +** `ELASTIC_ENDPOINT`: The URL of the {es} instance where data will be sent +** `ELASTIC_API_KEY`: The API Key to use to authenticate with {es} +** `STORAGE_DIR`: The directory where the OTel Collector can persist its state +* **Option 2:** Replace the environment variable references in the sample configuration with the corresponding values: +** `${env:ELASTIC_ENDPOINT}`:The URL of the {es} instance where data will be sent +** `${env:ELASTIC_API_KEY}`: The API Key to use to authenticate with {es} +** `${env:STORAGE_DIR}`: The directory where the OTel Collector can persist its state +. Save the opened OTel configuration as `elastic-agent.yml`, overwriting the default configuration of the installed agent. +. Run the `elastic-agent status` command to verify that the new configuration has been correctly applied: ++ +[source,shell] +---- +elastic-agent status +---- +The OTel Collector running configuration should appear under `elastic-agent` key (note the `extensions` and `pipeline` keys): ++ +[source,shell] +---- +┌─ fleet +│ └─ status: (STOPPED) Not enrolled into Fleet +└─ elastic-agent + ├─ status: (HEALTHY) Running + ├─ extensions + │ ├─ status: StatusOK + │ └─ extension:file_storage + │ └─ status: StatusOK + ├─ pipeline:logs/platformlogs + │ ├─ status: StatusOK + │ ├─ exporter:elasticsearch/otel + │ │ └─ status: StatusOK + │ ├─ processor:resourcedetection + │ │ └─ status: StatusOK + │ └─ receiver:filelog/platformlogs + │ └─ status: StatusOK + └─ pipeline:metrics/hostmetrics + ├─ status: StatusOK + ├─ exporter:elasticsearch/ecs + │ └─ status: StatusOK + ├─ processor:attributes/dataset + │ └─ status: StatusOK + ├─ processor:elasticinframetrics + │ └─ status: StatusOK + ├─ processor:resource/process + │ └─ status: StatusOK + ├─ processor:resourcedetection + │ └─ status: StatusOK + └─ receiver:hostmetrics/system + └─ status: StatusOK +---- ++ +. Congratulations! Host logs and metrics are now being collected and ingested by the {agent} service running an OTel Collector instance. +For further details about OpenTelemetry collector components supported by {agent}, refer to the link:https://github.com/elastic/elastic-agent/tree/main/internal/pkg/otel#components[Elastic Distribution for OpenTelemetry Collector README]. \ No newline at end of file