Start using OpenTelemetry with Elastic

This guide helps you choose the right setup for your environment so you can start sending metrics, logs, and traces to Elastic using Elastic OpenTelemetry. Elastic OpenTelemetry is Elastic's fully supported, pre-configured distribution of the upstream OpenTelemetry tools, optimized for Elastic ingest and analysis.

EDOT SDKs and Elastic Agent in OTel mode require Elastic Stack 8.16 or later for basic compatibility. For a supported configuration, use:

  • Elastic Stack 9.x, or
  • Elastic Stack 8.18 or 8.19 with Elastic Agent version 9.x. You have to keep your configuration aligned to your Stack version, not the Elastic Agent 9.x defaults.

Elastic Cloud Serverless has no version requirements.

Refer to Elastic Agent and Elastic Stack compatibility for the full matrix.

Your setup depends on the telemetry you collect:

  • Application telemetry (traces, metrics, and logs from your code): use an EDOT language SDK. It auto-instruments your application with zero or minimal code changes.
  • Infrastructure telemetry (host metrics, logs, Kubernetes signals): use Elastic Agent to collect system-level data from your hosts, containers, or cluster.
  • Both application and infrastructure telemetry: most production setups collect application and infrastructure telemetry together. You can run an EDOT SDK and Elastic Agent on the same host.

The recommended ingestion path depends on your Elastic deployment type. Select your deployment to see the recommended setup.

Important

Regardless of your deployment, do not point EDOT SDKs directly at the APM Server OpenTelemetry intake endpoint, as this configuration is not supported. EDOT SDKs work only when sending data through Elastic Agent or the Elastic Cloud Managed OTLP Endpoint.

Send data to the Elastic Cloud Managed OTLP Endpoint.

The Elastic Cloud Managed OTLP Endpoint is GA for Elastic Cloud Serverless Observability and Security projects. Elastic Agent is not required for application telemetry, you can just point your EDOT SDK or any OTLP-compatible exporter directly at the managed endpoint.

For infrastructure telemetry (host metrics, logs, Kubernetes), run Elastic Agent on your hosts or cluster and configure it to export data to the Elastic Cloud Managed OTLP Endpoint using the OTLP exporter.

Before committing to this path, note these Elastic Cloud Managed OTLP Endpoint limitations:

  • Tail-based sampling (TBS) is not available. Configure head-based sampling at the edge before sending data.
  • Universal Profiling is not available.

Refer to Elastic Cloud Managed OTLP Endpoint for the full list of limitations and configuration details.

Send data to the Elastic Cloud Managed OTLP Endpoint.

The Elastic Cloud Managed OTLP Endpoint is GA on Elastic Cloud Hosted and Serverless. For application telemetry only, send directly from your EDOT SDK or any OTLP-compatible exporter to the endpoint, with no Elastic Agent required. For infrastructure telemetry, run Elastic Agent on your hosts or cluster and configure it to export to the Elastic Cloud Managed OTLP Endpoint using the OTLP exporter.

Note

The current Elastic Cloud Hosted quickstarts use a different path: an Elastic Agent running on a host and writing directly to Elasticsearch using the elasticsearch exporter. This alternative works, but for new setups, use the mOTLP path. For more information, refer to Send OTLP data to the Elastic Cloud Managed OTLP Endpoint.

Before committing to this path, note these Elastic Cloud Managed OTLP Endpoint limitations:

  • Tail-based sampling (TBS) is not available. Configure head-based sampling at the edge before sending data.
  • Universal Profiling is not available.

Refer to Elastic Cloud Managed OTLP Endpoint for the full list of limitations and configuration details.

Run Elastic Agent in gateway mode.

The Elastic Cloud Managed OTLP Endpoint is not available for self-managed Elastic, ECE, or ECK deployments. You need an Elastic Agent running as a gateway.

