OpenTelemetry & Prometheus Compatibility

Comprehensive guide to using OpenTelemetry metrics with PromQL, explaining metric naming conventions, query building, and best practices for effective monitoring and analysis of telemetry data.

Overview

Dash0 provides a comprehensive approach to working with OpenTelemetry metrics through PromQL, giving you the flexibility to query your metrics data using either OpenTelemetry metric names or their Prometheus-compatible equivalents. This documentation explains how metrics are represented in Dash0, how naming conventions work across both formats, and how to identify converted names.

Sending Prometheus Metrics to Dash0

The best way to send Prometheus metrics to Dash0 is via the OpenTelemetry collector. Check out our dedicated documentation page about the configuration of the Prometheus receiver.

Understanding Metric Naming Conventions

When OpenTelemetry metrics are sent to Dash0, they maintain their original names while also being exposed with Prometheus-compatible names according to the OpenTelemetry specification. This dual-naming approach gives you flexibility in how you query your data.

For example, an OpenTelemetry metric named k8s.pod.memory.working_set might be exposed in Prometheus format as k8s_pod_memory_working_set_bytes. Both names refer to the exact same underlying metric data, and you can use either in your queries depending on your preference.

Key Transformations

The following transformations are applied when converting OpenTelemetry metric names to Prometheus format:

  • Type suffixes are added (e.g., _total for counters)
  • Unit suffixes may be added (e.g., _seconds)
  • Invalid characters are replaced with underscores
  • Multiple consecutive underscores are replaced with a single underscore

For further details on this process, refer to the OpenTelemetry reference documentation.

Using OpenTelemetry Metric Names in PromQL

A powerful feature of Dash0 is the ability to query metrics directly by their OpenTelemetry names using the otel_metric_name label filter (also see our semantic conventions). This is especially useful when you're familiar with your OpenTelemetry instrumentation but not necessarily with how the names translate to Prometheus format.

For example, to query a metric by its OpenTelemetry name:

1
{otel_metric_name = "k8s.pod.memory.working_set", service_name = "adservice"}

This query will return information about the working set memory of adservice pods, regardless of its Prometheus-compatible name. You can also choose to use the Prometheus-compatible names, in which case the query looks like this:

1
k8s_pod_memory_working_set_bytes{service_name="adservice"}

The easiest way to learn about supported metric names, and especially the Prometheus compatible names, is via the query builder. Once you provide the metric name's prefix, the auto-completion will show you all fitting metric names:

PromQL editor's auto completion showing suggestions for Kubernetes pod memory metrics
PromQL editor's auto completion showing suggestions for Kubernetes pod memory metrics

One gotcha is the direct usage of OpenTelemetry metric names in places where it is not allowed. For instance, the following query will return an unexpected character: '.' parsing error.

1
jvm.memory.used.bytes{service.name="catalog", jvm.memory.type="heap"}

To fix this, use Prometheus-compatible metric names and label keys.

1
jvm_memory_used_bytes{service_name="adservice", jvm_memory_type="heap"}

Last updated: May 10, 2025