Documentation Grafana Cloud Monitor applications Database Observability Reference Labels

Labels reference

Labels identify and organize your database telemetry data. This reference documents all labels used by Database Observability, their requirements, and best practices.

Required labels

These labels must be configured correctly for Database Observability to function.

job

The job label identifies Database Observability telemetry.

Configuration:

Alloy Copy

loki.relabel "mydb" {
  forward_to = [loki.write.default.receiver]

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }
}

discovery.relabel "mydb" {
  targets = database_observability.postgres.mydb.targets

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }
}

instance

The instance label uniquely identifies each database server.

Configuration:

Alloy Copy

loki.relabel "mydb" {
  forward_to = [loki.write.default.receiver]

  rule {
    target_label = "instance"
    replacement  = "db.example.com:5432"
  }
}

discovery.relabel "mydb" {
  targets = database_observability.postgres.mydb.targets

  rule {
    target_label = "instance"
    replacement  = "db.example.com:5432"
  }
}

Best practices:

For AWS RDS/Aurora:

Use the instance endpoint, not the cluster endpoint:

Alloy Copy

// Correct - instance endpoint
instance = "mydb-instance.abcd1234.us-east-1.rds.amazonaws.com:5432"

// Incorrect - cluster endpoint (changes during failover)
instance = "mydb-cluster.cluster-abcd1234.us-east-1.rds.amazonaws.com:5432"

For Google Cloud SQL:

Use a consistent instance label value across metrics and logs. The instance IP address or hostname is typical:

Alloy Copy

// Correct - instance IP or hostname with port
instance = "10.0.0.5:5432"

// Also set connection_name in the cloud_provider block for infrastructure metrics
cloud_provider {
  gcp {
    connection_name = "my-project:us-central1:my-db"
  }
}

Refer to Set up Google Cloud SQL PostgreSQL or Set up Google Cloud SQL MySQL for Alloy configuration. For Cloud Provider Observability navigation, refer to Google Cloud Platform observability.

System-managed labels

These labels are set automatically by Alloy. Do not modify them.

Database-specific labels

These labels come from the database itself and are automatically added by exporters.

PostgreSQL labels

MySQL labels

Recommended custom labels

Add these labels in both loki.relabel and discovery.relabel to organize and filter databases. Values must match across both components.

Example:

Alloy Copy

rule {
  target_label = "app"
  replacement  = "order-service"
}

For complete configuration examples showing custom labels in context, refer to Monitor multiple databases.

Environment variables

For dynamic labels, use environment variables:

Alloy Copy

rule {
  target_label = "environment"
  replacement  = sys.env("DEPLOYMENT_ENV")
}

rule {
  target_label = "region"
  replacement  = sys.env("AWS_REGION")  // or sys.env("GCP_REGION") for Google Cloud
}

Label name and value restrictions

Related documentation

• Telemetry reference: Available metrics and logs
• Monitor multiple databases: Labeling strategies and configuration at scale
• Tune Alloy collection: Configure collection and manage cardinality
• Troubleshoot Alloy components: Validate relabeling rules and diagnose label issues
• View query performance: Use labels in dashboards