Plan your metrics setup

Before you ingest metrics at scale, decide on two things: the data model your metrics are stored in, and the ingest path for your deployment type. Elastic doesn't convert metrics between schemas at ingest, so the ingest path you use determines how your data is stored, which field names you query, and which prebuilt dashboards work.

The data model is the schema your metrics are stored with: the naming conventions that determine your metric and field names. Use the OpenTelemetry schema unless you need existing Elastic Common Schema (ECS) integrations, dashboards, and alerts to keep working without customization. For that and other use cases where ECS might work better, refer to Know when to keep using classic Elastic components.

OpenTelemetry (OTel) schema

Metrics follow the OpenTelemetry semantic conventions, for example the metric system.cpu.utilization, with attributes stored under attributes.* and resource.attributes.*. This is the default. It matches the OpenTelemetry ecosystem and the Elastic OpenTelemetry ingest paths.

Elastic Common Schema (ECS)

Metrics follow Elastic's original field naming conventions, for example system.cpu.user.pct. Elastic Agent integrations write this schema, as does Metricbeat, the standalone Beats shipper for metrics. Use ECS when you need existing ECS integrations, dashboards, and alerts to keep working without customization.

Prometheus names

Prometheus remote write uses neither schema. It stores Prometheus metric and label names as they arrive, for example the metric node_cpu_seconds_total, with labels stored under labels.*. You get this data model when you keep Prometheus and add Elastic as a remote write target.

Use one schema. Mixing OpenTelemetry and ECS in one deployment works, but requires two sets of field names in your queries and dashboards.

For the OpenTelemetry Protocol (OTLP) paths, refer to How your ingest path determines the data format. For Prometheus remote write, refer to Data mapping.

The schema you choose affects how you ingest, which metric names you query, and which dashboards work without customization:

Prometheus remote write isn't in the table because it isn't a schema you choose: metrics ingested that way always keep their Prometheus names.

PromQL support depends on storage, not schema. Elasticsearch evaluates PromQL over any TSDS matched by metrics-*, whichever ingest path filled it. OTLP and Prometheus remote write metrics always land in a TSDS. Elastic Agent integration data streams are a TSDS when the integration enables it. Refer to the PromQL reference for how Elasticsearch evaluates PromQL.

Your deployment type determines the recommended path. Use Elastic Agent integrations instead of the recommended path only when you need ECS.

For configuration details for each path, refer to Ingest metrics.