--- title: Prometheus and OpenMetrics metrics collection from a host description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Integrations > Integration Guides > Prometheus and OpenMetrics metrics collection from a host --- # Prometheus and OpenMetrics metrics collection from a host Collect your exposed Prometheus and OpenMetrics metrics from your application running on your hosts using the Datadog Agent, and the [Datadog-OpenMetrics](https://docs.datadoghq.com/integrations/openmetrics/) or [Datadog-Prometheus](https://docs.datadoghq.com/integrations/prometheus/) integrations. ## Overview{% #overview %} Starting with version 6.5.0, the Agent includes [OpenMetrics](https://github.com/DataDog/integrations-core/tree/master/openmetrics) and [Prometheus](https://github.com/DataDog/integrations-core/tree/master/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](https://docs.datadoghq.com/extend/custom_checks/prometheus/) 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. ## Setup{% #setup %} ### Installation{% #installation %} [Install the Datadog Agent for your corresponding operating system](https://app.datadoghq.com/account/settings/agent/latest). OpenMetrics and Prometheus checks are included in the [Datadog Agent](https://docs.datadoghq.com/getting_started/tagging/) package, so you don't need to install anything else on your containers or hosts. ### Configuration{% #configuration %} To collect your exposed metrics: 1. Edit the `openmetrics.d/conf.yaml` file in the `conf.d/` folder at the root of your [Agent's configuration directory](https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory). See the [sample openmetrics.d/conf.yaml](https://github.com/DataDog/integrations-core/blob/master/openmetrics/datadog_checks/openmetrics/data/conf.yaml.example) for all available configuration options. This is the minimum required configuration needed to enable the integration: ```yaml init_config: instances: - openmetrics_endpoint: 'localhost:/' namespace: '' metrics: - '': '' ``` With the following configuration placeholder values: | Placeholder | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | 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 `` metric key to `` in Datadog.If you choose not to use this option, pass a list of strings rather than `key:value` pairs. | 1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent) to start collecting your metrics. ### Parameters available{% #parameters-available %} Find below the full list of parameters that can be used for your `instances`: | Name | Type | Necessity | Default value | Description | | --------------------------------------- | --------------------------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openmetrics_endpoint` | string | required | none | The URL exposing metrics in the OpenMetrics format. | | `namespace` | string | required | none | The namespace to be appended before all metrics namespaces. Your metrics are collected in the form `namespace.metric_name`. | | `metrics` | list of strings or `key:value` elements | required | none | List of `: ` pairs for metrics to be fetched from the Prometheus endpoint.`` is optional. It transforms the name in Datadog if set. This list should contain at least one metric. | | `raw_metric_prefix` | string | optional | none | A prefix that is removed from all exposed metric names, if present. | | `health_service_check` | boolean | optional | true | Send a service check reporting on the health of the Prometheus endpoint. The check is named `.prometheus.health`. | | `label_to_hostname` | string | optional | none | Override the hostname with the value of one label. | | `label_joins` | object | optional | none | The label join allows you to target a metric and retrieve its label using a 1:1 mapping. | | `labels_mapper` | list of key:value element | optional | none | The label mapper allows you to rename some labels. Format: `: `. | | `type_overrides` | 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).Supported ``s are `gauge`, `monotonic_count`, `histogram`, and `summary`. | | `tags` | 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](https://docs.datadoghq.com/extend/custom_checks/prometheus/). | | `send_distribution_buckets` | boolean | optional | false | Set `send_distribution_buckets` to `true` to send and convert OpenMetrics histograms to [Distribution metrics](https://docs.datadoghq.com/metrics/distributions/).`collect_histogram_buckets` must be set to `true` (default value).**Note**: For OpenMetrics v2, use `collect_counters_with_distributions` instead. | | `send_distribution_counts_as_monotonic` | boolean | optional | false | Set `send_distribution_counts_as_monotonic` to `true` to send OpenMetrics histogram/summary counts as monotonic counts. | | `collect_histogram_buckets` | boolean | optional | true | Set `collect_histogram_buckets` to `true` to send the histograms bucket. | | `send_monotonic_counter` | boolean | optional | true | o send counts as monotonic counts see the [relevant issue in GitHub](https://github.com/DataDog/integrations-core/blob/master/openmetrics/datadog_checks/openmetrics/data/conf.yaml.example). | | `exclude_labels` | list of string | optional | none | List of labels to be excluded. | | `ssl_cert` | 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. | | `ssl_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. | | `ssl_ca_cert` | string | optional | none | The path to the trusted CA used for generating custom certificates. | | `timeout` | integer | optional | 10 | Set a timeout in seconds for the Prometheus/OpenMetrics query. | | `max_returned_metrics` | integer | optional | 2000 | The check limits itself to 2000 metrics by default. Increase this limit if needed. | | `bearer_token_auth` | boolean | optional | false | Set `bearer_token_auth` to `true` to add a bearer token authentication header. **Note**: If `bearer_token_path` is not set, `/var/run/secrets/kubernetes.io/serviceaccount/token` is used as the default path. | | `bearer_token_path` | string | optional | none | The path to a Kubernetes service account bearer token file (make sure the file exists and is mounted correctly). **Note**: Set `bearer_token_auth` to `true` to enable adding the token to HTTP headers for authentication. | | `collect_counters_with_distributions` | boolean | optional | false | Whether or not to also collect the observation counter metrics ending in `.sum` and `.count` when sending histogram buckets as Datadog distribution metrics. This implicitly enables the `histogram_buckets_as_distributions` option. | **Note**: All parameters but `send_distribution_buckets` and `send_distribution_counts_as_monotonic` are supported by both OpenMetrics check and Prometheus check. ## Getting started{% #getting-started %} ### Simple metric collection{% #simple-metric-collection %} To get started with collecting metrics exposed by Prometheus, follow these steps: 1. Follow the [Prometheus Getting Started](https://prometheus.io/docs/prometheus/latest/getting_started/) documentation to start a local version of Prometheus that monitors itself. 1. [Install the Datadog Agent for your platform](https://app.datadoghq.com/account/settings/agent/latest). 1. Edit the `openmetrics.d/conf.yaml` file in the `conf.d/` folder at the root of your [Agent's configuration directory](https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory) with the following content: ```yaml init_config: instances: - openmetrics_endpoint: http://localhost:9090/metrics namespace: 'documentation_example' metrics: - promhttp_metric_handler_requests_total: prometheus.handler.requests.total ``` 1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/?tab=agentv6v7#restart-the-agent). 1. Go into your [Metric summary page](https://app.datadoghq.com/metric/summary) to see the collected metrics: `prometheus_target_interval_length_seconds*` {% image source="https://datadog-docs.imgix.net/images/integrations/guide/prometheus_host/prometheus_collected_metric_host.6bcb35fae11bfffa630b5a5fbb0f8105.png?auto=format" alt="Prometheus metric collected" /%} ## From custom to official integration{% #from-custom-to-official-integration %} 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](https://docs.datadoghq.com/extend/custom_checks/prometheus/)! 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](https://github.com/DataDog/integrations-core/tree/master/kube_proxy) integration. ## Further Reading{% #further-reading %} - [Collect your logs](https://docs.datadoghq.com/logs/log_collection) - [Collect your processes](https://docs.datadoghq.com/infrastructure/process) - [Collect your traces](https://docs.datadoghq.com/tracing) - [Write your own custom Prometheus Check](https://docs.datadoghq.com/extend/prometheus)