Quickstart for Docker on Elastic Cloud Hosted

Learn how to set up the Elastic Agent and EDOT SDKs in a Docker environment with Elastic Cloud Hosted (ECH) to collect host metrics, logs, and application traces. This quickstart uses the Elastic Cloud Managed OTLP Endpoint — the recommended ingestion path for ECH.

Guided setup

Use the Add data screen in Elastic Observability to generate install commands that are already configured with the values you need.

Open Elastic Observability.
Go to Add data.
Select what you want to monitor.
Follow the instructions.

Prerequisites

An Elastic Cloud Hosted deployment running version 9.0 or later.
Docker and Docker Compose installed on the host.

Manual installation

Follow these steps to deploy the Elastic Agent and EDOT SDKs in Docker with ECH.

Create the config file

Create an otel-collector-config.yml file with your Elastic Agent configuration for the Elastic Cloud Managed OTLP Endpoint. Refer to the configuration reference.
Find your endpoint and create an API key

Find your endpoint
1. Log in to the Elastic Cloud Console.
2. From the home page, 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
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:
  { "otlp_writer": { "applications": [ { "application": "apm", "resources": ["*"], "privileges": ["event:write"] } ] } }
4. Click Create API key and copy the encoded value.
Using the Elasticsearch API
Use the Create API key API:
POST /_security/api_key { "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.

Create the .env file

Create a .env file with the following content. Replace the placeholder values with your Elastic Cloud credentials:

		HOST_FILESYSTEM=/
DOCKER_SOCK=/var/run/docker.sock
ELASTIC_AGENT_OTEL=true
COLLECTOR_CONTRIB_IMAGE=elastic/elastic-agent:9.5.1
ELASTIC_API_KEY=<your_api_key_here>
ELASTIC_OTLP_ENDPOINT=<your_motlp_endpoint_here>
OTEL_COLLECTOR_CONFIG=/path/to/otel-collector-config.yml
		
	

Create the compose file

Create a compose.yml file with the following content:

		services:
 otel-collector:
   image: ${COLLECTOR_CONTRIB_IMAGE}
   container_name: otel-collector
   deploy:
     resources:
       limits:
         memory: 1.5G
   restart: unless-stopped
   command: ["--config", "/etc/otelcol-config.yml" ]
   network_mode: host
   user: 0:0
   volumes:
     - ${HOST_FILESYSTEM}:/hostfs:ro
     - ${DOCKER_SOCK}:/var/run/docker.sock:ro
     - ${OTEL_COLLECTOR_CONFIG}:/etc/otelcol-config.yml
   environment:
     - HOST_FILESYSTEM
     - ELASTIC_AGENT_OTEL
     - ELASTIC_API_KEY
     - ELASTIC_OTLP_ENDPOINT
     - STORAGE_DIR=/usr/share/elastic-agent
		
	

Start the Collector

To start the Collector, run:
```
docker compose up -d
		
```
(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
- .NET
- iOS
- Java
- Node.js
- PHP
- Python
Configure your SDKs to send the data to the local Elastic Agent using OTLP/gRPC (http://localhost:4317) or OTLP/HTTP (http://localhost:4318).

Tip

Enable Central Configuration to configure your EDOT SDKs from within Kibana. Refer to EDOT SDKs Central Configuration.
Install the content packs

Install the System OpenTelemetry Assets integration and the Docker OpenTelemetry Assets integration in Kibana.
Explore your data

Go to Kibana and select Dashboards to explore your newly collected data.

Using the `elasticsearch` exporter

If you need to write telemetry directly to Elasticsearch — for example, for pipeline customizations not yet supported through Elastic Cloud Managed OTLP Endpoint — use the following .env and compose configuration instead.

Retrieve your Elasticsearch URL and your API key:

Retrieve the Elasticsearch URL for your Elastic Cloud deployment:
1. Go to the Elastic Cloud console.
2. Next to your deployment, select Manage.
3. Under Applications next to Elasticsearch, select Copy endpoint.
Create an API Key following these instructions.

Create a .env file with your Elasticsearch endpoint and credentials:

		HOST_FILESYSTEM=/
DOCKER_SOCK=/var/run/docker.sock
ELASTIC_AGENT_OTEL=true
COLLECTOR_CONTRIB_IMAGE=elastic/elastic-agent:9.5.1
ELASTIC_API_KEY=<your_api_key_here>
ELASTIC_ENDPOINT=<your_elasticsearch_endpoint_here>
OTEL_COLLECTOR_CONFIG=/path/to/otel-collector-config.yml
		
	

Use the following compose file, which passes ELASTIC_ENDPOINT instead of ELASTIC_OTLP_ENDPOINT:

		services:
 otel-collector:
   image: ${COLLECTOR_CONTRIB_IMAGE}
   container_name: otel-collector
   deploy:
     resources:
       limits:
         memory: 1.5G
   restart: unless-stopped
   command: ["--config", "/etc/otelcol-config.yml" ]
   network_mode: host
   user: 0:0
   volumes:
     - ${HOST_FILESYSTEM}:/hostfs:ro
     - ${DOCKER_SOCK}:/var/run/docker.sock:ro
     - ${OTEL_COLLECTOR_CONFIG}:/etc/otelcol-config.yml
   environment:
     - HOST_FILESYSTEM
     - ELASTIC_AGENT_OTEL
     - ELASTIC_API_KEY
     - ELASTIC_ENDPOINT
     - STORAGE_DIR=/usr/share/elastic-agent
		
	

Troubleshooting

The following issues might occur.

API key prefix not found

The following error is due to an improperly formatted API key:

		Exporting failed. Dropping data.
{"kind": "exporter", "data_type": }
"Unauthenticated desc = ApiKey prefix not found"
		
	

Format your API key as "Authorization": "ApiKey <api-key-value-here>" or "Authorization=ApiKey <api-key>" depending on whether you're using a Collector or SDK.

For additional troubleshooting, refer to Troubleshooting common issues with the Elastic Agent and Troubleshooting the EDOT SDKs.