---
title: Quickstart for hosts and VMs on Elastic Cloud Hosted
description: Learn how to set up the {{agent}} and EDOT SDKs with Elastic Cloud Hosted to collect host metrics, logs, and application traces using the Managed OTLP Endpoint.
url: https://www.elastic.co/elastic/docs-builder/docs/4116/solutions/observability/get-started/opentelemetry/quickstart/ech/hosts_vms
products:
  - Elastic Agent
  - Elastic Cloud Hosted
  - Elastic Observability
applies_to:
  - Elastic Cloud Hosted: Generally available
---

# Quickstart for hosts and VMs on Elastic Cloud Hosted
Learn how to set up the Elastic Agent and EDOT SDKs on hosts and VMs with Elastic Cloud Hosted (ECH) to collect host metrics, logs, and application traces. This quickstart uses the [Elastic Cloud Managed OTLP Endpoint](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/managed-inputs/managed-otlp-endpoint), which is the recommended ingestion path for ECH.

## Prerequisites

- An Elastic Cloud Hosted deployment running version 9.0 or later.
- The host or VM running a supported operating system (Linux, macOS, or Windows).


## Guided setup

The fastest way to get started is the **Add data** screen in Elastic Observability. It generates install commands with your endpoint and API key already included.
1. Open Elastic Observability.
2. Go to **Add data**.
3. Select what you want to monitor.
4. Follow the instructions.

If you need to manage credentials manually, for example, to use them in automation or to configure multiple environments, follow the steps in the Manual installation section.

## Manual installation

