Add small doc about running a standalone agent in otel mode (#1572) (#…

…1574)

* Add small doc about running a standalone agent in otel mode

---------

Co-authored-by: David Kilfoyle <[email protected]>
(cherry picked from commit 99836e0)

# Conflicts:
#	docs/en/ingest-management/elastic-agent/otel-agent-transform.asciidoc

Co-authored-by: Paolo Chilà <[email protected]>

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 <<otel-agent,OTel Collector>>. 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 <<otel-agent,OTel Collector>> 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 <<create-api-key-standalone-agent,{es} API key>> 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].