Skip to content

Metrics Files

Instead of hardcoding metric name mappings in Python or requiring per-instance user configuration, integrations can ship mappings as YAML files alongside the check module. The base class discovers and loads these files automatically and merges them into the scraper configuration before each scrape.

For the user-level metrics configuration option, the generic OpenMetrics check documentation covers the supported formats. The generic check exposes a default configuration that does not apply to all OpenMetrics-based integrations; each integration surfaces its own set of options. See the individual integration's documentation for the full reference (for example, the KrakenD integration).

Metrics File Format

A metrics file is a YAML document containing a flat mapping of Prometheus metric names to Datadog metric names. The same formats supported by the metrics instance option are valid here.

Simple rename:

go_goroutines: go.goroutines
go_threads: go.threads

Rename with type override:

some_counter:
  name: my.counter
  type: counter

Regex rename:

"(?P<name>.+)_total$": \g<name>

All keys in a single file are merged into the metrics list of the scraper configuration.

Convention-Based Discovery

When METRICS_MAP is not set on the check class, the base class searches for a metrics file next to the check module automatically. The lookup order is:

  1. metrics.yaml
  2. metrics.yml

The first match is loaded; if both exist, .yaml takes precedence. No code is required. Drop the file in the right place and the base class handles the rest.

Explicit Declaration with METRICS_MAP

For integrations that ship multiple files or need to load files conditionally, declare METRICS_MAP as a class variable. The presence of METRICS_MAP (even if empty) suppresses convention-based discovery entirely.

from pathlib import Path

from datadog_checks.base.checks.openmetrics.v2 import (
    ConfigOptionTruthy,
    MetricsMapping,
    OpenMetricsBaseCheckV2,
)


class MyCheck(OpenMetricsBaseCheckV2):
    METRICS_MAP = (
        MetricsMapping(Path("metrics/default.yaml")),
        MetricsMapping(Path("metrics/go.yaml"), predicate=ConfigOptionTruthy("go_metrics")),
        MetricsMapping(Path("metrics/process.yaml"), predicate=ConfigOptionTruthy("process_metrics")),
    )

Paths in METRICS_MAP are relative to the package directory (the directory containing the check module). Files listed without a predicate are always loaded.

Conditional Loading with Predicates

Any MetricsMapping can carry a predicate. When the predicate returns False for the current instance configuration, the file is skipped. A single check class can cover deployments that expose different metric sets based on their configuration.

MetricsMapping(Path("metrics/go.yaml"), predicate=ConfigOptionTruthy("go_metrics"))

The file metrics/go.yaml is loaded only when the instance option go_metrics is truthy. When the option is absent, it defaults to True, so metrics are included unless explicitly disabled.

Predicates are evaluated once per check instance, against the configuration at the time of the first scrape. For the full list of built-in predicates, see the API Reference below.

Custom Predicates

Any class with a should_load(self, config: Mapping) -> bool method satisfies the MetricsPredicate protocol and can be used directly. No inheritance or registration is required:

class MyPredicate:
    def should_load(self, config: Mapping) -> bool:
        return config.get("mode") in ("advanced", "full")


class MyCheck(OpenMetricsBaseCheckV2):
    METRICS_MAP = (
        MetricsMapping(Path("metrics/default.yaml")),
        MetricsMapping(Path("metrics/extra.yaml"), predicate=MyPredicate()),
    )

Customizing Defaults with get_default_config

get_default_config() is the hook for providing instance-level scraper defaults. File-based metrics are merged on top of whatever this method returns, so you can combine file metrics with other defaults such as rename_labels:

class MyCheck(OpenMetricsBaseCheckV2):
    def get_default_config(self) -> dict:
        return {
            "rename_labels": {"exported_job": "job"},
        }

The returned dict may be mutated by the framework before it is wrapped in a ChainMap. Return a fresh dict on every call. Returning a shared class-level or instance-level object can cause state leakage between check executions.

API Reference

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.MetricsMapping dataclass

Declares a single YAML file containing metric name mappings to load automatically.

Use in the METRICS_MAP class variable of OpenMetricsBaseCheckV2 subclasses. The path is relative to the package directory. An optional predicate controls whether the file is loaded for a given instance config; when omitted, the file is always loaded.

Example::

METRICS_MAP = (
    MetricsMapping(Path("metrics/default.yaml")),
    MetricsMapping(Path("metrics/go.yaml"), predicate=ConfigOptionTruthy("go_metrics")),
)

Parameters:

Name Type Description Default
path Path

Path to the YAML metrics file, relative to the package directory.

 required
predicate MetricsPredicate | None

