---
title: "Labels reference | Database Observability documentation"
description: "Reference documentation for labels used in Database Observability metrics and logs, including required labels and best practices."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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.

Expand table

| Requirement  | Value                  |
|--------------|------------------------|
| **Required** | Yes                    |
| **Must be**  | `integrations/db-o11y` |
| **Where**    | Both metrics and logs  |

**Configuration:**

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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"
  }
}
```

> Warning
> 
> If `job` is not exactly `integrations/db-o11y`, the Database Observability dashboards cannot find your data.

### `instance`

The `instance` label uniquely identifies each database server.

Expand table

| Requirement    | Value                               |
|----------------|-------------------------------------|
| **Required**   | Yes                                 |
| **Format**     | `hostname:port`                     |
| **Must match** | Same value in both metrics and logs |

**Configuration:**

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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:**

Expand table

| Do                                          | Don’t                                         |
|---------------------------------------------|-----------------------------------------------|
| Use FQDN: `orders-db.prod.example.com:3306` | Use IP addresses (they can change)            |
| Include port: `mydb:5432`                   | Omit port: `mydb`                             |
| Be consistent across all databases          | Use different formats for different databases |

**For AWS RDS/Aurora:**

Use the instance endpoint, not the cluster endpoint:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// 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"
```

## System-managed labels

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

Expand table

| Label       | Description                                                                                                                                    |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `server_id` | Unique server identifier, used internally to associate telemetry                                                                               |
| `op`        | Operation type for log entries (`query_sample`, `query_association`, `wait_event`, `explain_plan_output`, `create_statement`, `health_status`) |

> Warning
> 
> Do not override `server_id` or `op` in relabel rules. Modifying these labels prevents Database Observability from querying and correlating your data.

## Database-specific labels

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

### PostgreSQL labels

Expand table

| Label     | Source               | Description             |
|-----------|----------------------|-------------------------|
| `datname` | `pg_stat_statements` | Database name           |
| `usename` | `pg_stat_statements` | User who executed query |
| `queryid` | `pg_stat_statements` | Unique query identifier |

### MySQL labels

Expand table

| Label    | Source               | Description                         |
|----------|----------------------|-------------------------------------|
| `schema` | `performance_schema` | Database schema name                |
| `digest` | `performance_schema` | Statement digest (query identifier) |
| `user`   | `performance_schema` | Database user                       |

## Recommended custom labels

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

Expand table

| Label         | Purpose                                  | Example values                        |
|---------------|------------------------------------------|---------------------------------------|
| `app`         | Application that uses the database       | `order-service`, `user-api`           |
| `team`        | Team responsible for the database        | `checkout`, `platform`                |
| `environment` | Deployment stage                         | `production`, `staging`, `dev`        |
| `region`      | Geographic region or data center         | `us-east-1`, `eu-west-1`              |
| `cluster`     | Database cluster (for replicated setups) | `orders-primary`, `orders-replica`    |
| `provider`    | Infrastructure provider                  | `aws`, `gcp`, `azure`, `self-managed` |

**Example:**

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

For complete configuration examples showing custom labels in context, refer to [Monitor multiple databases](/docs/grafana-cloud/monitor-applications/database-observability/configure/monitor-multiple-databases/).

## Environment variables

For dynamic labels, use environment variables:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

rule {
  target_label = "region"
  replacement  = sys.env("AWS_REGION")
}
```

## Label name and value restrictions

Expand table

| Restriction      | Details                                                            |
|------------------|--------------------------------------------------------------------|
| Name characters  | Letters, numbers, underscores. Must match `[a-zA-Z_][a-zA-Z0-9_]*` |
| Value characters | Any UTF-8 string                                                   |
| Case             | Case-sensitive; use lowercase for consistency                      |
| Empty            | Empty values are ignored                                           |

## Related documentation

- [Telemetry reference](/docs/grafana-cloud/monitor-applications/database-observability/reference/telemetry-reference/): Available metrics and logs
- [Monitor multiple databases](/docs/grafana-cloud/monitor-applications/database-observability/configure/monitor-multiple-databases/): Labeling strategies and configuration at scale
- [Tune Alloy collection](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/): Configure collection and manage cardinality
- [Troubleshoot Alloy components](/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/alloy/): Validate relabeling rules and diagnose label issues
- [View query performance](/docs/grafana-cloud/monitor-applications/database-observability/monitor/view-query-performance/): Use labels in dashboards