Starting with version 6.5.0, the Agent includes OpenMetrics and Prometheus checks capable of scraping Prometheus endpoints. Datadog recommends using the OpenMetrics check since it is more efficient and fully supports Prometheus text format. For more advanced usage of the
OpenMetricsCheck interface, including writing a custom check, see the Developer Tools section. Use the Prometheus check only when the metrics endpoint does not support a text format.
This page explains the basic usage of these checks, enabling you to import all your Prometheus exposed metrics within Datadog.
Install the Datadog Agent for your corresponding operating system. OpenMetrics and Prometheus checks are included in the Datadog Agent package, so you don’t need to install anything else on your containers or hosts.
To collect your exposed metrics:
openmetrics.d/conf.yaml file in the
conf.d/ folder at the root of your Agent’s configuration directory. See the sample openmetrics.d/conf.yaml for all available configuration options. This is the minimum required configuration needed to enable the integration::
init_config: instances: - prometheus_url: 'localhost:<PORT>/<ENDPOINT>' namespace: '<NAMESPACE>' metrics: - '<METRIC_TO_FETCH>': '<DATADOG_METRIC_NAME>'
With the following configuration placeholder values:
|Port to connect to in order to access the Prometheus endpoint.|
|URL for the metrics served by the container, in Prometheus format.|
|Set namespace to be prefixed to every metric when viewed in Datadog.|
|Prometheus metrics key to be fetched from the Prometheus endpoint.|
|Optional parameter which, if set, transforms the |
If you choose not to use this option, pass a list of strings rather than
Restart the Agent to start collecting your metrics.
Find below the full list of parameters that can be used for your
|string||required||none||The URL where your application metrics are exposed by Prometheus/OpenMetrics.|
|string||required||none||The namespace to be appended before all metrics namespaces. Your metrics are collected in the form |
|list of strings or ||required||none||List of |
|string||optional||none||Prefix for exposed Prometheus/OpenMetrics metrics.|
|boolean||optional||true||Send a service check reporting on the health of the Prometheus endpoint. The check is named |
|string||optional||none||Override the hostname with the value of one label.|
|object||optional||none||The label join allows you to target a metric and retrieve its label via a 1:1 mapping.|
|list of key:value element||optional||none||The label mapper allows you to rename some labels. Format: |
|list of key:value element||optional||none||Type override allows you to override a type in the Prometheus payload or type an untyped metric (they’re ignored by default).|
|list of key:value element||optional||none||List of tags to attach to every metric, event, and service check emitted by this integration.|
Learn more about tagging.
|boolean||optional||true||o send counts as monotonic counts see the relevant issue in GitHub.|
|list of string||optional||none||List of labels to be excluded.|
|string||optional||none||If your Prometheus endpoint is secured, here are the settings to configure it:|
Can either be: only the path to the certificate and thus you should specify the private key, or it can be the path to a file containing both the certificate and the private key.
|string||optional||none||Needed if the certificate does not include the private key.|
WARNING: The private key to your local certificate must be unencrypted.
|string||optional||none||The path to the trusted CA used for generating custom certificates.|
|integer||optional||10||Set a timeout in seconds for the Prometheus/OpenMetrics query.|
|integer||optional||2000||The check limits itself to 2000 metrics by default. Increase this limit if needed.|
|string||optional||none||The path to a Kubernetes service account bearer token file (make sure the file exists and is mounted correctly). Note: Set |
Note: All parameters but
send_distribution_counts_as_monotonic are supported by both OpenMetrics check and Prometheus check.
To get started with collecting metrics exposed by Prometheus, follow these steps:
Follow the Prometheus Getting Started documentation to start a local version of Prometheus that monitors itself.
openmetrics.d/conf.yaml file in the
conf.d/ folder at the root of your Agent’s configuration directory with the following content:
init_config: instances: - prometheus_url: http://localhost:9090/metrics namespace: 'documentation_example' metrics: - promhttp_metric_handler_requests_total: prometheus.handler.requests.total
Go into your Metric summary page to see the collected metrics:
By default, all metrics retrieved by the generic Prometheus check are considered custom metrics. If you are monitoring off-the-shelf software and think it deserves an official integration, don’t hesitate to contribute!
Official integrations have their own dedicated directories. There’s a default instance mechanism in the generic check to hardcode the default configuration and metrics metadata. For example, reference the kube-proxy integration.
Additional helpful documentation, links, and articles: