From c9e069ba9b3966aabf64441d8b96d1b133e9c9e5 Mon Sep 17 00:00:00 2001
From: "David Muto (pseudomuto)" <david.muto@gmail.com>
Date: Thu, 3 Sep 2026 09:55:48 -0400
Subject: [PATCH] [metrics]: Allow request metadata as Prometheus labels

Proxy metrics could only be sliced by dimensions the proxy itself knows: the
method, the upstream, the outcome. An operator running one proxy for several
tenants or clusters has no way to attribute traffic to them, because the thing
that identifies them travels in request metadata the collectors never see.

Add a metrics.tags list, written as "<header>:<label>", that carries an inbound
metadata value onto the metrics emitted while serving a request. The gateway's
own request metrics, the routing decision, and the vault operations all gain
the configured labels.

Things that aren't request based are is left as is. `crypto.Observer`,
for example, which has no request context, and has some logic in a
go routine with no request available at all.

Having 2 different headers mapping to the same label is a startup
(validation) error, since Prometheus would panic at runtime with two
values set for the same one. There's also some validation for the header
and label names to keep them inline with gRPC/Prometheus requirements
and ensure they're caught at startup and not at runtime. gRPC binary
metadata (ending in `-bin`) are not allowed.

Finally, gRPC metadata is a `map[string][]string` where each value is
the ordered set of values set for the key. In the case that multiple
values exist, the last value is used as the label.
---
 README.md                                     |   4 +-
 e2e/metric_tags_test.go                       | 129 +++++++
 internal/config/metrics.go                    | 188 ++++++++-
 internal/config/metrics_test.go               | 362 +++++++++++++++++-
 internal/dataplane/dataplane_test.go          |  16 +
 .../dataplane/dataplanetest/dataplanetest.go  |  19 +-
 internal/dataplane/reporters.go               |  16 +-
 internal/metrics/doc.go                       |   6 +
 internal/metrics/tags.go                      | 104 +++++
 internal/metrics/tags_test.go                 | 161 ++++++++
 internal/proxy/encryption.go                  |   4 +-
 internal/proxy/encryption_test.go             |  49 ++-
 internal/proxy/reporter.go                    |  25 +-
 internal/router/director.go                   |   6 +-
 internal/router/handler.go                    |   2 +-
 internal/router/handler_test.go               |  13 +-
 internal/router/reporter.go                   |  41 +-
 internal/router/reporter_test.go              |  64 +++-
 internal/server/reporter.go                   |  25 +-
 internal/server/reporter_test.go              |  82 +++-
 20 files changed, 1238 insertions(+), 78 deletions(-)
 create mode 100644 e2e/metric_tags_test.go
 create mode 100644 internal/metrics/tags.go
 create mode 100644 internal/metrics/tags_test.go

diff --git a/README.md b/README.md
index 115e888..7d4deb0 100644
--- a/README.md
+++ b/README.md
@@ -75,7 +75,9 @@ reaches a different upstream with no change to the Worker.
   (the gRPC method, and the Namespace the proxy resolved from the request rather than from anything the caller claims),
   so it can decide per Namespace and per method rather than only whether the caller is who it says it is.
 - **Prometheus metrics.** Expose request latency and counts, routing decisions, and encryption activity on `/metrics`.
-  The listen address and the namespace prefixed onto every metric are set under `metrics:` in the config.
+  The listen address and the namespace prefixed onto every metric are set under `metrics:` in the config, which can
+  also name request metadata to carry onto the request-scoped metrics as extra labels, so they can be sliced by a
+  dimension only your callers know.
 - **Codec-transparent.** The gateway never parses payloads. It peeks the Namespace, picks an upstream, and relays raw
   frames in both directions.
 - **Multiple deployment options.** Ship as a Go binary, a container image, or a Helm chart.
diff --git a/e2e/metric_tags_test.go b/e2e/metric_tags_test.go
new file mode 100644
index 0000000..19a7c9a
--- /dev/null
+++ b/e2e/metric_tags_test.go
@@ -0,0 +1,129 @@
+package e2e
+
+import (
+	"testing"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus/testutil"
+	"github.com/stretchr/testify/require"
+	"go.temporal.io/api/common/v1"
+	"go.temporal.io/api/query/v1"
+	"go.temporal.io/api/workflowservice/v1"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/metadata"
+
+	"github.com/temporalio/temporal-proxy/internal/config"
+	"github.com/temporalio/temporal-proxy/internal/dataplane/dataplanetest"
+)
+
+// TestEndToEndMetricTags drives a payload-carrying call through the full stack
+// with a metrics tag configured, and proves the caller's metadata reaches the
+// labels of every request-scoped collector.
+//
+// The vault_ops assertion is the one that matters: that collector lives on the
+// per-upstream hop, on the far side of a unix socket that context values do not
+// cross. It passes only because the value is read from the metadata the gateway
+// forwards, and it is what fails if this is ever reworked into a single
+// interceptor stashing values in a context.
+func TestEndToEndMetricTags(t *testing.T) {
+	t.Parallel()
+
+	up := dataplanetest.NewUpstream(t)
+
+	cfg := dataplanetest.Config(up)
+	// Mixed case on purpose: gRPC canonicalizes metadata keys, so a config
+	// written this way still has to match what arrives on the wire.
+	cfg.Metrics.Tags = []config.MetricTag{{Header: "X-Tenant", Label: "tenant"}}
+	// Encryption is what makes the per-upstream hop emit vault_ops at all.
+	cfg.Encryption = config.Encryption{
+		Enabled: true,
+		Default: &config.KeyPolicy{URI: testingKeyURI(t), Duration: time.Hour},
+	}
+
+	f := dataplanetest.StartApp(t, cfg)
+
+	ctx := metadata.AppendToOutgoingContext(f.Context(), "x-tenant", "acme")
+	_, err := f.Client().QueryWorkflow(ctx, queryWithPayload(), grpc.WaitForReady(true))
+	require.NoError(t, err)
+
+	// Hop 1: the gateway's own interceptor and the routing decision.
+	requireLabel(t, f, "test_server_requests_total", "tenant", "acme")
+	requireLabel(t, f, "test_router_decisions_total", "tenant", "acme")
+
+	// Hop 2: across the socket.
+	requireLabel(t, f, "test_encryption_vault_ops_total", "tenant", "acme")
+}
+
+// TestEndToEndMetricTagsWithoutTheHeader proves a configured label is always
+// present, empty when the caller sent nothing, rather than the series being
+// reported without it.
+func TestEndToEndMetricTagsWithoutTheHeader(t *testing.T) {
+	t.Parallel()
+
+	up := dataplanetest.NewUpstream(t)
+
+	cfg := dataplanetest.Config(up)
+	cfg.Metrics.Tags = []config.MetricTag{{Header: "x-tenant", Label: "tenant"}}
+	cfg.Encryption = config.Encryption{
+		Enabled: true,
+		Default: &config.KeyPolicy{URI: testingKeyURI(t), Duration: time.Hour},
+	}
+
+	f := dataplanetest.StartApp(t, cfg)
+
+	_, err := f.Client().QueryWorkflow(f.Context(), queryWithPayload(), grpc.WaitForReady(true))
+	require.NoError(t, err)
+
+	requireLabel(t, f, "test_server_requests_total", "tenant", "")
+	requireLabel(t, f, "test_router_decisions_total", "tenant", "")
+	requireLabel(t, f, "test_encryption_vault_ops_total", "tenant", "")
+}
+
+// queryWithPayload is a QueryWorkflow request carrying one payload, so the
+// encryption interceptor on the per-upstream hop has something to seal.
+func queryWithPayload() *workflowservice.QueryWorkflowRequest {
+	return &workflowservice.QueryWorkflowRequest{
+		Namespace: "ns1",
+		Execution: &common.WorkflowExecution{WorkflowId: "wf-1"},
+		Query: &query.WorkflowQuery{
+			QueryType: "state",
+			QueryArgs: &common.Payloads{Payloads: []*common.Payload{{
+				Metadata: map[string][]byte{wireEncoding: []byte("json/plain")},
+				Data:     []byte(`"hi"`),
+			}}},
+		},
+	}
+}
+
+// requireLabel asserts that some series in the named metric family carries
+// label=want. It compares against the gathered registry rather than a scrape,
+// which is equivalent: the metrics module hands that same Gatherer to its
+// /metrics handler.
+func requireLabel(t *testing.T, f *dataplanetest.Fixture, family, label, want string) {
+	t.Helper()
+
+	found, err := testutil.GatherAndLint(f.Gatherer(), family)
+	require.NoError(t, err)
+	require.Empty(t, found, "collector %s failed prometheus linting", family)
+
+	mfs, err := f.Gatherer().Gather()
+	require.NoError(t, err)
+
+	for _, mf := range mfs {
+		if mf.GetName() != family {
+			continue
+		}
+
+		for _, m := range mf.GetMetric() {
+			for _, lp := range m.GetLabel() {
+				if lp.GetName() == label && lp.GetValue() == want {
+					return
+				}
+			}
+		}
+
+		t.Fatalf("metric family %s has no series with %s=%q, got %v", family, label, want, mf.GetMetric())
+	}
+
+	t.Fatalf("metric family %s was never registered", family)
+}
diff --git a/internal/config/metrics.go b/internal/config/metrics.go
index 99b1e58..d95d2f3 100644
--- a/internal/config/metrics.go
+++ b/internal/config/metrics.go
@@ -1,23 +1,189 @@
 package config
 
-import "github.com/temporalio/temporal-proxy/pkg/validation"
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"slices"
+	"strings"
 
