Use hostnames in Prometheus instance labels

Set instance explicitly in a static target's labels, or derive it from discovery metadata with relabel_configs. Prometheus uses the target address as the default instance label only when relabeling has not supplied one.

Remove a port from an address

For IPv4 addresses or ordinary DNS names with a port:

relabel_configs:
  - source_labels: [__address__]
    regex: '([^:]+):\d+'
    target_label: instance
    replacement: '$1'

This changes 192.168.1.10:9100 into 192.168.1.10. It does not resolve that IP address into a hostname, and this regular expression does not handle bracketed IPv6 addresses. Preserve the port if several targets on the same host would otherwise become indistinguishable.

Copy a discovered hostname

For Kubernetes node discovery:

relabel_configs:
  - source_labels: [__meta_kubernetes_node_name]
    target_label: instance

Use this only in a discovery context that supplies the node-name metadata. Cloud discovery offers different metadata, such as an EC2 Name tag exposed as __meta_ec2_tag_Name; verify that the tag exists and is unique enough for the job.

Relabeling transforms available label values. It does not perform reverse DNS lookups. If you need a hostname that discovery does not supply, provide a mapping through static or file-based discovery.

Name a static target directly

scrape_configs:
  - job_name: node
    static_configs:
      - targets: ['10.0.0.1:9100']
        labels:
          instance: web-server-01

The scrape still connects to 10.0.0.1:9100. Only the identity label changes; editing instance does not change __address__.

Use target relabeling for target identity

relabel_configs runs before scraping and is the appropriate place to set the target's identity. metric_relabel_configs runs on scraped samples before ingestion. Do not use it merely to make the target's instance label readable, because target relabeling keeps that identity consistent with generated target metrics such as up.

FAQ

What happens to old data after a rename? The complete label set identifies a time series. A new instance value creates new series; earlier samples retain the old value. Plan dashboard selectors and comparisons across the change.

What does $1 mean? It inserts the first regular-expression capture group. With the port-stripping expression, that group contains the address before the colon.

Sources

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

• Prometheus relabeling configuration
• Prometheus jobs and instances