Add target-specific labels to a Prometheus scrape

Give a static target its own entry under static_configs, then put its labels in that entry's labels mapping. All targets in the same entry receive the same labels, so split entries whenever their label values differ.

Label static targets

scrape_configs:
  - job_name: node
    static_configs:
      - targets: ['10.0.0.1:9100']
        labels:
          datacenter: bj-01
          role: db
      - targets: ['10.0.0.2:9100']
        labels:
          datacenter: sh-01
          role: cache

Both targets share the job's scrape interval and other settings. Their samples carry different datacenter and role values.

Derive labels from service discovery

For a Kubernetes pod discovery configuration, available metadata can be copied into ordinary target labels:

relabel_configs:
  - source_labels: [__meta_kubernetes_namespace]
    target_label: namespace
  - source_labels: [__meta_kubernetes_pod_name]
    target_label: pod

Place this under the relevant scrape job. Metadata depends on the discovery role; a label available for pod discovery is not automatically available for every other role. Internal labels beginning with __ do not survive target relabeling unless you copy the values you need.

Keep label identities stable

Changing a label value creates a different time series. It does not rewrite earlier samples. Prefer useful, bounded dimensions such as environment or role; avoid timestamps and request IDs. Target addresses are a normal identity dimension, but adding unnecessary volatile labels creates more churn.

Use metric_relabel_configs for transformations on scraped samples before ingestion. It is not a way to repair already stored history.

FAQ

How do I add a label to every target in one job? Repeat it in each static group or use a constant target relabeling rule:

relabel_configs:
  - target_label: environment
    replacement: production

There is no general labels field directly under a scrape job. honor_labels controls conflicts; it does not create such a field.

What if the exporter already supplies the same label? With the default honor_labels: false, Prometheus preserves the target-side value and renames the conflicting scraped label with an exported_ prefix. With honor_labels: true, the scraped value wins. Choose this deliberately, especially for federation or Pushgateway scrapes.

Sources

This guide is based on the documentation below; the examples have not been tested against a live deployment.

• Prometheus configuration and relabeling