# What are Prometheus Labels?

# What are Prometheus labels?

Prometheus labels are key-value pairs used to add metadata to metrics, making them more descriptive and allowing flexible queries. They enable Prometheus to organize, filter, and aggregate metrics efficiently.

[ad-logs-small]

## Key characteristics of labels

1. **Key-value format**:
   Each label is a key paired with a value. Example: `status="200"`.

2. **Attached to metrics**:
   Labels provide context or dimensions to raw metrics. For instance, the metric `http_requests_total` can have labels like `method="GET"` or `endpoint="/api"`.

3. **Dynamic values**:
   Labels can represent dynamic attributes, such as instance names, environments, or HTTP status codes.

---

## Example of labels

Metric with labels:

```text
http_requests_total{method="GET", endpoint="/home", status="200"} 42
```

Breakdown:

- `http_requests_total`: The metric name.
- `{method="GET", endpoint="/home", status="200"}`: Labels that provide context.
- `42`: The metric value.

---

## Use cases for labels

1. **Filtering metrics**:
   Labels allow querying specific subsets of metrics.
   - Query: `http_requests_total{status="200"}` retrieves metrics for successful requests.

2. **Aggregating metrics**:
   Labels enable grouping or aggregating data.
   - Query: `sum(rate(http_requests_total[5m])) by (status)` calculates the rate of requests grouped by status.

3. **Adding context**:
   Labels provide metadata like instance, region, or version to distinguish metrics.

---

## Best practices for using labels

1. **Avoid high cardinality**:
   Labels with many unique values (like `user_id`) can lead to a large number of time series, increasing resource usage.

2. **Use meaningful keys**:
   Use descriptive and consistent keys such as `region`, `environment`, or `status`.

3. **Keep values short**:
   Avoid embedding long strings or logs as label values.


---

## Label pitfalls

1. **Unbounded values**:
   Dynamic values like UUIDs or timestamps can create infinite time series, overwhelming Prometheus.

2. **Query complexity**:
   Excessive labels can make PromQL queries difficult to construct and understand.

3. **Immutable labels**:
   Labels cannot be modified once a time series is created. Changes require creating a new time series.

---


Labels are essential for making Prometheus metrics flexible and insightful. When used effectively, they enable powerful filtering, aggregation, and monitoring capabilities. However, careful design is required to avoid performance issues.

[ad-uptime]