Elastic Agent running as a gateway is required for full APM functionality. It:

  • Exposes an OTLP endpoint that edge collectors, EDOT SDKs, and other OTLP sources send data to.
  • Runs the elasticapm processor to enrich trace data with attributes the Elastic Observability UIs rely on.
  • Runs the elastictrace processor to enrich trace data with attributes.
  • Runs the elasticapm connector to generate pre-aggregated APM metrics from traces.
  • Routes telemetry to the correct data streams and writes to Elasticsearch using the elasticsearch exporter in the otel mapping mode.

For edge collectors running on your hosts, Kubernetes nodes, or alongside your applications, use the OTLP exporter to forward data to the gateway. The elasticsearch exporter is only recommended for the gateway itself, not for edge collectors.

Refer to Elastic Agent modes and Default standalone configurations for step-by-step setup.

Use the quickstart that matches your deployment and environment:

Deployment model Kubernetes Docker Hosts or VMs
Self-managed Elastic Stack K8s on self-managed Docker on self-managed Hosts on self-managed
Elastic Cloud Serverless K8s on serverless Docker on serverless Hosts on serverless
Elastic Cloud Hosted K8s on hosted Docker on hosted Hosts on hosted

To send OTLP data directly to Elastic Cloud Serverless or Elastic Cloud Hosted without running Elastic Agent, follow Send OTLP data to the Elastic Cloud Managed OTLP Endpoint.

After setting up an ingestion path, add an EDOT language SDK to your application. Each SDK auto-instruments your application and sends OTLP data to your configured endpoint.

Important

Avoid running an EDOT SDK alongside any other APM agent in the same application process. Running multiple agents can cause conflicting instrumentation, duplicate telemetry, or other unexpected behavior.

Available EDOT SDKs (all GA unless noted):

For languages without an EDOT SDK (Go, C++, Ruby, and others), you can use the contrib OpenTelemetry SDKs. These work with Elastic over OTLP but receive community support only.

Configure your EDOT SDKs and edge Elastic Agent instances to use the OTLP exporter. Elastic recommends the elasticsearch exporter only for the Elastic Agent gateway in a self-managed deployment. Using it at the edge can lead to data loss or incorrect mapping.

Elastic OpenTelemetry covers most core Observability use cases, but the following scenarios still work better with classic Elastic ingestion:

  • Web real user monitoring (RUM): OTel-native RUM data is not yet available for production use. EDOT Browser is in Technical Preview. For production RUM, use the classic Elastic APM browser agent.
  • Universal Profiling: Only available with classic Elastic ingestion, and not through OTel-native data.
  • Existing ECS integrations and dashboards: Many prebuilt integrations and dashboards use ECS-formatted data and may not work with OpenTelemetry semantic conventions without customization. Install OpenTelemetry content packs from the Kibana Integrations UI (search for otel) to get OTel-compatible dashboards.
  • Tail-based sampling (TBS): Elastic OpenTelemetry does not provide managed TBS. The Elastic Cloud Managed OTLP Endpoint has no TBS support, so you have to configure sampling at the edge before sending. You can configure self-managed TBS, with some caveats, in:
    • Elastic Agent
    • Any OTel-compatible Collector
  • Centrally managed log processing: Elastic doesn't provide curated, centralized Elasticsearch ingest pipelines for OTel-native data. Process logs in the Collector instead, or define your own ingest pipeline. For dotted field names in user-defined pipelines, you can:

Refer to Limitations of Elastic OpenTelemetry for the full list.

After completing your quickstart, confirm that data is flowing:

  1. Open Kibana and go to Elastic Observability → Applications → Service inventory (or use the global search to find Service inventory) to confirm your application traces appear.
  2. Go to Elastic Observability → Infrastructure (or search for Infrastructure) to confirm host and container metrics are visible.
  3. Go to Discover and filter by your service name to confirm log data is flowing.

If data is missing, refer to Troubleshoot Elastic OpenTelemetry.