-// Metrics configures the Prometheus endpoint. HostPort is the address the
-// /metrics handler listens on, and Namespace is the prefix stamped onto every
-// collector: a Prometheus namespace, unrelated to a Temporal namespace. Load
-// defaults both, so neither is empty in a loaded config.
-type Metrics struct {
-	HostPort  string `yaml:"hostPort"`
-	Namespace string `yaml:"namespace"`
+	"github.com/temporalio/temporal-proxy/pkg/validation"
+)
+
+const (
+	binaryHeaderSuffix   = "-bin"  // gRPC binary metadata marker
+	reservedHeaderPrefix = "grpc-" // gRPC reserved metadata prefix
+	reservedLabelPrefix  = "__"    // Prometheus reserved label prefix
+)
+
+var (
+	// promReservedLabels are the label names Prometheus keeps for a histogram's
+	// bucket bound and a summary's quantile.
+	promReservedLabels = []string{"le", "quantile"}
+
+	// mdKeyRegex matches the characters gRPC allows in a metadata key.
+	mdKeyRegex = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
+
+	// promLabelRegex matches the Prometheus label name grammar.
+	promLabelRegex = regexp.MustCompile(`^[a-zA-Z_][a-zA-Z0-9_]*$`)
+)
+
+type (
+	// Metrics configures the Prometheus endpoint. HostPort is the address the
+	// /metrics handler listens on, and Namespace is the prefix stamped onto every
+	// collector: a Prometheus namespace, unrelated to a Temporal namespace. Tags
+	// name the request metadata to carry through as labels. Load defaults
+	// HostPort and Namespace, so neither is empty in a loaded config.
+	Metrics struct {
+		HostPort  string      `yaml:"hostPort"`
+		Namespace string      `yaml:"namespace"`
+		Tags      []MetricTag `yaml:"tags"`
+	}
+
+	// MetricTag pairs an inbound request metadata Header with the Prometheus
+	// Label it is reported under. It is written in YAML as "<header>:<label>".
+	//
+	// Choose the Header with care. Its value is published on the /metrics
+	// endpoint, which is served unauthenticated, so naming a header that carries
+	// a credential exposes that credential to anything able to reach the port.
+	// A tag also multiplies every request-scoped series rather than adding to
+	// them, so a header the caller varies freely multiplies cardinality with it.
+	MetricTag struct {
+		Header string
+		Label  string
+	}
+)
+
+// ParseMetricTag parses the "<header>:<label>" form, trimming whitespace around
+// each half. It splits on the first colon, so a label containing one survives
+// parsing and is rejected by Validate instead.
+func ParseMetricTag(v string) (MetricTag, error) {
+	tag := MetricTag{}
+	hdr, lbl, ok := strings.Cut(v, ":")
+	if !ok {
+		return tag, errors.New("invalid metric tag: format: <header>:<label>")
+	}
+
+	tag.Header = strings.TrimSpace(hdr)
+	tag.Label = strings.TrimSpace(lbl)
+	return tag, nil
 }
 
-// Validate requires a valid host:port and a non-empty namespace. Load defaults
-// both, so a namespace failure is only reachable for a Metrics built directly,
-// and a hostPort failure only for a config that sets one that will not parse.
+// Validate requires a valid host:port and a non-empty namespace, and checks
+// every tag. Load defaults the first two, so a namespace failure is only
+// reachable for a Metrics built directly, and a hostPort failure only for a
+// config that sets one that will not parse. Two tags may not share a label,
+// which Prometheus rejects as a duplicate label name.
 func (m *Metrics) Validate() error {
+	labels := make([]string, len(m.Tags))
+	for i, t := range m.Tags {
+		labels[i] = t.Label
+	}
+
 	return validation.Validate(
 		"",
 		validation.Field("hostPort", m.HostPort, validation.IsHostPort()),
 		validation.Field("namespace", m.Namespace, validation.Required[string]()),
+		validation.Field("tags[label]", labels, validation.Unique[string]()),
+		validation.Children("tags", m.Tags, func(t *MetricTag) error { return t.Validate() }),
 	)
 }
+
+// UnmarshalYAML decodes the scalar "<header>:<label>" form, so a tag is written
+// as a plain YAML string rather than a mapping.
+func (t *MetricTag) UnmarshalYAML(unmarshal func(any) error) error {
+	var decoded string
+	if err := unmarshal(&decoded); err != nil {
+		return err
+	}
+
+	tag, err := ParseMetricTag(decoded)
+	if err != nil {
+		return err
+	}
+
+	*t = tag
+	return nil
+}
+
+// Validate requires a header that is a legal, unreserved, non-binary gRPC
+// metadata key and a label that is a legal, unreserved Prometheus label name.
+func (t *MetricTag) Validate() error {
+	return validation.Validate(
+		"",
+		validation.Field(
+			"header",
+			t.Header,
+			validation.Required[string](),
+			match(mdKeyRegex),
+			unreservedHeader(),
+			textualHeader(),
+		),
+		validation.Field(
+			"label",
+			t.Label,
+			validation.Required[string](),
+			match(promLabelRegex),
+			unreservedLabel(),
+		),
+	)
+}
+
+// match rejects a value that does not match r. An empty value yields nothing so
+// the Required check on the same field owns that case and reports it once.
+func match(r *regexp.Regexp) validation.Check[string] {
+	return func(s string) error {
+		if s == "" || r.MatchString(s) {
+			return nil
+		}
+
+		return fmt.Errorf("is not valid, must match: %q", r.String())
+	}
+}
+
+// textualHeader rejects a metadata key ending in "-bin". gRPC uses that suffix
+// to mark a value as binary, and binary is not valid UTF-8, so such a value
+// cannot be reported as a Prometheus label. The comparison is case-insensitive
+// because metadata keys are.
+func textualHeader() validation.Check[string] {
+	return func(s string) error {
+		if strings.HasSuffix(strings.ToLower(s), binaryHeaderSuffix) {
+			return fmt.Errorf("must not end with %q, which gRPC uses to mark binary metadata", binaryHeaderSuffix)
+		}
+
+		return nil
+	}
+}
+
+// unreservedHeader rejects a metadata key beginning with "grpc-", which gRPC
+// keeps for itself. The comparison is case-insensitive because metadata keys
+// are, so "GRPC-Status" is rejected alongside "grpc-status".
+func unreservedHeader() validation.Check[string] {
+	return func(s string) error {
+		if strings.HasPrefix(strings.ToLower(s), reservedHeaderPrefix) {
+			return fmt.Errorf("must not begin with %q, which gRPC reserves", reservedHeaderPrefix)
+		}
+
+		return nil
+	}
+}
+
+// unreservedLabel rejects a label name Prometheus keeps for itself: one
+// beginning with "__", which it refuses to register, and "le" or "quantile",
+// which name a histogram's bucket bound and a summary's quantile. The reserved
+// names are refused here because a histogram panics on "le" only when it first
+// instantiates a series, which happens while serving a request rather than at
+// construction, so nothing downstream would catch it.
+func unreservedLabel() validation.Check[string] {
+	return func(s string) error {
+		if strings.HasPrefix(s, reservedLabelPrefix) {
+			return fmt.Errorf("must not begin with %q, which Prometheus reserves", reservedLabelPrefix)
+		}
+
+		if slices.Contains(promReservedLabels, s) {
+			return fmt.Errorf("must not be %q, which Prometheus reserves", s)
+		}
+
+		return nil
+	}
+}
diff --git a/internal/config/metrics_test.go b/internal/config/metrics_test.go
index 0168cef..609ede3 100644
--- a/internal/config/metrics_test.go
+++ b/internal/config/metrics_test.go
@@ -18,7 +18,94 @@ func TestMetrics_Validate(t *testing.T) {
 		name     string
 		cfg      *config.Metrics
 		wantErrs []validation.Error
-	}{}
+	}{
+		{
+			name: "port-only hostPort and a namespace",
+			cfg:  &config.Metrics{HostPort: ":9090", Namespace: "tmprl_proxy"},
+		},
+		{
+			name: "host and port",
+			cfg:  &config.Metrics{HostPort: "127.0.0.1:9090", Namespace: "tmprl_proxy"},
+		},
+		{
+			name: "hostPort without a port",
+			cfg:  &config.Metrics{HostPort: "localhost", Namespace: "tmprl_proxy"},
+			wantErrs: []validation.Error{
+				{Field: "hostPort", Message: "is not a valid host:port"},
+			},
+		},
+		{
+			name: "missing namespace",
+			cfg:  &config.Metrics{HostPort: ":9090"},
+			wantErrs: []validation.Error{
+				{Field: "namespace", Message: "is required"},
+			},
+		},
+		{
+			// The zero value only reaches Validate when a Metrics is built
+			// directly; Load defaults both fields before anything sees it.
+			name: "zero value fails on both fields",
+			cfg:  &config.Metrics{},
+			wantErrs: []validation.Error{
+				{Field: "hostPort", Message: "is not a valid host:port"},
+				{Field: "namespace", Message: "is required"},
+			},
+		},
+		{
+			name: "distinct tags",
+			cfg: &config.Metrics{
+				HostPort:  ":9090",
+				Namespace: "tmprl_proxy",
+				Tags: []config.MetricTag{
+					{Header: "x-tenant", Label: "tenant"},
+					{Header: "x-region", Label: "region"},
+				},
+			},
+		},
+		{
+			// Prometheus refuses to register a collector with a duplicate label
+			// name, so two headers may not share one label.
+			name: "two tags sharing a label",
+			cfg: &config.Metrics{
+				HostPort:  ":9090",
+				Namespace: "tmprl_proxy",
+				Tags: []config.MetricTag{
+					{Header: "x-a", Label: "dup"},
+					{Header: "x-b", Label: "dup"},
+				},
+			},
+			wantErrs: []validation.Error{
+				{Field: "tags[label]", Message: "contains duplicate value: dup"},
+			},
+		},
+		{
+			name: "the same header twice under different labels is allowed",
+			cfg: &config.Metrics{
+				HostPort:  ":9090",
+				Namespace: "tmprl_proxy",
+				Tags: []config.MetricTag{
+					{Header: "x-a", Label: "one"},
+					{Header: "x-a", Label: "two"},
+				},
+			},
+		},
+		{
+			name: "a broken tag carries its index as the subject",
+			cfg: &config.Metrics{
+				HostPort:  ":9090",
+				Namespace: "tmprl_proxy",
+				Tags: []config.MetricTag{
+					{Header: "x-ok", Label: "ok"},
+					{Header: "x-bad", Label: "not a label"},
+				},
+			},
+			wantErrs: []validation.Error{{
+				Subject: "tags[1]",
+				Field:   "label",
+				Message: `is not valid, must match: "^[a-zA-Z_][a-zA-Z0-9_]*$"`,
+			}},
+		},
+	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -84,3 +171,276 @@ func TestLoad_MetricsDefaults(t *testing.T) {
 		})
 	}
 }
