grpc-ecosystem / grpc-ecosystem/java-grpc-prometheus

Support constant/static labels in Configuration (similar to withLabelHeaders)

Open
#60 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Java
Stars
236
Forks
80
PR merge metrics
No merged PRs in 30d

Description

## Context

The library provides a convenient way to expose gRPC server metrics to Prometheus, including the ability to derive additional labels from request metadata headers via `Configuration.withLabelHeaders(...)`.

A related (and fairly common) requirement is to attach **static labels** at configuration time — e.g. `server_name`, `env`, etc. — so they are present on *all* metrics emitted by the interceptor.

## Current behavior

Request-scoped labels can be added from headers:

```java
import static me.dinowernli.grpc.prometheus.Configuration.allMetrics;

import io.grpc.ServerInterceptor;
import io.prometheus.client.CollectorRegistry;
import java.util.List;
import me.dinowernli.grpc.prometheus.Configuration;
import me.dinowernli.grpc.prometheus.MonitoringServerInterceptor;

CollectorRegistry registry = new CollectorRegistry();

Configuration cfg = allMetrics()
.withCollectorRegistry(registry)
.withLabelHeaders(List.of("x-tenant", "x-request-source"));

ServerInterceptor interceptor = MonitoringServerInterceptor.create(cfg);
```

However, labels that are **not request-derived** (service identity / deployment metadata) do not have an equivalent configuration hook in the library.

Prometheus relabeling is an option, but it may not be available in all environments (e.g. shared scrape config, limited access to Prometheus setup), and it’s often preferable when the service can fully describe its own metrics.

## Proposal

Add support for constant/static labels in `Configuration`, applied to all metrics created by this library.

Example API shape (naming is flexible):

```java
import java.util.Map;

Configuration cfg = allMetrics()
.withCollectorRegistry(registry)
.withConstantLabels(Map.of(
"server_name", "my-custom-server-name",
"env", "prod"
));
```

Potential names:
- `withConstantLabels(Map labels)`
- `withStaticLabels(...)`
- `withDefaultLabels(...)`

The key requirement is that these labels are always present, independent of request metadata.

## Why this could be useful

- **No dependency on Prometheus relabeling** (not always configurable by the service owner).
- **Clearer label semantics**: request-derived labels via `withLabelHeaders`, deployment/service identity via constant labels.
- **Predictable cardinality**: a fixed set of labels with fixed values.

Please let me know what you think! Thanks!

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.