Follow these steps to deploy the Elastic Agent and EDOT SDKs with ECH:
<stepper>
  <step title="Download the {{agent}}">
    [Download the Elastic Agent](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/edot-collector/download) for your operating system.
  </step>

  <step title="Find your endpoint and create an API key">
    **Find your endpoint**
    The easiest way to get your endpoint and API key is from the **Add data** screen in Kibana:
    1. Go to **Add data**.
    2. In the **Connect directly to the endpoint** section, select the **OpenTelemetry** tab.
    3. Copy the **Endpoint** value.
    4. Click **Create key** to generate an API key with the required privileges.

    Alternatively, retrieve the endpoint from the Elastic Cloud Console and create an API key manually:
    1. Log in to the [Elastic Cloud Console](https://cloud.elastic.co/).
    2. Find your deployment in **Hosted deployments**, and select **Manage**.
    3. In the **Application endpoints, cluster and component IDs** section, select **Managed OTLP**.
    4. Copy the public endpoint value.

    **Create an API key**
    <note>
      The Elastic Cloud Managed OTLP Endpoint validates API keys using APM application privileges. Index-level privilege scoping is not yet supported, meaning that API keys with custom index-level role descriptors return a `PermissionDenied` error.
    </note>

    <dropdown title="Using Kibana">
      1. Go to **Stack Management** → **API keys**.
      2. Click **Create API key**, enter a name, and enable **Control security privileges**.
      3. In the role descriptors box, enter the following privileges:
         ```json
         {
           "otlp_writer": {
             "applications": [
               {
                 "application": "apm",
                 "resources": ["*"],
                 "privileges": ["event:write"]
               }
             ]
           }
         }
         ```
      4. Click **Create API key** and copy the encoded value.
    </dropdown>

    <dropdown title="Using the Elasticsearch API">
      Use the [Create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) API:
      ```json

      {
        "name": "otlp-writer",
        "role_descriptors": {
          "otlp_writer": {
            "applications": [
              {
                "application": "apm",
                "resources": ["*"],
                "privileges": ["event:write"]
              }
            ]
          }
        }
      }
      ```
      The `event:write` privilege for the `apm` application is the minimum required to send data through the Elastic Cloud Managed OTLP Endpoint.
    </dropdown>
  </step>

  <step title="Configure the {{agent}}">
    Replace `<ELASTIC_OTLP_ENDPOINT>` and `<ELASTIC_API_KEY>` before applying the following commands.
    <tab-set>
      <tab-item title="Linux">
        ```bash
        ELASTIC_OTLP_ENDPOINT=<ELASTIC_OTLP_ENDPOINT> && \
        ELASTIC_API_KEY=<ELASTIC_API_KEY> && \
        cp ./otel_samples/managed_otlp/logs_metrics_traces.yml ./otel.yml && \
        mkdir -p ./data/otelcol && \
        sed -i "s#\${env:STORAGE_DIR}#${PWD}/data/otelcol#g" ./otel.yml && \
        sed -i "s#\${env:ELASTIC_OTLP_ENDPOINT}#${ELASTIC_OTLP_ENDPOINT}#g" ./otel.yml && \
        sed -i "s#\${env:ELASTIC_API_KEY}#${ELASTIC_API_KEY}#g" ./otel.yml
        ```
      </tab-item>

      <tab-item title="macOS">
        ```bash
        ELASTIC_OTLP_ENDPOINT=<ELASTIC_OTLP_ENDPOINT> && \
        ELASTIC_API_KEY=<ELASTIC_API_KEY> && \
        cp ./otel_samples/managed_otlp/logs_metrics_traces.yml ./otel.yml && \
        mkdir -p ./data/otelcol && \
        sed -i '' "s#\${env:STORAGE_DIR}#${PWD}/data/otelcol#g" ./otel.yml && \
        sed -i '' "s#\${env:ELASTIC_OTLP_ENDPOINT}#${ELASTIC_OTLP_ENDPOINT}#g" ./otel.yml && \
        sed -i '' "s#\${env:ELASTIC_API_KEY}#${ELASTIC_API_KEY}#g" ./otel.yml
        ```
      </tab-item>

      <tab-item title="Windows">
        ```powershell
        Remove-Item -Path .\otel.yml -ErrorAction SilentlyContinue
        Copy-Item .\otel_samples\managed_otlp\logs_metrics_traces.yml .\otel.yml
        New-Item -ItemType Directory -Force -Path .\data\otelcol | Out-Null

        $content = Get-Content .\otel.yml
        $content = $content -replace '\${env:STORAGE_DIR}', "$PWD\data\otelcol"
        $content = $content -replace '\${env:ELASTIC_OTLP_ENDPOINT}', "<ELASTIC_OTLP_ENDPOINT>"
        $content = $content -replace '\${env:ELASTIC_API_KEY}', "<ELASTIC_API_KEY>"
        $content | Set-Content .\otel.yml
        ```
      </tab-item>
    </tab-set>
    For details about the pipelines, refer to [Using the Managed OTLP Endpoint](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/edot-collector/config/default-config-standalone#using-the-managed-otlp-endpoint).
  </step>

  <step title="Run the {{agent}}">
    Use the following command to start the Elastic Agent.
    <tab-set>
      <tab-item title="Linux and macOS">
        ```bash
        sudo ./otelcol --config otel.yml
        ```
      </tab-item>

      <tab-item title="Windows">
        ```powershell
        .\elastic-agent.exe otel --config otel.yml
        ```
      </tab-item>
    </tab-set>

    <note>
      By default, the Collector opens ports `4317` and `4318` to receive application data from locally running EDOT SDKs.
    </note>
  </step>

  <step title="(Optional) Instrument your applications">
    To collect telemetry from applications and use the Elastic Agent as a gateway, instrument your target applications following the setup instructions:
    - [Android](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/android)
    - [.NET](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/dotnet/setup)
    - [iOS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/ios)
    - [Java](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/java/setup)
    - [Node.js](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/node/setup)
    - [PHP](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/php/setup)
    - [Python](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/edot-sdks/python/setup)
    Configure your SDKs to send the data to the local Elastic Agent using OTLP/gRPC (`http://localhost:4317`) or OTLP/HTTP (`http://localhost:4318`).
  </step>

  <step title="Explore your data">
    Go to Kibana and select **Dashboards** to explore your newly collected data.
  </step>
</stepper>


## Using the `elasticsearch` exporter

If you need to write telemetry directly to Elasticsearch using the `elasticsearch` exporter (for example, for pipeline customizations not yet supported through Elastic Cloud Managed OTLP Endpoint), follow these steps. For a full list of features and limitations that apply to each path, refer to [Elastic features available with Elastic OpenTelemetry](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/opentelemetry/compatibility/features).
Retrieve your Elasticsearch URL and your API key:
1. Retrieve the Elasticsearch URL for your Elastic Cloud deployment:
   1. Go to the [Elastic Cloud console](https://cloud.elastic.co/).
2. Next to your deployment, select **Manage**.
3. Under **Applications** next to **Elasticsearch**, select **Copy endpoint**.
2. Create an API Key following [these instructions](https://www.elastic.co/elastic/docs-builder/docs/4116/deploy-manage/api-keys/elasticsearch-api-keys).

Replace `<ELASTICSEARCH_ENDPOINT>` and `<ELASTIC_API_KEY>` before applying the following commands.
<tab-set>
  <tab-item title="Linux">
    ```bash
    ELASTICSEARCH_ENDPOINT=<ELASTICSEARCH_ENDPOINT> && \
    ELASTIC_API_KEY=<ELASTIC_API_KEY> && \
    cp ./otel_samples/logs_metrics_traces.yml ./otel.yml && \
    mkdir -p ./data/otelcol && \
    sed -i "s#\${env:STORAGE_DIR}#${PWD}/data/otelcol#g" ./otel.yml && \
    sed -i "s#\${env:ELASTIC_ENDPOINT}#${ELASTICSEARCH_ENDPOINT}#g" ./otel.yml && \
    sed -i "s#\${env:ELASTIC_API_KEY}#${ELASTIC_API_KEY}#g" ./otel.yml
    ```
  </tab-item>

  <tab-item title="macOS">
    ```bash
    ELASTICSEARCH_ENDPOINT=<ELASTICSEARCH_ENDPOINT> && \
    ELASTIC_API_KEY=<ELASTIC_API_KEY> && \
    cp ./otel_samples/logs_metrics_traces.yml ./otel.yml && \
    mkdir -p ./data/otelcol && \
    sed -i '' "s#\${env:STORAGE_DIR}#${PWD}/data/otelcol#g" ./otel.yml && \
    sed -i '' "s#\${env:ELASTIC_ENDPOINT}#${ELASTICSEARCH_ENDPOINT}#g" ./otel.yml && \
    sed -i '' "s#\${env:ELASTIC_API_KEY}#${ELASTIC_API_KEY}#g" ./otel.yml
    ```
  </tab-item>

  <tab-item title="Windows">
    ```powershell
    Remove-Item -Path .\otel.yml -ErrorAction SilentlyContinue
    Copy-Item .\otel_samples\logs_metrics_traces.yml .\otel.yml
    New-Item -ItemType Directory -Force -Path .\data\otelcol | Out-Null

    $content = Get-Content .\otel.yml
    $content = $content -replace '\${env:STORAGE_DIR}', "$PWD\data\otelcol"
    $content = $content -replace '\${env:ELASTIC_ENDPOINT}', "<ELASTICSEARCH_ENDPOINT>"
    $content = $content -replace '\${env:ELASTIC_API_KEY}', "<ELASTIC_API_KEY>"
    $content | Set-Content .\otel.yml
    ```
  </tab-item>
</tab-set>

For details about the pipelines, refer to [Direct ingestion into Elasticsearch](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4116/reference/edot-collector/config/default-config-standalone#direct-ingestion-into-elasticsearch).

## Troubleshooting

The following issues might occur.

### API key prefix not found

The following error is due to an improperly formatted API key, and typically occurs when credentials are configured manually:
```txt
Exporting failed. Dropping data.
{"kind": "exporter", "data_type": }
"Unauthenticated desc = ApiKey prefix not found"
```

For a Collector, format the header as `"Authorization": "ApiKey <api-key>"`. For an SDK, format it as `"Authorization=ApiKey <api-key>"`.
For additional troubleshooting, refer to [Troubleshooting common issues with the Elastic Agent](https://www.elastic.co/elastic/docs-builder/docs/4116/troubleshoot/ingest/opentelemetry/edot-collector) and [Troubleshooting the EDOT SDKs](https://www.elastic.co/elastic/docs-builder/docs/4116/troubleshoot/ingest/opentelemetry/edot-sdks).