+
+func TestParseMetricTag(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		in      string
+		want    config.MetricTag
+		wantErr bool
+	}{
+		{
+			name: "header and label",
+			in:   "x-tenant:tenant",
+			want: config.MetricTag{Header: "x-tenant", Label: "tenant"},
+		},
+		{
+			name: "whitespace around each half is trimmed",
+			in:   "  x-tenant : tenant  ",
+			want: config.MetricTag{Header: "x-tenant", Label: "tenant"},
+		},
+		{
+			// Cut splits on the first colon, so the rest lands in the label and
+			// is rejected by Validate rather than here.
+			name: "splits on the first colon only",
+			in:   "x-h:a:b",
+			want: config.MetricTag{Header: "x-h", Label: "a:b"},
+		},
+		{
+			// Parsing accepts an empty half; Validate is what requires both.
+			name: "empty header",
+			in:   ":tenant",
+			want: config.MetricTag{Label: "tenant"},
+		},
+		{
+			name: "empty label",
+			in:   "x-tenant:",
+			want: config.MetricTag{Header: "x-tenant"},
+		},
+		{
+			name:    "no colon",
+			in:      "x-tenant",
+			wantErr: true,
+		},
+		{
+			name:    "empty string",
+			in:      "",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := config.ParseMetricTag(tt.in)
+			if tt.wantErr {
+				require.ErrorContains(t, err, "invalid metric tag")
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestMetricTag_Validate(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		tag      config.MetricTag
+		wantErrs []validation.Error
+	}{
+		{
+			name: "a metadata key and a label name",
+			tag:  config.MetricTag{Header: "x-tenant", Label: "tenant"},
+		},
+		{
+			name: "dots, dashes, and mixed case in the header",
+			tag:  config.MetricTag{Header: "X-Acme.Tenant-ID", Label: "tenant"},
+		},
+		{
+			name: "a single leading underscore is a legal label",
+			tag:  config.MetricTag{Header: "x-h", Label: "_tenant"},
+		},
+		{
+			// Reported once: match yields nothing for an empty value so the
+			// Required check on the same field owns that case.
+			name: "empty header reports only that it is required",
+			tag:  config.MetricTag{Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: "is required"},
+			},
+		},
+		{
+			name: "empty label reports only that it is required",
+			tag:  config.MetricTag{Header: "x-tenant"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: "is required"},
+			},
+		},
+		{
+			name: "a space is not legal in a metadata key",
+			tag:  config.MetricTag{Header: "bad header", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `is not valid, must match: "^[a-zA-Z0-9._-]+$"`},
+			},
+		},
+		{
+			name: "a dash is not legal in a label name",
+			tag:  config.MetricTag{Header: "x-h", Label: "not-a-label"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `is not valid, must match: "^[a-zA-Z_][a-zA-Z0-9_]*$"`},
+			},
+		},
+		{
+			name: "a label may not start with a digit",
+			tag:  config.MetricTag{Header: "x-h", Label: "1tenant"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `is not valid, must match: "^[a-zA-Z_][a-zA-Z0-9_]*$"`},
+			},
+		},
+		{
+			// gRPC reserves the "grpc-" prefix for its own metadata.
+			name: "a reserved header",
+			tag:  config.MetricTag{Header: "grpc-status", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `must not begin with "grpc-", which gRPC reserves`},
+			},
+		},
+		{
+			// Metadata keys are case-insensitive, so the prefix check must be
+			// too or this spelling would slip through.
+			name: "a reserved header in mixed case",
+			tag:  config.MetricTag{Header: "GRPC-Status", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `must not begin with "grpc-", which gRPC reserves`},
+			},
+		},
+		{
+			name: "only the prefix is reserved, not the substring",
+			tag:  config.MetricTag{Header: "x-grpc-tenant", Label: "tenant"},
+		},
+		{
+			name: "a header merely starting with grpc is allowed",
+			tag:  config.MetricTag{Header: "grpcfoo", Label: "tenant"},
+		},
+		{
+			// gRPC marks a binary value with the "-bin" suffix, and binary is
+			// not valid UTF-8, so it cannot be a label value.
+			name: "a binary metadata key",
+			tag:  config.MetricTag{Header: "x-trace-bin", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `must not end with "-bin", which gRPC uses to mark binary metadata`},
+			},
+		},
+		{
+			name: "a binary metadata key in mixed case",
+			tag:  config.MetricTag{Header: "X-Trace-BIN", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `must not end with "-bin", which gRPC uses to mark binary metadata`},
+			},
+		},
+		{
+			name: "only the suffix is binary, not the substring",
+			tag:  config.MetricTag{Header: "x-robin", Label: "tenant"},
+		},
+		{
+			// Two independent problems, so unlike an empty value this is
+			// reported twice rather than once.
+			name: "reserved and binary aggregate on one header",
+			tag:  config.MetricTag{Header: "grpc-trace-bin", Label: "tenant"},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: `must not begin with "grpc-", which gRPC reserves`},
+				{Field: "header", Message: `must not end with "-bin", which gRPC uses to mark binary metadata`},
+			},
+		},
+		{
+			// Prometheus reserves the "__" prefix and refuses to register a
+			// collector using one, so it fails here rather than at runtime.
+			name: "a reserved label name",
+			tag:  config.MetricTag{Header: "x-h", Label: "__name__"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `must not begin with "__", which Prometheus reserves`},
+			},
+		},
+		{
+			// A histogram panics on "le" when it first instantiates a series,
+			// which is while serving a request, so config has to refuse it.
+			name: "a label named le",
+			tag:  config.MetricTag{Header: "x-h", Label: "le"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `must not be "le", which Prometheus reserves`},
+			},
+		},
+		{
+			name: "a label named quantile",
+			tag:  config.MetricTag{Header: "x-h", Label: "quantile"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `must not be "quantile", which Prometheus reserves`},
+			},
+		},
+		{
+			name: "a label merely containing a reserved name is allowed",
+			tag:  config.MetricTag{Header: "x-h", Label: "sample_quantile"},
+		},
+		{
+			name: "a bare reserved prefix",
+			tag:  config.MetricTag{Header: "x-h", Label: "__"},
+			wantErrs: []validation.Error{
+				{Field: "label", Message: `must not begin with "__", which Prometheus reserves`},
+			},
+		},
+		{
+			name: "failures on both halves aggregate",
+			tag:  config.MetricTag{},
+			wantErrs: []validation.Error{
+				{Field: "header", Message: "is required"},
+				{Field: "label", Message: "is required"},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := tt.tag.Validate()
+			if len(tt.wantErrs) == 0 {
+				require.NoError(t, err)
+				return
+			}
+
+			var errs validation.Errors
+			require.True(t, errors.As(err, &errs), "expected validation.Errors, got %T", err)
+			require.ElementsMatch(t, tt.wantErrs, []validation.Error(errs))
+		})
+	}
+}
+
+func TestLoad_MetricTags(t *testing.T) {
+	t.Parallel()
+
+	t.Run("scalar tags decode into header and label", func(t *testing.T) {
+		t.Parallel()
+
+		got, err := config.Load(strings.NewReader(
+			"metrics:\n  tags:\n    - \"x-tenant:tenant\"\n    - \" x-Region : region \"\n",
+		))
+		require.NoError(t, err)
+		require.Equal(t, []config.MetricTag{
+			{Header: "x-tenant", Label: "tenant"},
+			{Header: "x-Region", Label: "region"},
+		}, got.Metrics.Tags)
+	})
+
+	t.Run("an absent tags key leaves no tags", func(t *testing.T) {
+		t.Parallel()
+
+		got, err := config.Load(strings.NewReader("metrics:\n  namespace: acme\n"))
+		require.NoError(t, err)
+		require.Empty(t, got.Metrics.Tags)
+	})
+
+	t.Run("a tag missing its colon fails the load", func(t *testing.T) {
+		t.Parallel()
+
+		// The unmarshaler rejects it, so this never reaches Validate.
+		_, err := config.Load(strings.NewReader("metrics:\n  tags:\n    - nocolon\n"))
+		require.ErrorContains(t, err, "invalid metric tag")
+	})
+}
diff --git a/internal/dataplane/dataplane_test.go b/internal/dataplane/dataplane_test.go
index 58b6b45..eb53307 100644
--- a/internal/dataplane/dataplane_test.go
+++ b/internal/dataplane/dataplane_test.go
@@ -141,6 +141,22 @@ func TestNewRejectsConfiguredKeysWithoutVault(t *testing.T) {
 		})
 	}
 }