Optional condition that gates loading. Defaults to always load.

 None
Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
@dataclass(frozen=True)
class MetricsMapping:
    """
    Declares a single YAML file containing metric name mappings to load automatically.

    Use in the ``METRICS_MAP`` class variable of ``OpenMetricsBaseCheckV2``
    subclasses. The path is relative to the package directory. An optional
    predicate controls whether the file is loaded for a given instance config;
    when omitted, the file is always loaded.

    Example::

        METRICS_MAP = (
            MetricsMapping(Path("metrics/default.yaml")),
            MetricsMapping(Path("metrics/go.yaml"), predicate=ConfigOptionTruthy("go_metrics")),
        )

    Args:
        path: Path to the YAML metrics file, relative to the package directory.
        predicate: Optional condition that gates loading. Defaults to always load.
    """

    path: Path
    predicate: MetricsPredicate | None = None

    def should_load(self, config: InstanceType) -> bool:
        """Return whether this mapping should be loaded for the given config."""
        return self.predicate is None or self.predicate.should_load(config)

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.MetricsPredicate

Protocol for conditional metrics loading.

Any class with a should_load(self, config) -> bool method satisfies this protocol and can be used as a predicate in MetricsMapping. No inheritance or registration is required.

Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
class MetricsPredicate(Protocol):
    """
    Protocol for conditional metrics loading.

    Any class with a ``should_load(self, config) -> bool`` method satisfies
    this protocol and can be used as a predicate in ``MetricsMapping``. No
    inheritance or registration is required.
    """

    def should_load(self, config: InstanceType) -> bool: ...

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.ConfigOptionTruthy

Load metrics when a config option is truthy; skip when it is falsy.

Uses is_affirmative to evaluate the option value. When the option is absent from the config, default is used (True by default, so metrics are included unless explicitly disabled).

Parameters:

Name Type Description Default
option str

The instance config key to evaluate.

 required
default bool

Fallback value when the option is not present.

 True
Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
class ConfigOptionTruthy:
    """
    Load metrics when a config option is truthy; skip when it is falsy.

    Uses ``is_affirmative`` to evaluate the option value. When the option is
    absent from the config, ``default`` is used (``True`` by default, so
    metrics are included unless explicitly disabled).

    Args:
        option: The instance config key to evaluate.
        default: Fallback value when the option is not present.
    """

    def __init__(self, option: str, default: bool = True) -> None:
        self.option = option
        self.default = default

    def should_load(self, config: InstanceType) -> bool:
        return is_affirmative(config.get(self.option, self.default))

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.ConfigOptionEquals

Load metrics when a config option equals a specific value; skip otherwise.

A missing key compares equal to None: ConfigOptionEquals("flag", None) matches both {"flag": None} and instances that omit the key entirely.

Parameters:

Name Type Description Default
option str

The instance config key to evaluate.

 required
value Any

The exact value the option must equal.

 required
Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
class ConfigOptionEquals:
    """
    Load metrics when a config option equals a specific value; skip otherwise.

    A missing key compares equal to ``None``: ``ConfigOptionEquals("flag", None)``
    matches both ``{"flag": None}`` and instances that omit the key entirely.

    Args:
        option: The instance config key to evaluate.
        value: The exact value the option must equal.
    """

    def __init__(self, option: str, value: Any) -> None:
        self.option = option
        self.value = value

    def should_load(self, config: InstanceType) -> bool:
        return config.get(self.option) == self.value

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.AllOf

Conjunction of predicates; all must pass for the metrics to be loaded.

Follows Python's all() semantics: returns True when given no predicates.

Parameters:

Name Type Description Default
predicates MetricsPredicate

One or more MetricsPredicate instances to evaluate.

 ()
Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
class AllOf:
    """
    Conjunction of predicates; all must pass for the metrics to be loaded.

    Follows Python's ``all()`` semantics: returns ``True`` when given no
    predicates.

    Args:
        predicates: One or more ``MetricsPredicate`` instances to evaluate.
    """

    def __init__(self, *predicates: MetricsPredicate) -> None:
        self.predicates = predicates

    def should_load(self, config: InstanceType) -> bool:
        return all(p.should_load(config) for p in self.predicates)

datadog_checks.base.checks.openmetrics.v2.metrics_mapping.AnyOf

Disjunction of predicates; any one passing is sufficient to load the metrics.

Follows Python's any() semantics: returns False when given no predicates.

Parameters:

Name Type Description Default
predicates MetricsPredicate

One or more MetricsPredicate instances to evaluate.

 ()
Source code in datadog_checks_base/datadog_checks/base/checks/openmetrics/v2/metrics_mapping.py 
class AnyOf:
    """
    Disjunction of predicates; any one passing is sufficient to load the metrics.

    Follows Python's ``any()`` semantics: returns ``False`` when given no
    predicates.

    Args:
        predicates: One or more ``MetricsPredicate`` instances to evaluate.
    """

    def __init__(self, *predicates: MetricsPredicate) -> None:
        self.predicates = predicates

    def should_load(self, config: InstanceType) -> bool:
        return any(p.should_load(config) for p in self.predicates)