+
+func TestNewRejectsATagLabelCollidingWithACollectorsOwn(t *testing.T) {
+	t.Parallel()
+
+	// A tag claiming a label a collector already declares makes the Desc
+	// invalid, so registration panics. That is caught in the same place a
+	// duplicate registration is, and the message has to name this cause too:
+	// config cannot check it without knowing every collector's label set.
+	cfg := testConfig()
+	cfg.Metrics.Tags = []config.MetricTag{{Header: "x-method", Label: "method"}}
+
+	deps := newTestDeps(t, cfg)
+	_, err := dataplane.New(deps.ctx, deps.cfg, deps.opts()...)
+	require.ErrorContains(t, err, "metrics tag label colliding with a collector's own")
+}
+
 func TestNewTwiceOverOneMetricsFactoryDoesNotPanic(t *testing.T) {
 	t.Parallel()
 
diff --git a/internal/dataplane/dataplanetest/dataplanetest.go b/internal/dataplane/dataplanetest/dataplanetest.go
index 792f2ab..7025b0d 100644
--- a/internal/dataplane/dataplanetest/dataplanetest.go
+++ b/internal/dataplane/dataplanetest/dataplanetest.go
@@ -48,6 +48,7 @@ type Fixture struct {
 	t    *testing.T
 	dp   *dataplane.Dataplane
 	conn *grpc.ClientConn
+	reg  prometheus.Gatherer
 }
 
 // Config returns a minimal valid configuration: an ephemeral gateway port and
@@ -107,11 +108,13 @@ func Start(t *testing.T, cfg *config.Config) *Fixture {
 	pool := connect.NewPool()
 	t.Cleanup(func() { _ = pool.Close() })
 
+	reg := prometheus.NewRegistry()
+
 	dp, err := dataplane.New(t.Context(), cfg,
 		dataplane.WithExtractor(protoutil.NewExtractor(protoregistry.GlobalFiles, protoregistry.GlobalTypes)),
 		dataplane.WithTranslator(protoutil.NewTranslator(protoregistry.GlobalFiles)),
 		dataplane.WithPool(pool),
-		dataplane.WithMetrics(metrics.New("test", promauto.With(prometheus.NewRegistry()))),
+		dataplane.WithMetrics(metrics.New("test", promauto.With(reg))),
 		dataplane.WithAllowlist(config.NewAllowlist(cfg)),
 		dataplane.WithAuth(auth.AdmitAll()),
 		dataplane.WithLogger(logger.NewNoopLogger()),
@@ -127,7 +130,7 @@ func Start(t *testing.T, cfg *config.Config) *Fixture {
 	// cleanups run, and a shutdown must not inherit that.
 	t.Cleanup(func() { requireCleanStop(t, dp.Stop(stopContext(t))) })
 
-	return newFixture(t, dp)
+	return newFixture(t, dp, reg)
 }
 
 // StartApp assembles and starts the whole production module graph around cfg,
@@ -180,9 +183,15 @@ func StartApp(t *testing.T, cfg *config.Config) *Fixture {
 		requireCleanStop(t, app.Stop(stopCtx))
 	})
 
-	return newFixture(t, dp)
+	return newFixture(t, dp, reg)
 }
 
+// Gatherer is the registry every collector in this plane registered with, and
+// the one its /metrics handler serves. A test asserts against it directly
+// because [applyDefaults] binds that handler to an ephemeral port nothing
+// reports.
+func (f *Fixture) Gatherer() prometheus.Gatherer { return f.reg }
+
 // Addr is the address the gateway is accepting on.
 func (f *Fixture) Addr() string { return f.dp.Addr().String() }
 
@@ -242,7 +251,7 @@ func applyDefaults(cfg *config.Config) {
 
 // newFixture dials the running gateway. gRPC connects lazily, so this opens
 // nothing until the first request.
-func newFixture(t *testing.T, dp *dataplane.Dataplane) *Fixture {
+func newFixture(t *testing.T, dp *dataplane.Dataplane, reg prometheus.Gatherer) *Fixture {
 	t.Helper()
 
 	require.NotNil(t, dp.Addr(), "the gateway must be accepting once Start returns")
@@ -251,7 +260,7 @@ func newFixture(t *testing.T, dp *dataplane.Dataplane) *Fixture {
 	require.NoError(t, err)
 	t.Cleanup(func() { _ = conn.Close() })
 
-	return &Fixture{t: t, dp: dp, conn: conn}
+	return &Fixture{t: t, dp: dp, conn: conn, reg: reg}
 }
 
 // stopContext returns a context for shutdown that does not inherit the test's
diff --git a/internal/dataplane/reporters.go b/internal/dataplane/reporters.go
index fc9970d..d6b6b99 100644
--- a/internal/dataplane/reporters.go
+++ b/internal/dataplane/reporters.go
@@ -32,14 +32,15 @@ func newReporters(f *metrics.Factory, c *config.Config, encryption bool) (r *rep
 		// MustRegister panics with the error Register returned, so wrap it and
 		// leave the caller an [prometheus.AlreadyRegisteredError] to match on.
 		// Any other panic value can only be reported as it arrived, and names a
-		// cause other than the one guessed at below.
+		// cause other than the ones guessed at below.
 		cause, ok := rec.(error)
 		if !ok {
 			cause = errors.New(fmt.Sprint(rec))
 		}
 
 		r, err = nil, fmt.Errorf(
-			"dataplane: registering metrics panicked, is another dataplane using this registry: %w", cause,
+			"dataplane: registering metrics panicked, is another dataplane using this "+
+				"registry, or a configured metrics tag label colliding with a collector's own: %w", cause,
 		)
 	}()
 
@@ -48,13 +49,18 @@ func newReporters(f *metrics.Factory, c *config.Config, encryption bool) (r *rep
 		names = append(names, c.Upstreams[i].Name)
 	}
 
+	// Only the request-scoped reporters take the tags; internal/kms builds its
+	// own from the same factory and emits off a request, where no metadata is in
+	// scope to read them from.
+	tags := metrics.NewTags(c.Metrics.Tags)
+
 	out := &reporters{
-		router: router.NewReporter(f.ForSubsystem("router"), names),
-		server: server.NewReporter(f.ForSubsystem("server")),
+		router: router.NewReporter(f.ForSubsystem("router"), names, tags),
+		server: server.NewReporter(f.ForSubsystem("server"), tags),
 	}
 
 	if encryption {
-		out.encryption = proxy.NewReporter(f.ForSubsystem("encryption"))
+		out.encryption = proxy.NewReporter(f.ForSubsystem("encryption"), tags)
 	}
 
 	return out, nil
diff --git a/internal/metrics/doc.go b/internal/metrics/doc.go
index 0249bb8..1201f0a 100644
--- a/internal/metrics/doc.go
+++ b/internal/metrics/doc.go
@@ -3,4 +3,10 @@
 // serves that registry at /metrics over HTTP, binding the server to the fx
 // application lifecycle. Consumers inject the [Factory], optionally scoping it
 // to a subsystem with [Factory.ForSubsystem], to declare their collectors.
+//
+// A reporter emitting while a request is in flight also takes a [Tags], built
+// from the configured header-to-label pairs, and carries those labels on its
+// collectors. Values are read from the request's incoming metadata at each emit
+// rather than resolved once and carried along, because the proxy forwards over a
+// socket that context values do not cross while metadata does.
 package metrics
diff --git a/internal/metrics/tags.go b/internal/metrics/tags.go
new file mode 100644
index 0000000..6eeaed3
--- /dev/null
+++ b/internal/metrics/tags.go
@@ -0,0 +1,104 @@
+package metrics
+
+import (
+	"context"
+	"slices"
+	"strings"
+	"unicode/utf8"
+
+	"google.golang.org/grpc/metadata"
+
+	"github.com/temporalio/temporal-proxy/internal/config"
+)
+
+// maxTagValueLen bounds a tag's label value in bytes. The value is supplied by
+// the caller and the registry never evicts a series, so an unbounded one is a
+// memory-growth vector.
+const maxTagValueLen = 256
+
+// Tags is the ordered set of inbound metadata headers reported as extra labels
+// on request-scoped collectors. The zero Tags carries none, which is what a
+// deployment that configures no tags runs, so a reporter holding one keeps its
+// label set and its emit path exactly as they were.
+type Tags struct {
+	labels  []string // Prometheus label names, in configured order.
+	headers []string // Lowercased metadata keys, parallel to labels.
+}
+
+// NewTags builds the ordered Tags for cfg. Headers are lowercased here because
+// gRPC canonicalizes metadata keys while a config preserves whatever case its
+// author wrote; labels keep their case, which Prometheus distinguishes.
+func NewTags(cfg []config.MetricTag) Tags {
+	if len(cfg) == 0 {
+		return Tags{}
+	}
+
+	t := Tags{
+		labels:  make([]string, len(cfg)),
+		headers: make([]string, len(cfg)),
+	}
+
+	for i, tag := range cfg {
+		t.labels[i] = tag.Label
+		t.headers[i] = strings.ToLower(tag.Header)
+	}
+
+	return t
+}
+
+// Len is the number of extra labels, and zero for a Tags carrying none.
+func (t Tags) Len() int { return len(t.labels) }
+
+// Labels returns the extra label names in configured order, for appending to a
+// collector's own label names at construction. The result is a copy.
+func (t Tags) Labels() []string { return slices.Clone(t.labels) }
+
+// AppendValues appends this request's tag values to dst in [Tags.Labels] order
+// and returns the extended slice, so a caller resolves them once and appends
+// them to more than one label list. It returns dst untouched when no tags are
+// configured, without reading ctx.
+func (t Tags) AppendValues(ctx context.Context, dst []string) []string {
+	if len(t.headers) == 0 {
+		return dst
+	}
+
+	// A context with no incoming metadata yields a nil MD, and Get on that is a
+	// nil-map read, so an absent request context needs no separate branch.
+	md, _ := metadata.FromIncomingContext(ctx)
+	for _, h := range t.headers {
+		dst = append(dst, labelValue(md.Get(h)))
+	}
+
+	return dst
+}
+
+// labelValue reduces a header's values to the one reported as a label. A header
+// the request did not carry yields "", because Prometheus has no notion of an
+// absent label value. So does one whose value is not valid UTF-8: client_golang
+// panics on those, and a caller should not be able to provoke that. Where a
+// header carries several values the last wins, as it does everywhere else the
+// proxy reduces metadata to a single value.
+func labelValue(vals []string) string {
+	if len(vals) == 0 {
+		return ""
+	}
+
+	// Validated before truncating, so a value that is already invalid is
+	// cleared rather than silently shortened into something that looks fine.
+	v := vals[len(vals)-1]
+	if !utf8.ValidString(v) {
+		return ""
+	}
+
+	if len(v) > maxTagValueLen {
+		v = v[:maxTagValueLen]
+
+		// Cutting on a byte boundary can split a rune, so drop the partial tail
+		// rather than emit a value client_golang would reject.
+		for len(v) > 0 && !utf8.ValidString(v) {
+			v = v[:len(v)-1]
+		}
+	}
+
+	return v
+}
diff --git a/internal/metrics/tags_test.go b/internal/metrics/tags_test.go
new file mode 100644
index 0000000..ef47703
--- /dev/null
+++ b/internal/metrics/tags_test.go
@@ -0,0 +1,161 @@
+package metrics_test
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/metadata"
+
+	"github.com/temporalio/temporal-proxy/internal/config"
+	"github.com/temporalio/temporal-proxy/internal/metrics"
+)
+
+func TestNewTags(t *testing.T) {
+	t.Parallel()
+
+	t.Run("no tags yields the zero value", func(t *testing.T) {
+		t.Parallel()
+
+		tags := metrics.NewTags(nil)
+		require.Zero(t, tags.Len())
+		require.Empty(t, tags.Labels())
+	})
+
+	t.Run("labels keep configured order and case", func(t *testing.T) {
+		t.Parallel()
+
+		tags := metrics.NewTags([]config.MetricTag{
+			{Header: "x-tenant", Label: "Tenant"},
+			{Header: "x-region", Label: "region"},
+		})
+
+		require.Equal(t, 2, tags.Len())
+		require.Equal(t, []string{"Tenant", "region"}, tags.Labels())
+	})
+
+	t.Run("Labels returns a copy", func(t *testing.T) {
+		t.Parallel()
+
+		tags := metrics.NewTags([]config.MetricTag{{Header: "x-tenant", Label: "tenant"}})
+
+		got := tags.Labels()
+		got[0] = "mutated"
+		require.Equal(t, []string{"tenant"}, tags.Labels())
+	})
+}
+
+func TestTags_AppendValues(t *testing.T) {
+	t.Parallel()
+
+	tags := metrics.NewTags([]config.MetricTag{
+		{Header: "x-tenant", Label: "tenant"},
+		{Header: "x-region", Label: "region"},
+	})
+
+	tests := []struct {
+		name string
+		md   metadata.MD // nil means no incoming metadata at all
+		want []string
+	}{
+		{
+			name: "both headers present",
+			md:   metadata.Pairs("x-tenant", "acme", "x-region", "us-east"),
+			want: []string{"acme", "us-east"},
+		},
+		{
+			name: "values follow label order, not metadata order",
+			md:   metadata.Pairs("x-region", "us-east", "x-tenant", "acme"),
+			want: []string{"acme", "us-east"},
+		},
+		{
+			// gRPC canonicalizes keys to lowercase, so a header the config wrote
+			// in mixed case still has to match.
+			name: "a mixed-case header on the wire still matches",
+			md:   metadata.Pairs("X-Tenant", "acme"),
+			want: []string{"acme", ""},
+		},
+		{
+			name: "an absent header yields an empty value",
+			md:   metadata.Pairs("x-tenant", "acme"),
+			want: []string{"acme", ""},
+		},
+		{
+			name: "no incoming metadata yields empty values",
+			md:   nil,
+			want: []string{"", ""},
+		},
+		{
+			// Matches how the proxy reduces multi-valued metadata elsewhere, e.g.
+			// the template context in internal/proxy.
+			name: "the last of several values wins",
+			md:   metadata.Pairs("x-tenant", "first", "x-tenant", "last"),
+			want: []string{"last", ""},
+		},
+		{
+			// client_golang panics on a label value that is not valid UTF-8, and
+			// gRPC does not police the bytes of a textual header, so a caller
+			// could otherwise crash the process on demand.
+			name: "a value that is not valid UTF-8 is dropped",
+			md:   metadata.Pairs("x-tenant", string([]byte{0xff, 0xfe}), "x-region", "us-east"),
+			want: []string{"", "us-east"},
+		},
+		{
+			// The guard applies to whichever value the last-wins rule picked, so
+			// a bad value last is cleared rather than falling back to a good one
+			// earlier in the list.
+			name: "an earlier valid value does not rescue an invalid last one",
+			md:   metadata.Pairs("x-tenant", "acme", "x-tenant", string([]byte{0xff})),
+			want: []string{"", ""},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := t.Context()
+			if tt.md != nil {
+				ctx = metadata.NewIncomingContext(ctx, tt.md)
+			}
+
+			require.Equal(t, tt.want, tags.AppendValues(ctx, nil))
+		})
+	}
+}
+
+func TestTags_AppendValuesExtendsTheCallersSlice(t *testing.T) {
+	t.Parallel()
+
+	tags := metrics.NewTags([]config.MetricTag{{Header: "x-tenant", Label: "tenant"}})
+	ctx := metadata.NewIncomingContext(t.Context(), metadata.Pairs("x-tenant", "acme"))
+
+	require.Equal(t, []string{"method", "code", "acme"}, tags.AppendValues(ctx, []string{"method", "code"}))
+}
+
+func TestTags_AppendValuesWithNoTagsLeavesTheSliceAlone(t *testing.T) {
+	t.Parallel()
+
+	// The fast path every deployment that configures no tags takes: the label
+	// list is handed back exactly as it arrived.
+	var tags metrics.Tags
+
+	require.Equal(t, []string{"method"}, tags.AppendValues(t.Context(), []string{"method"}))
+	require.Nil(t, tags.AppendValues(t.Context(), nil))
+}
+
+func TestTags_AppendValuesTruncatesOnARuneBoundary(t *testing.T) {
+	t.Parallel()
+
+	tags := metrics.NewTags([]config.MetricTag{{Header: "x-tenant", Label: "tenant"}})
+
+	// Each euro sign is three bytes, so a cut at 256 bytes lands mid-rune and
+	// the partial tail has to be dropped rather than reported.
+	ctx := metadata.NewIncomingContext(t.Context(), metadata.Pairs("x-tenant", strings.Repeat("€", 200)))
+
+	got := tags.AppendValues(ctx, nil)
+	require.Len(t, got, 1)
+	require.True(t, utf8.ValidString(got[0]), "a truncated value must still be valid UTF-8")
+	require.Equal(t, strings.Repeat("€", 85), got[0], "expected a whole number of runes within the cap")
+}
diff --git a/internal/proxy/encryption.go b/internal/proxy/encryption.go
index 1c356bd..7dba566 100644
--- a/internal/proxy/encryption.go
+++ b/internal/proxy/encryption.go
@@ -32,7 +32,7 @@ type (
 func (c *cipher) Encrypt(data []byte) (*crypto.Message, error) {
 	start := time.Now()
 	msg, err := c.v.Seal(c.ctx, c.ns, data)
-	c.r.VaultOp("encrypt", resultLabel(err), c.ns, time.Since(start).Seconds())
+	c.r.VaultOp(c.ctx, "encrypt", resultLabel(err), c.ns, time.Since(start).Seconds())
 
 	return msg, err
 }
@@ -41,7 +41,7 @@ func (c *cipher) Encrypt(data []byte) (*crypto.Message, error) {
 func (c *cipher) Decrypt(m *crypto.Message) ([]byte, error) {
 	start := time.Now()
 	pt, err := c.v.Open(c.ctx, m)
-	c.r.VaultOp("decrypt", resultLabel(err), c.ns, time.Since(start).Seconds())
+	c.r.VaultOp(c.ctx, "decrypt", resultLabel(err), c.ns, time.Since(start).Seconds())
 
 	return pt, err
 }
diff --git a/internal/proxy/encryption_test.go b/internal/proxy/encryption_test.go
index 913f55b..5aa54ac 100644
--- a/internal/proxy/encryption_test.go
+++ b/internal/proxy/encryption_test.go
@@ -18,6 +18,7 @@ import (
 	"google.golang.org/grpc/metadata"
 	"google.golang.org/protobuf/proto"
 
+	"github.com/temporalio/temporal-proxy/internal/config"
 	"github.com/temporalio/temporal-proxy/internal/metrics"
 	"github.com/temporalio/temporal-proxy/internal/proxy"
 	"github.com/temporalio/temporal-proxy/internal/transport/meta"
@@ -213,11 +214,53 @@ func TestEncryptionErrors(t *testing.T) {
 	})
 }
 
+func TestEncryptionRecordsVaultOpsWithTags(t *testing.T) {
+	t.Parallel()
+
+	reg := prometheus.NewRegistry()
+	tags := metrics.NewTags([]config.MetricTag{{Header: "X-Tenant", Label: "tenant"}})
+	reporter := proxy.NewReporter(metrics.New("proxy", promauto.With(reg)).ForSubsystem("encryption"), tags)
+
+	vault := &fakeVault{}
+	interceptor, err := proxy.CodecInterceptor(proxy.CodecOptions{Vault: vault, Encrypt: true, Reporter: reporter})
+	require.NoError(t, err)
+
+	// The namespace reaches this hop as outgoing metadata, but a tag is read
+	// from the incoming metadata the gateway forwarded over the socket, which is
+	// the only reason tags work on this side at all.
+	ctx := metadata.AppendToOutgoingContext(t.Context(), meta.NamespaceHeader, "ns1")
+	ctx = metadata.NewIncomingContext(ctx, metadata.Pairs("x-tenant", "acme"))
+
+	req := startRequest(&common.Payload{Data: []byte("hi")})
+	resp := &workflowservice.StartWorkflowExecutionRequest{}
+
+	invoker := func(_ context.Context, _ string, gotReq, gotResp any, _ *grpc.ClientConn, _ ...grpc.CallOption) error {
+		sent := gotReq.(*workflowservice.StartWorkflowExecutionRequest).Input.Payloads[0]
+		gotResp.(*workflowservice.StartWorkflowExecutionRequest).Input = &common.Payloads{
+			Payloads: []*common.Payload{sent},
+		}
+		return nil
+	}
+	require.NoError(t, interceptor(ctx, "/method", req, resp, nil, invoker))
+
+	ops := gatherFamily(t, reg, "proxy_encryption_vault_ops_total")
+	require.NotNil(t, ops)
+	require.True(t, hasLabels(ops, map[string]string{
+		"operation": "encrypt", "result": "success", "namespace": "ns1", "tenant": "acme",
+	}))
+
+	dur := gatherFamily(t, reg, "proxy_encryption_vault_ops_duration_secs")
+	require.NotNil(t, dur)
+	require.True(t, hasLabels(dur, map[string]string{
+		"operation": "encrypt", "namespace": "ns1", "tenant": "acme",
+	}))
+}
+
 func TestEncryptionRecordsVaultOps(t *testing.T) {
 	t.Parallel()
 
 	reg := prometheus.NewRegistry()
-	reporter := proxy.NewReporter(metrics.New("proxy", promauto.With(reg)).ForSubsystem("encryption"))
+	reporter := proxy.NewReporter(metrics.New("proxy", promauto.With(reg)).ForSubsystem("encryption"), metrics.Tags{})
 
 	vault := &fakeVault{}
 	interceptor, err := proxy.CodecInterceptor(proxy.CodecOptions{Vault: vault, Encrypt: true, Reporter: reporter})
@@ -254,7 +297,7 @@ func TestEncryptionSkipsMetricsForPassThrough(t *testing.T) {
 	t.Parallel()
 
 	reg := prometheus.NewRegistry()
-	reporter := proxy.NewReporter(metrics.New("proxy", promauto.With(reg)).ForSubsystem("encryption"))
+	reporter := proxy.NewReporter(metrics.New("proxy", promauto.With(reg)).ForSubsystem("encryption"), metrics.Tags{})
 
 	vault := &fakeVault{}
 	interceptor, err := proxy.CodecInterceptor(proxy.CodecOptions{Vault: vault, Encrypt: true, Reporter: reporter})
@@ -364,7 +407,7 @@ func respondWith(payloads ...*common.Payload) grpc.UnaryInvoker {
 // any other test's metrics.
 func newTestReporter(t *testing.T) *proxy.Reporter {
 	t.Helper()
-	return proxy.NewReporter(metrics.New("test", promauto.With(prometheus.NewRegistry())).ForSubsystem("encryption"))
+	return proxy.NewReporter(metrics.New("test", promauto.With(prometheus.NewRegistry())).ForSubsystem("encryption"), metrics.Tags{})
 }
 
 // gatherFamily returns the metric family named name from reg, or nil if no
diff --git a/internal/proxy/reporter.go b/internal/proxy/reporter.go
index 4a7dd26..8554f58 100644
--- a/internal/proxy/reporter.go
+++ b/internal/proxy/reporter.go
@@ -1,6 +1,8 @@
 package proxy
 
 import (
+	"context"
+
 	"github.com/prometheus/client_golang/prometheus"
 
 	"github.com/temporalio/temporal-proxy/internal/metrics"
@@ -15,25 +17,32 @@ import (
 type Reporter struct {
 	ops      *prometheus.CounterVec
 	duration *prometheus.HistogramVec
+	tags     metrics.Tags
 }
 
 // NewReporter builds the Prometheus-backed vault-operation Reporter. f must
-// already be scoped to the "encryption" subsystem by the caller.
-func NewReporter(f *metrics.Factory) *Reporter {
+// already be scoped to the "encryption" subsystem by the caller. tags are the
+// configured metadata labels, and may be the zero value.
+func NewReporter(f *metrics.Factory, tags metrics.Tags) *Reporter {
 	return &Reporter{
 		ops: f.NewCounter(prometheus.CounterOpts{
 			Name: "vault_ops_total",
 			Help: "Total envelope operations (encrypt/decrypt), labeled by operation, result, and namespace.",
-		}, []string{"operation", "result", "namespace"}),
+		}, append([]string{"operation", "result", "namespace"}, tags.Labels()...)),
 		duration: f.NewHistogram(prometheus.HistogramOpts{
 			Name: "vault_ops_duration_secs",
 			Help: "Duration of envelope operations in seconds end to end, including any KEK wrap or unwrap, labeled by operation and namespace.",
-		}, []string{"operation", "namespace"}),
+		}, append([]string{"operation", "namespace"}, tags.Labels()...)),
+		tags: tags,
 	}
 }
 
-// VaultOp records a single envelope operation and its duration.
-func (r *Reporter) VaultOp(operation, result, namespace string, seconds float64) {
-	r.ops.WithLabelValues(operation, result, namespace).Inc()
-	r.duration.WithLabelValues(operation, namespace).Observe(seconds)
+// VaultOp records a single envelope operation and its duration. ctx is the
+// request's, and supplies the configured metadata label values. This runs on the
+// per-upstream hop, where the metadata is what the gateway forwarded rather than
+// what it received, so a header the inbound authenticator consumed is gone.
+func (r *Reporter) VaultOp(ctx context.Context, operation, result, namespace string, seconds float64) {
+	tags := r.tags.AppendValues(ctx, nil)
+	r.ops.WithLabelValues(append([]string{operation, result, namespace}, tags...)...).Inc()
+	r.duration.WithLabelValues(append([]string{operation, namespace}, tags...)...).Observe(seconds)
 }
diff --git a/internal/router/director.go b/internal/router/director.go
index ce878b4..34b491f 100644
--- a/internal/router/director.go
+++ b/internal/router/director.go
@@ -64,15 +64,15 @@ func (d *director) Resolve(
 ) (Target, error) {
 	upstream, outcome := d.mux.Switch(namespace, md)
 	if outcome == OutcomeUnroutable {
-		d.reporter.Decision(upstreamUnknown, OutcomeUnroutable)
+		d.reporter.Decision(ctx, upstreamUnknown, OutcomeUnroutable)
 		return Target{}, status.Error(codes.FailedPrecondition, "no upstream matched the request and no default is configured")
 	}
 
-	d.reporter.Decision(upstream, outcome)
+	d.reporter.Decision(ctx, upstream, outcome)
 
 	cc, ok := d.conns[upstream]
 	if !ok {
-		d.reporter.ForwardingError(upstream, reasonNoConnection)
+		d.reporter.ForwardingError(ctx, upstream, reasonNoConnection)
 		return Target{}, status.Errorf(codes.Unavailable, "router: no connection for upstream %q", upstream)
 	}
 
diff --git a/internal/router/handler.go b/internal/router/handler.go
index 4f1bcd1..d646b72 100644
--- a/internal/router/handler.go
+++ b/internal/router/handler.go
@@ -93,7 +93,7 @@ func Handler(d Director, a services.Allowlist, rep *Reporter) grpc.StreamHandler
 		)
 		if err != nil {
 			if rep != nil {
-				rep.ForwardingError(target.Upstream, reasonStreamSetup)
+				rep.ForwardingError(ctx, target.Upstream, reasonStreamSetup)
 			}
 
 			return err
diff --git a/internal/router/handler_test.go b/internal/router/handler_test.go
index 6994039..4bd12e4 100644
--- a/internal/router/handler_test.go
+++ b/internal/router/handler_test.go
@@ -698,10 +698,21 @@ func serve(t *testing.T, srv *grpc.Server, lis *bufconn.Listener) {
 // tmprl_proxy_router_* names, for tests that need to observe (or discard) what
 // the handler records.
 func newTestReporter(t *testing.T, upstreams ...string) (*router.Reporter, *prometheus.Registry) {
+	t.Helper()
+	return newTaggedTestReporter(t, metrics.Tags{}, upstreams...)
+}
+
+// newTaggedTestReporter is newTestReporter for the cases that care what tags do
+// to the label set and to pre-resolution.
+func newTaggedTestReporter(
+	t *testing.T,
+	tags metrics.Tags,
+	upstreams ...string,
+) (*router.Reporter, *prometheus.Registry) {
 	t.Helper()
 	reg := prometheus.NewRegistry()
 	factory := metrics.New("tmprl_proxy", promauto.With(reg)).ForSubsystem("router")
-	return router.NewReporter(factory, upstreams), reg
+	return router.NewReporter(factory, upstreams, tags), reg
 }
 
 // newRelayToUpstream stands up a fake upstream (configured by registerUpstream),
diff --git a/internal/router/reporter.go b/internal/router/reporter.go
index 9ef61cd..6dbc9cf 100644
--- a/internal/router/reporter.go
+++ b/internal/router/reporter.go
@@ -1,6 +1,8 @@
 package router
 
 import (
+	"context"
+
 	"github.com/prometheus/client_golang/prometheus"
 
 	"github.com/temporalio/temporal-proxy/internal/metrics"
@@ -22,11 +24,17 @@ type (
 	// so the emit path is a lock-free map read; an unexpected label combination
 	// falls back to CounterVec.WithLabelValues. A Reporter is safe for concurrent
 	// use.
+	//
+	// Configured metadata tags suppress that pre-resolution, because their values
+	// arrive with a request and cannot be enumerated at startup. Every emit then
+	// takes the fallback, and no series starts at zero, so a query for a counter
+	// that has not been incremented yet finds nothing rather than 0.
 	Reporter struct {
 		decisions *prometheus.CounterVec
 		errors    *prometheus.CounterVec
 		decHandle map[decisionKey]prometheus.Counter
 		errHandle map[errorKey]prometheus.Counter
+		tags      metrics.Tags
 	}
 
 	decisionKey struct {
@@ -43,23 +51,34 @@ type (
 // NewReporter builds the Prometheus-backed Reporter, registering its collectors
 // with the factory's registry and pre-resolving the meaningful label
 // combinations so every series starts at zero. upstreams is the configured
-// upstream name list.
-func NewReporter(f *metrics.Factory, upstreams []string) *Reporter {
+// upstream name list. tags are the configured metadata labels, and may be the
+// zero value.
+//
+// Nothing is pre-resolved when tags are configured: a handle would have to fix
+// their values, which only a request carries. Leaving the maps empty routes
+// every emit through the fallback the maps exist to avoid, rather than adding a
+// second path that could drift from it.
+func NewReporter(f *metrics.Factory, upstreams []string, tags metrics.Tags) *Reporter {
 	decisions := f.NewCounter(prometheus.CounterOpts{
 		Name: "decisions_total",
 		Help: "Total routing decisions, labeled by chosen upstream and outcome.",
-	}, []string{"upstream", "outcome"})
+	}, append([]string{"upstream", "outcome"}, tags.Labels()...))
 
 	errors := f.NewCounter(prometheus.CounterOpts{
 		Name: "forwarding_errors_total",
 		Help: "Total router-originated forwarding failures, labeled by upstream and reason.",
-	}, []string{"upstream", "reason"})
+	}, append([]string{"upstream", "reason"}, tags.Labels()...))
 
 	r := &Reporter{
 		decisions: decisions,
 		errors:    errors,
 		decHandle: make(map[decisionKey]prometheus.Counter),
 		errHandle: make(map[errorKey]prometheus.Counter),
+		tags:      tags,
+	}
+
+	if tags.Len() > 0 {
+		return r
 	}
 
 	outcomes := []Outcome{OutcomeMatch, OutcomeDefault, OutcomeSystem}
@@ -81,22 +100,26 @@ func NewReporter(f *metrics.Factory, upstreams []string) *Reporter {
 }
 
 // Decision increments the decision counter for the chosen upstream and outcome.
-func (r *Reporter) Decision(upstream string, outcome Outcome) {
+// ctx is the request's, and supplies the configured metadata label values.
+func (r *Reporter) Decision(ctx context.Context, upstream string, outcome Outcome) {
 	if c, ok := r.decHandle[decisionKey{upstream, outcome}]; ok {
 		c.Inc()
 		return
 	}
 
-	r.decisions.WithLabelValues(upstream, outcome.String()).Inc()
+	lvs := append([]string{upstream, outcome.String()}, r.tags.AppendValues(ctx, nil)...)
+	r.decisions.WithLabelValues(lvs...).Inc()
 }
 
 // ForwardingError increments the forwarding-error counter for the upstream and
-// reason.
-func (r *Reporter) ForwardingError(upstream, reason string) {
+// reason. ctx is the request's, and supplies the configured metadata label
+// values.
+func (r *Reporter) ForwardingError(ctx context.Context, upstream, reason string) {
 	if c, ok := r.errHandle[errorKey{upstream, reason}]; ok {
 		c.Inc()
 		return
 	}
 
-	r.errors.WithLabelValues(upstream, reason).Inc()
+	lvs := append([]string{upstream, reason}, r.tags.AppendValues(ctx, nil)...)
+	r.errors.WithLabelValues(lvs...).Inc()
 }
diff --git a/internal/router/reporter_test.go b/internal/router/reporter_test.go
index 3851fd3..5265bc9 100644
--- a/internal/router/reporter_test.go
+++ b/internal/router/reporter_test.go
@@ -6,7 +6,10 @@ import (
 
 	"github.com/prometheus/client_golang/prometheus/testutil"
 	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/metadata"
 
+	"github.com/temporalio/temporal-proxy/internal/config"
+	"github.com/temporalio/temporal-proxy/internal/metrics"
 	"github.com/temporalio/temporal-proxy/internal/router"
 )
 
@@ -46,10 +49,10 @@ tmprl_proxy_router_forwarding_errors_total{reason="stream_setup",upstream="prima
 
 		m, reg := newTestReporter(t, "primary")
 
-		m.Decision("primary", router.OutcomeMatch)
-		m.Decision("primary", router.OutcomeMatch)
-		m.Decision("unknown", router.OutcomeUnroutable)
-		m.ForwardingError("primary", "no_connection")
+		m.Decision(t.Context(), "primary", router.OutcomeMatch)
+		m.Decision(t.Context(), "primary", router.OutcomeMatch)
+		m.Decision(t.Context(), "unknown", router.OutcomeUnroutable)
+		m.ForwardingError(t.Context(), "primary", "no_connection")
 
 		const wantDecisions = `
 # HELP tmprl_proxy_router_decisions_total Total routing decisions, labeled by chosen upstream and outcome.
@@ -81,7 +84,7 @@ tmprl_proxy_router_forwarding_errors_total{reason="stream_setup",upstream="prima
 
 		// "secondary" was not pre-resolved; the defensive WithLabelValues path must
 		// still create and increment the series.
-		m.Decision("secondary", router.OutcomeMatch)
+		m.Decision(t.Context(), "secondary", router.OutcomeMatch)
 
 		const want = `
 # HELP tmprl_proxy_router_decisions_total Total routing decisions, labeled by chosen upstream and outcome.
@@ -97,3 +100,54 @@ tmprl_proxy_router_decisions_total{outcome="unroutable",upstream="unknown"} 0
 		))
 	})
 }
+
+func TestReporterTags(t *testing.T) {
+	t.Parallel()
+
+	tags := metrics.NewTags([]config.MetricTag{{Header: "X-Tenant", Label: "tenant"}})
+
+	t.Run("pre-resolves nothing, since a tag value arrives with a request", func(t *testing.T) {
+		t.Parallel()
+
+		_, reg := newTaggedTestReporter(t, tags, "primary")
+
+		// The counterpart to "pre-resolves meaningful series to zero": a handle
+		// would have to fix a tag value, so none is taken and no series exists
+		// until something is actually recorded.
+		count, err := testutil.GatherAndCount(reg, "tmprl_proxy_router_decisions_total")
+		require.NoError(t, err)
+		require.Zero(t, count)
+	})
+
+	t.Run("records the tag on both collectors", func(t *testing.T) {
+		t.Parallel()
+
+		m, reg := newTaggedTestReporter(t, tags, "primary")
+
+		ctx := metadata.NewIncomingContext(t.Context(), metadata.Pairs("x-tenant", "acme"))
+		m.Decision(ctx, "primary", router.OutcomeMatch)
+		m.ForwardingError(ctx, "primary", "no_connection")
+
+		// A request without the header still reports the label, empty.
+		m.Decision(t.Context(), "primary", router.OutcomeMatch)
+
+		const wantDecisions = `
+# HELP tmprl_proxy_router_decisions_total Total routing decisions, labeled by chosen upstream and outcome.
+# TYPE tmprl_proxy_router_decisions_total counter
+tmprl_proxy_router_decisions_total{outcome="match",tenant="",upstream="primary"} 1
+tmprl_proxy_router_decisions_total{outcome="match",tenant="acme",upstream="primary"} 1
+`
+		require.NoError(t, testutil.GatherAndCompare(
+			reg, strings.NewReader(wantDecisions), "tmprl_proxy_router_decisions_total",
+		))
+
+		const wantErrors = `
+# HELP tmprl_proxy_router_forwarding_errors_total Total router-originated forwarding failures, labeled by upstream and reason.
+# TYPE tmprl_proxy_router_forwarding_errors_total counter
+tmprl_proxy_router_forwarding_errors_total{reason="no_connection",tenant="acme",upstream="primary"} 1
+`
+		require.NoError(t, testutil.GatherAndCompare(
+			reg, strings.NewReader(wantErrors), "tmprl_proxy_router_forwarding_errors_total",
+		))
+	})
+}
diff --git a/internal/server/reporter.go b/internal/server/reporter.go
index 6b01db1..b50d9e4 100644
--- a/internal/server/reporter.go
+++ b/internal/server/reporter.go
@@ -1,6 +1,7 @@
 package server
 
 import (
+	"context"
 	"time"
 
 	"github.com/prometheus/client_golang/prometheus"
@@ -33,29 +34,35 @@ var durationBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10
 type Reporter struct {
 	duration *prometheus.HistogramVec
 	requests *prometheus.CounterVec
+	tags     metrics.Tags
 }
 
 // NewReporter builds the Prometheus-backed Reporter. f must already be scoped to
-// the "server" subsystem by the caller.
-func NewReporter(f *metrics.Factory) *Reporter {
+// the "server" subsystem by the caller. tags are the configured metadata labels
+// carried on both collectors, and may be the zero value.
+func NewReporter(f *metrics.Factory, tags metrics.Tags) *Reporter {
 	return &Reporter{
 		duration: f.NewHistogram(prometheus.HistogramOpts{
 			Name:    "request_duration_seconds",
 			Help:    "Time spent serving an RPC end to end, labeled by method.",
 			Buckets: durationBuckets,
-		}, []string{"method"}),
+		}, append([]string{"method"}, tags.Labels()...)),
 		requests: f.NewCounter(prometheus.CounterOpts{
 			Name: "requests_total",
 			Help: "Total RPCs served, labeled by method and gRPC status code.",
-		}, []string{"method", "code"}),
+		}, append([]string{"method", "code"}, tags.Labels()...)),
+		tags: tags,
 	}
 }
 
 // Observe records one completed RPC: its duration on the method histogram and a
-// count on the (method, code) counter.
-func (r *Reporter) Observe(method string, code codes.Code, d time.Duration) {
-	r.duration.WithLabelValues(method).Observe(d.Seconds())
-	r.requests.WithLabelValues(method, code.String()).Inc()
+// count on the (method, code) counter. ctx is the request's, and supplies the
+// configured metadata label values; the two collectors carry different fixed
+// labels, so the values are resolved once and appended to each.
+func (r *Reporter) Observe(ctx context.Context, method string, code codes.Code, d time.Duration) {
+	tags := r.tags.AppendValues(ctx, nil)
+	r.duration.WithLabelValues(append([]string{method}, tags...)...).Observe(d.Seconds())
+	r.requests.WithLabelValues(append([]string{method, code.String()}, tags...)...).Inc()
 }
 
 // StreamInterceptor returns a stream server interceptor that times the handler
@@ -73,7 +80,7 @@ func (r *Reporter) StreamInterceptor() grpc.StreamServerInterceptor {
 	) error {
 		start := time.Now()
 		err := handler(srv, ss)
-		r.Observe(info.FullMethod, status.Code(err), time.Since(start))
+		r.Observe(ss.Context(), info.FullMethod, status.Code(err), time.Since(start))
 		return err
 	}
 }
diff --git a/internal/server/reporter_test.go b/internal/server/reporter_test.go
index efa62e4..612c6e0 100644
--- a/internal/server/reporter_test.go
+++ b/internal/server/reporter_test.go
@@ -1,6 +1,7 @@
 package server_test
 
 import (
+	"context"
 	"strings"
 	"testing"
 	"time"
@@ -12,9 +13,11 @@ import (
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/metadata"
 	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/test/bufconn"
 
+	"github.com/temporalio/temporal-proxy/internal/config"
 	"github.com/temporalio/temporal-proxy/internal/metrics"
 	"github.com/temporalio/temporal-proxy/internal/server"
 )
@@ -25,11 +28,11 @@ func TestReporterObserve(t *testing.T) {
 	t.Run("counts requests by method and code", func(t *testing.T) {
 		t.Parallel()
 
-		r, reg := newTestReporter(t)
+		r, reg := newTestReporter(t, metrics.Tags{})
 
-		r.Observe("/svc/Method", codes.OK, 750*time.Millisecond)
-		r.Observe("/svc/Method", codes.OK, 250*time.Millisecond)
-		r.Observe("/svc/Other", codes.NotFound, 2*time.Second)
+		r.Observe(t.Context(), "/svc/Method", codes.OK, 750*time.Millisecond)
+		r.Observe(t.Context(), "/svc/Method", codes.OK, 250*time.Millisecond)
+		r.Observe(t.Context(), "/svc/Other", codes.NotFound, 2*time.Second)
 
 		require.NoError(t, testutil.GatherAndCompare(reg, strings.NewReader(`
 # HELP tmprl_proxy_server_requests_total Total RPCs served, labeled by method and gRPC status code.
@@ -42,10 +45,10 @@ tmprl_proxy_server_requests_total{code="NotFound",method="/svc/Other"} 1
 	t.Run("buckets durations by method", func(t *testing.T) {
 		t.Parallel()
 
-		r, reg := newTestReporter(t)
+		r, reg := newTestReporter(t, metrics.Tags{})
 
-		r.Observe("/svc/Method", codes.OK, 750*time.Millisecond)
-		r.Observe("/svc/Method", codes.OK, 250*time.Millisecond)
+		r.Observe(t.Context(), "/svc/Method", codes.OK, 750*time.Millisecond)
+		r.Observe(t.Context(), "/svc/Method", codes.OK, 250*time.Millisecond)
 
 		require.NoError(t, testutil.GatherAndCompare(reg, strings.NewReader(`
 # HELP tmprl_proxy_server_request_duration_seconds Time spent serving an RPC end to end, labeled by method.
@@ -71,13 +74,22 @@ tmprl_proxy_server_request_duration_seconds_count{method="/svc/Method"} 2
 	})
 }
 
+// fakeStream is a ServerStream supplying only a context, which is all the
+// reporter's interceptor reads from it.
+type fakeStream struct {
+	grpc.ServerStream
+	ctx context.Context
+}
+
+func (s *fakeStream) Context() context.Context { return s.ctx }
+
 func TestReporterStreamInterceptor(t *testing.T) {
 	t.Parallel()
 
 	t.Run("records the returned status code", func(t *testing.T) {
 		t.Parallel()
 
-		r, reg := newTestReporter(t)
+		r, reg := newTestReporter(t, metrics.Tags{})
 		interceptor := r.StreamInterceptor()
 
 		info := &grpc.StreamServerInfo{FullMethod: "/svc/Fail"}
@@ -85,7 +97,7 @@ func TestReporterStreamInterceptor(t *testing.T) {
 			return status.Error(codes.PermissionDenied, "nope")
 		}
 
-		err := interceptor(nil, nil, info, handler)
+		err := interceptor(nil, &fakeStream{ctx: t.Context()}, info, handler)
 		require.Error(t, err)
 		require.Equal(t, codes.PermissionDenied, status.Code(err))
 
@@ -99,13 +111,13 @@ tmprl_proxy_server_requests_total{code="PermissionDenied",method="/svc/Fail"} 1
 	t.Run("maps a nil error to OK", func(t *testing.T) {
 		t.Parallel()
 
-		r, reg := newTestReporter(t)
+		r, reg := newTestReporter(t, metrics.Tags{})
 		interceptor := r.StreamInterceptor()
 
 		info := &grpc.StreamServerInfo{FullMethod: "/svc/Ok"}
 		handler := func(any, grpc.ServerStream) error { return nil }
 
-		require.NoError(t, interceptor(nil, nil, info, handler))
+		require.NoError(t, interceptor(nil, &fakeStream{ctx: t.Context()}, info, handler))
 
 		require.NoError(t, testutil.GatherAndCompare(reg, strings.NewReader(`
 # HELP tmprl_proxy_server_requests_total Total RPCs served, labeled by method and gRPC status code.
@@ -118,7 +130,7 @@ tmprl_proxy_server_requests_total{code="OK",method="/svc/Ok"} 1
 func TestReporterInterceptorMetersForwardedTraffic(t *testing.T) {
 	t.Parallel()
 
-	r, reg := newTestReporter(t)
+	r, reg := newTestReporter(t, metrics.Tags{})
 
 	handler := func(_ any, _ grpc.ServerStream) error {
 		return status.Error(codes.Unimplemented, "unknown")
@@ -163,10 +175,10 @@ tmprl_proxy_server_requests_total{code="Unimplemented",method="/temporal.api.wor
 `), "tmprl_proxy_server_requests_total"))
 }
 
-func newTestReporter(t *testing.T) (*server.Reporter, *goprom.Registry) {
+func newTestReporter(t *testing.T, tags metrics.Tags) (*server.Reporter, *goprom.Registry) {
 	t.Helper()
 	f, reg := newTestFactory(t)
-	return server.NewReporter(f.ForSubsystem("server")), reg
+	return server.NewReporter(f.ForSubsystem("server"), tags), reg
 }
 
 // newTestFactory builds a namespace-scoped metrics Factory backed by a fresh,
@@ -177,3 +189,45 @@ func newTestFactory(t *testing.T) (*metrics.Factory, *goprom.Registry) {
 	reg := goprom.NewRegistry()
 	return metrics.New("tmprl_proxy", promauto.With(reg)), reg
 }
+
+func TestReporterCarriesConfiguredTags(t *testing.T) {
+	t.Parallel()
+
+	tags := metrics.NewTags([]config.MetricTag{{Header: "X-Tenant", Label: "tenant"}})
+	r, reg := newTestReporter(t, tags)
+
+	ctx := metadata.NewIncomingContext(t.Context(), metadata.Pairs("x-tenant", "acme"))
+	r.Observe(ctx, "/svc/Method", codes.OK, time.Second)
+
+	// A request that carried no header still reports the label, empty, because
+	// Prometheus has no notion of an absent label value.
+	r.Observe(t.Context(), "/svc/Other", codes.OK, time.Second)
+
+	require.NoError(t, testutil.GatherAndCompare(reg, strings.NewReader(`
+# HELP tmprl_proxy_server_requests_total Total RPCs served, labeled by method and gRPC status code.
+# TYPE tmprl_proxy_server_requests_total counter
+tmprl_proxy_server_requests_total{code="OK",method="/svc/Method",tenant="acme"} 1
+tmprl_proxy_server_requests_total{code="OK",method="/svc/Other",tenant=""} 1
+`), "tmprl_proxy_server_requests_total"))
+}
+
+func TestReporterInterceptorReadsTagsFromTheStream(t *testing.T) {
+	t.Parallel()
+
+	// Proves the interceptor takes the metadata off the stream it was handed,
+	// which is the only reason Observe needs a context at all.
+	tags := metrics.NewTags([]config.MetricTag{{Header: "x-tenant", Label: "tenant"}})
+	r, reg := newTestReporter(t, tags)
+
+	ctx := metadata.NewIncomingContext(t.Context(), metadata.Pairs("x-tenant", "acme"))
+	info := &grpc.StreamServerInfo{FullMethod: "/svc/Ok"}
+	handler := func(any, grpc.ServerStream) error { return nil }
+
+	require.NoError(t, r.StreamInterceptor()(nil, &fakeStream{ctx: ctx}, info, handler))
+
+	require.NoError(t, testutil.GatherAndCompare(reg, strings.NewReader(`
+# HELP tmprl_proxy_server_requests_total Total RPCs served, labeled by method and gRPC status code.
+# TYPE tmprl_proxy_server_requests_total counter
+tmprl_proxy_server_requests_total{code="OK",method="/svc/Ok",tenant="acme"} 1
+`), "tmprl_proxy_server_requests_total"))
+}