From 9dae6c7ec887456a9abd44a13acc33511ce2085d Mon Sep 17 00:00:00 2001
From: Evgenii Fadeev <fes94@ya.ru>
Date: Fri, 28 Aug 2026 22:04:02 +0300
Subject: [PATCH] feat(loki.enrich): Add multi-label matching

---
 .../reference/components/loki/loki.enrich.md  |  86 ++++++----
 internal/component/common/enrich/matcher.go   |  88 ++++++++++
 .../component/common/enrich/matcher_test.go   | 158 ++++++++++++++++++
 internal/component/loki/enrich/enrich.go      |  95 ++++++-----
 internal/component/loki/enrich/enrich_test.go | 155 +++++++++++++++++
 .../component/prometheus/enrich/enrich.go     |  94 +----------
 6 files changed, 524 insertions(+), 152 deletions(-)
 create mode 100644 internal/component/common/enrich/matcher.go
 create mode 100644 internal/component/common/enrich/matcher_test.go

diff --git a/docs/sources/reference/components/loki/loki.enrich.md b/docs/sources/reference/components/loki/loki.enrich.md
index 8d74924c31e..fcc4a8b5a9f 100644
--- a/docs/sources/reference/components/loki/loki.enrich.md
+++ b/docs/sources/reference/components/loki/loki.enrich.md
@@ -15,25 +15,33 @@ description: The loki.enrich component enriches logs with labels from service di
 {{< docs/shared lookup="stability/experimental.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
 The `loki.enrich` component enriches logs with additional labels from service discovery targets.
-It matches a label from incoming logs against a label from discovered targets, and copies specified labels from the matched target to the log entry.
+It matches labels from incoming logs against labels from discovered targets, and copies specified labels from the matched target to the log entry.
+If no match occurs, the component forwards the log entry unchanged.
+
+Use the `target_to_log_match` argument to specify which target labels correspond to which log labels.
+The map keys are target label names and the values are the corresponding log label names.
+All labels in the map must match for enrichment to occur.
+
+{{< admonition type="warning" >}}
+The `target_match_label` and `logs_match_label` arguments are deprecated in favor of `target_to_log_match`.
+If `target_to_log_match` is set, it takes precedence.
+Replace `target_match_label = "hostname"` with `target_to_log_match = {"hostname" = "hostname"}`.
+These deprecated arguments will be removed in a future release.
+{{< /admonition >}}
 
 ## Usage
 
 ```alloy
 loki.enrich "<LABEL>" {
-  // List of targets from a discovery component
   targets = <DISCOVERY_COMPONENT>.targets
-  
-  // Which label from discovered targets to match against
-  target_match_label = "<LABEL>"
-  
-  // Which label from incoming logs to match against
-  logs_match_label = "<LABEL>"
-  
-  // List of labels to copy from discovered targets to logs
+
+  target_to_log_match = {
+    "<TARGET_LABEL_1>" = "<LOG_LABEL_1>",
+    "<TARGET_LABEL_2>" = "<LOG_LABEL_2>",
+  }
+
   labels_to_copy = ["<LABEL>", ...]
-  
-  // Where to send enriched logs
+
   forward_to = [<RECEIVER_LIST>]
 }
 ```
@@ -42,15 +50,14 @@ loki.enrich "<LABEL>" {
 
 You can use the following arguments with `loki.enrich`:
 
-| Name                 | Type                  | Description                                                                                      | Default                | Required |
-| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------- | -------- |
-| `forward_to`         | `[]loki.LogsReceiver` | List of receivers to send enriched logs to.                                                      |                        | yes      |
-| `target_match_label` | `string`              | The label from discovered targets to match against, for example, `"__inventory_consul_service"`. |                        | yes      |
-| `targets`            | `[]discovery.Target`  | List of targets from a discovery component.                                                      |                        | yes      |
-| `labels_to_copy`     | `[]string`            | List of labels to copy from discovered targets to logs. If empty, all labels will be copied.     |                        | no       |
-| `logs_match_label`   | `string`              | The label from incoming logs to match against discovered targets, for example `"service_name"`.  |                        | no       |
-
-If not provided, the `logs_match_label` attribute will default to the value of `target_match_label`.
+| Name                  | Type                 | Description                                                                                                   | Default | Required |
+| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | -------- |
+| `forward_to`          | `list(LogsReceiver)` | List of receivers to send log entries to.                                                                     |         | yes      |
+| `targets`             | `list(map(string))`  | List of targets from a discovery component.                                                                   |         | yes      |
+| `labels_to_copy`      | `list(string)`       | List of labels to copy from discovered targets to logs. If empty, all labels are copied.                      |         | no       |
+| `logs_match_label`    | `string`             | (Deprecated) The label from incoming logs to match against discovered targets, for example, `"service_name"`. |         | no       |
+| `target_match_label`  | `string`             | (Deprecated) The label from discovered targets to match against, for example, `"hostname"`.                   |         | no       |
+| `target_to_log_match` | `map(string)`        | Map of target label names to log label names. All entries must match for enrichment.                          |         | no       |
 
 ## Blocks
 
@@ -66,6 +73,9 @@ The following values are exported:
 
 ## Example
 
+The following example enriches syslog entries with labels from an HTTP service discovery target.
+It matches the connection IP address and tenant label before it forwards entries to Loki.
+
 ```alloy
 // Configure HTTP discovery
 discovery.http "default" {
@@ -101,15 +111,25 @@ discovery.relabel "default" {
     }
 }
 
+loki.relabel "syslog" {
+    rule {
+        source_labels = ["__syslog_connection_ip_address"]
+        target_label  = "source_ip"
+    }
+}
+
 // Receive syslog messages
 loki.source.syslog "incoming" {
     listener {
-        address = ":514"
+        address  = ":514"
         protocol = "tcp"
         labels = {
-            job = "syslog"
+            job    = "syslog"
+            tenant = "production"
         }
     }
+
+    relabel_rules = loki.relabel.syslog.rules
     forward_to = [loki.enrich.default.receiver]
 }
 
@@ -118,19 +138,27 @@ loki.enrich "default" {
     // Use targets from HTTP discovery (after relabeling)
     targets = discovery.relabel.default.output
 
-    // Match hostname from logs to DNS name
-    target_match_label = "primary_ip"
+    target_to_log_match = {
+        "primary_ip" = "source_ip"
+        "tenant"     = "tenant"
+    }
 
     forward_to = [loki.write.default.receiver]
 }
+
+loki.write "default" {
+    endpoint {
+        url = "http://loki:3100/loki/api/v1/push"
+    }
+}
 ```
 
-## Component Behavior
+## Component behavior
 
 The component matches logs to discovered targets and enriches them with additional labels:
 
-1. For each log entry, it looks up the value of `logs_match_label` from the log's labels or `target_match_label` if `logs_match_label` is not specified.
-1. It matches this value against the `target_match_label` in discovered targets.
+1. For each log entry, it looks up the log labels specified by `target_to_log_match`.
+1. It matches those values against the corresponding target labels. All label pairs must match the same target.
 1. If a match is found, it copies the requested `labels_to_copy` from the discovered target to the log entry. If `labels_to_copy` is empty, all labels are copied.
 1. The log entry, enriched or unchanged, is forwarded to the configured receivers.
 
@@ -158,4 +186,4 @@ Connecting some components may not be sensible or components may require further
 Refer to the linked documentation for more details.
 {{< /admonition >}}
 
-<!-- END GENERATED COMPATIBLE COMPONENTS -->
\ No newline at end of file
+<!-- END GENERATED COMPATIBLE COMPONENTS -->
diff --git a/internal/component/common/enrich/matcher.go b/internal/component/common/enrich/matcher.go
new file mode 100644
index 00000000000..1ecf4fb8096
--- /dev/null
+++ b/internal/component/common/enrich/matcher.go
@@ -0,0 +1,88 @@
+// Package enrich provides shared target matching for enrichment components.
+package enrich
+
+import (
+	"sort"
+
+	"github.com/cespare/xxhash/v2"
+	"github.com/prometheus/common/model"
+
+	"github.com/grafana/alloy/internal/component/discovery"
+)
+
+// Matcher looks up discovery targets using matching label values. It is safe for
+// concurrent lookups. To change the targets or matching strategy, create a new Matcher.
+type Matcher struct {
+	labelNames []string
+	targets    map[uint64]model.LabelSet
+}
+
+// NewMatcher builds a lookup from targets. targetToLabel maps target label names
+// to incoming label names. Targets with a missing or empty matching label are
+// skipped. If multiple targets have the same matching values, the last one wins.
+func NewMatcher(targets []discovery.Target, targetToLabel map[string]string) *Matcher {
+	targetNames := make([]string, 0, len(targetToLabel))
+	for name := range targetToLabel {
+		targetNames = append(targetNames, name)
+	}
+	sort.Strings(targetNames)
+
+	m := &Matcher{
+		labelNames: make([]string, 0, len(targetNames)),
+		targets:    make(map[uint64]model.LabelSet),
+	}
+	for _, name := range targetNames {
+		m.labelNames = append(m.labelNames, targetToLabel[name])
+	}
+	for _, target := range targets {
+		h, ok := hashValues(func(name string) string {
+			value, _ := target.Get(name)
+			return value
+		}, targetNames)
+		if !ok {
+			continue
+		}
+		labelSet := make(model.LabelSet, target.Len())
+		target.ForEachLabel(func(name, value string) bool {
+			labelSet[model.LabelName(name)] = model.LabelValue(value)
+			return true
+		})
+		m.targets[h] = labelSet
+	}
+	return m
+}
+
+// Match returns the matching target's labels, or nil if no target matches.
+// get must return an empty string for missing labels. The returned label set
+// belongs to the Matcher and must not be modified.
+func (m *Matcher) Match(get func(string) string) model.LabelSet {
+	h, ok := hashValues(get, m.labelNames)
+	if !ok {
+		return nil
+	}
+	return m.targets[h]
+}
+
+// Len returns the number of distinct matching targets in the lookup.
+func (m *Matcher) Len() int {
+	return len(m.targets)
+}
+
+var sep = []byte{0xff} // separates UTF-8 label values to preserve value boundaries
+
+// hashValues returns false if no names are configured or any value is empty.
+func hashValues(get func(string) string, names []string) (uint64, bool) {
+	if len(names) == 0 {
+		return 0, false
+	}
+	h := xxhash.New()
+	for _, name := range names {
+		value := get(name)
+		if value == "" {
+			return 0, false
+		}
+		_, _ = h.WriteString(value)
+		_, _ = h.Write(sep)
+	}
+	return h.Sum64(), true
+}
diff --git a/internal/component/common/enrich/matcher_test.go b/internal/component/common/enrich/matcher_test.go
new file mode 100644
index 00000000000..2961a6c9b2b
--- /dev/null
+++ b/internal/component/common/enrich/matcher_test.go
@@ -0,0 +1,158 @@
+package enrich_test
+
+import (
+	"testing"
+
+	"github.com/prometheus/common/model"
+	"github.com/prometheus/prometheus/model/labels"
+	"github.com/stretchr/testify/require"
+
+	"github.com/grafana/alloy/internal/component/common/enrich"
+	"github.com/grafana/alloy/internal/component/discovery"
+)
+
+func TestMatcher(t *testing.T) {
+	tests := []struct {
+		name     string
+		strategy map[string]string
+		targets  []model.LabelSet
+		input    model.LabelSet
+		want     model.LabelSet
+		wantLen  int
+	}{
+		{
+			name:     "single label",
+			strategy: map[string]string{"service": "service_name"},
+			targets:  []model.LabelSet{{"service": "api", "env": "prod"}},
+			input:    model.LabelSet{"service_name": "api"},
+			want:     model.LabelSet{"service": "api", "env": "prod"},
+			wantLen:  1,
+		},
+		{
+			name:     "all pairs match the same target regardless of label name order",
+			strategy: map[string]string{"namespace": "z_namespace", "pod": "a_pod"},
+			targets: []model.LabelSet{
+				{"namespace": "prod", "pod": "api", "env": "production"},
+				{"namespace": "stage", "pod": "api", "env": "staging"},
+			},
+			input:   model.LabelSet{"z_namespace": "stage", "a_pod": "api", "extra": "ignored"},
+			want:    model.LabelSet{"namespace": "stage", "pod": "api", "env": "staging"},
+			wantLen: 2,
+		},
+		{
+			name:     "pairs cannot match different targets",
+			strategy: map[string]string{"namespace": "namespace", "pod": "pod"},
+			targets: []model.LabelSet{
+				{"namespace": "prod", "pod": "api"},
+				{"namespace": "stage", "pod": "worker"},
+			},
+			input:   model.LabelSet{"namespace": "prod", "pod": "worker"},
+			wantLen: 2,
+		},
+		{
+			name:     "missing incoming label",
+			strategy: map[string]string{"namespace": "namespace", "pod": "pod"},
+			targets:  []model.LabelSet{{"namespace": "prod", "pod": "api"}},
+			input:    model.LabelSet{"namespace": "prod"},
+			wantLen:  1,
+		},
+		{
+			name:     "empty incoming label",
+			strategy: map[string]string{"namespace": "namespace", "pod": "pod"},
+			targets:  []model.LabelSet{{"namespace": "prod", "pod": "api"}},
+			input:    model.LabelSet{"namespace": "prod", "pod": ""},
+			wantLen:  1,
+		},
+		{
+			name:     "missing and empty target labels are skipped",
+			strategy: map[string]string{"namespace": "namespace", "pod": "pod"},
+			targets: []model.LabelSet{
+				{"namespace": "prod", "pod": "api"},
+				{"namespace": "prod"},
+				{"namespace": "prod", "pod": ""},
+			},
+			input:   model.LabelSet{"namespace": "prod", "pod": "api"},
+			want:    model.LabelSet{"namespace": "prod", "pod": "api"},
+			wantLen: 1,
+		},
+		{
+			name:    "empty strategy does not match",
+			targets: []model.LabelSet{{"service": "api"}},
+			input:   model.LabelSet{"service": "api"},
+		},
+		{
+			name:     "no targets",
+			strategy: map[string]string{"service": "service"},
+			input:    model.LabelSet{"service": "api"},
+		},
+		{
+			name:     "last duplicate target wins",
+			strategy: map[string]string{"service": "service"},
+			targets: []model.LabelSet{
+				{"service": "api", "env": "old"},
+				{"service": "api", "env": "new"},
+			},
+			input:   model.LabelSet{"service": "api"},
+			want:    model.LabelSet{"service": "api", "env": "new"},
+			wantLen: 1,
+		},
+		{
+			name:     "value boundaries are preserved",
+			strategy: map[string]string{"a": "a", "b": "b"},
+			targets: []model.LabelSet{
+				{"a": "ab", "b": "c"},
+				{"a": "a", "b": "bc"},
+			},
+			input:   model.LabelSet{"a": "ab", "b": "c"},
+			want:    model.LabelSet{"a": "ab", "b": "c"},
+			wantLen: 2,
+		},
+		{
+			name:     "multiple target labels map to the same incoming label",
+			strategy: map[string]string{"a": "service", "b": "service"},
+			targets:  []model.LabelSet{{"a": "api", "b": "api"}},
+			input:    model.LabelSet{"service": "api"},
+			want:     model.LabelSet{"a": "api", "b": "api"},
+			wantLen:  1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			targets := make([]discovery.Target, 0, len(tt.targets))
+			for _, target := range tt.targets {
+				targets = append(targets, discovery.NewTargetFromLabelSet(target))
+			}
+			matcher := enrich.NewMatcher(targets, tt.strategy)
+			require.Equal(t, tt.wantLen, matcher.Len())
+
+			// Exercise both label representations used by the components.
+			require.Equal(t, tt.want, matcher.Match(func(name string) string {
+				return string(tt.input[model.LabelName(name)])
+			}))
+			builder := labels.NewScratchBuilder(len(tt.input))
+			for name, value := range tt.input {
+				builder.Add(string(name), string(value))
+			}
+			builder.Sort()
+			require.Equal(t, tt.want, matcher.Match(builder.Labels().Get))
+		})
+	}
+}
+
+func TestMatcherSnapshotsTargetsAndStrategy(t *testing.T) {
+	strategy := map[string]string{"service": "service_name"}
+	own := model.LabelSet{"service": "api", "env": "prod"}
+	group := model.LabelSet{"service": "default", "region": "eu"}
+	target := discovery.NewTargetFromSpecificAndBaseLabelSet(own, group)
+	matcher := enrich.NewMatcher([]discovery.Target{target}, strategy)
+
+	strategy["service"] = "other"
+	own["service"] = "worker"
+	own["env"] = "stage"
+	group["region"] = "us"
+
+	require.Equal(t, model.LabelSet{"service": "api", "env": "prod", "region": "eu"},
+		matcher.Match(labels.FromStrings("service_name", "api").Get))
+	require.Nil(t, matcher.Match(labels.FromStrings("service_name", "worker").Get))
+}
diff --git a/internal/component/loki/enrich/enrich.go b/internal/component/loki/enrich/enrich.go
index e7524405225..d89bca0c500 100644
--- a/internal/component/loki/enrich/enrich.go
+++ b/internal/component/loki/enrich/enrich.go
@@ -3,11 +3,13 @@ package enrich
 
 import (
 	"context"
+	"fmt"
 	"sync"
 
 	"github.com/prometheus/common/model"
 
 	"github.com/grafana/alloy/internal/component"
+	commonenrich "github.com/grafana/alloy/internal/component/common/enrich"
 	"github.com/grafana/alloy/internal/component/common/loki"
 	"github.com/grafana/alloy/internal/component/discovery"
 	"github.com/grafana/alloy/internal/featuregate"
@@ -30,11 +32,15 @@ type Arguments struct {
 	// The targets to use for enrichment
 	Targets []discovery.Target `alloy:"targets,attr"`
 
-	// Which label from targets to use for matching (e.g. "hostname", "ip")
-	TargetMatchLabel string `alloy:"target_match_label,attr"`
+	// Multi-label matching: a map of target_label -> log_label.
+	// Takes precedence over target_match_label / logs_match_label.
+	TargetToLogMatch map[string]string `alloy:"target_to_log_match,attr,optional"`
 
-	// Which label from logs to match against (e.g. "hostname", "ip")
-	// If not specified, TargetMatchLabel will be used
+	// Legacy: which label from targets to use for matching (e.g. "hostname", "ip").
+	TargetMatchLabel string `alloy:"target_match_label,attr,optional"`
+
+	// Legacy: which label from logs to match against (e.g. "hostname", "ip").
+	// If not specified, TargetMatchLabel will be used.
 	LogsMatchLabel string `alloy:"logs_match_label,attr,optional"`
 
 	// List of labels to copy from discovered targets to logs. If empty, all labels will be copied.
@@ -44,10 +50,31 @@ type Arguments struct {
 	ForwardTo []loki.LogsReceiver `alloy:"forward_to,attr"`
 }
 
+// Validate implements syntax.Validator.
+func (a Arguments) Validate() error {
+	hasLegacy := a.TargetMatchLabel != "" || a.LogsMatchLabel != ""
+	hasNew := len(a.TargetToLogMatch) > 0
+
+	if !hasLegacy && !hasNew {
+		return fmt.Errorf("at least one match mechanism must be specified: set target_match_label or target_to_log_match")
+	}
+	// target_to_log_match takes precedence when set; legacy fields are ignored.
+	if hasLegacy && !hasNew && a.TargetMatchLabel == "" {
+		return fmt.Errorf("target_match_label must be set when using legacy match fields")
+	}
+	return nil
+}
+
 type Exports struct {
 	Receiver loki.LogsReceiver `alloy:"receiver,attr,optional"`
 }
 
+// matchCache holds the hash-based lookup for a match strategy.
+type matchCache struct {
+	matcher      *commonenrich.Matcher
+	labelsToCopy []string // snapshot of which target labels to copy (empty means copy all)
+}
+
 type Component struct {
 	opts component.Options
 
@@ -55,19 +82,16 @@ type Component struct {
 	fanout      *loki.Fanout
 	interceptor *loki.InterceptorConsumer
 
-	mut          sync.RWMutex
-	stopped      bool
-	args         Arguments
-	targetsCache map[string]model.LabelSet
+	mut     sync.RWMutex
+	stopped bool
+	mc      *matchCache
 }
 
 func New(opts component.Options, args Arguments) (*Component, error) {
 	c := &Component{
-		opts:         opts,
-		args:         args,
-		targetsCache: make(map[string]model.LabelSet),
-		receiver:     loki.NewLogsReceiver(loki.WithComponentID(opts.ID)),
-		fanout:       loki.NewFanout(args.ForwardTo),
+		opts:     opts,
+		receiver: loki.NewLogsReceiver(loki.WithComponentID(opts.ID)),
+		fanout:   loki.NewFanout(args.ForwardTo),
 	}
 
 	c.interceptor = loki.NewInterceptorConsumer(
@@ -121,11 +145,10 @@ func (c *Component) Update(args component.Arguments) error {
 	defer c.mut.Unlock()
 
 	newArgs := args.(Arguments)
-	c.args = newArgs
 	c.fanout.UpdateChildren(newArgs.ForwardTo)
 
 	// Update the targets cache with new targets
-	c.refreshCacheFromTargets(newArgs.Targets)
+	c.refreshCacheFromTargets(newArgs)
 
 	return nil
 }
@@ -133,23 +156,14 @@ func (c *Component) Update(args component.Arguments) error {
 // process returns lset enriched with labels from a matching target. Set
 // needsClone when the caller does not own lset.
 func (c *Component) process(lset model.LabelSet, needsClone bool) model.LabelSet {
-	// Determine which label to use for matching
-	matchLabel := c.args.LogsMatchLabel
-	if matchLabel == "" {
-		matchLabel = c.args.TargetMatchLabel
-	}
-
-	// Get the source value to match against discovered targets
-	sourceValue := string(lset[model.LabelName(matchLabel)])
-	if sourceValue == "" {
-		// No match label, forward as-is
+	if c.mc == nil {
 		return lset
 	}
 
-	// Look up matching target
-	targetLabels, found := c.targetsCache[sourceValue]
-	if !found {
-		// No matching target, forward as-is
+	targetLabels := c.mc.matcher.Match(func(name string) string {
+		return string(lset[model.LabelName(name)])
+	})
+	if targetLabels == nil {
 		return lset
 	}
 
@@ -157,14 +171,14 @@ func (c *Component) process(lset model.LabelSet, needsClone bool) model.LabelSet
 		lset = lset.Clone()
 	}
 
-	if len(c.args.LabelsToCopy) == 0 {
+	if len(c.mc.labelsToCopy) == 0 {
 		// If no specific labels are requested, copy all labels
 		for k, v := range targetLabels {
 			lset[k] = v
 		}
 	} else {
 		// Copy only requested labels
-		for _, label := range c.args.LabelsToCopy {
+		for _, label := range c.mc.labelsToCopy {
 			if value := targetLabels[model.LabelName(label)]; value != "" {
 				lset[model.LabelName(label)] = value
 			}
@@ -173,13 +187,18 @@ func (c *Component) process(lset model.LabelSet, needsClone bool) model.LabelSet
 	return lset
 }
 
-func (c *Component) refreshCacheFromTargets(targets []discovery.Target) {
-	newCache := make(map[string]model.LabelSet)
-	for _, target := range targets {
-		lset := target.LabelSet()
-		if matchValue := string(lset[model.LabelName(c.args.TargetMatchLabel)]); matchValue != "" {
-			newCache[matchValue] = lset
+func (c *Component) refreshCacheFromTargets(args Arguments) {
+	strategyMap := args.TargetToLogMatch
+	if len(strategyMap) == 0 && args.TargetMatchLabel != "" {
+		logsLabel := args.LogsMatchLabel
+		if logsLabel == "" {
+			logsLabel = args.TargetMatchLabel
 		}
+		strategyMap = map[string]string{args.TargetMatchLabel: logsLabel}
+	}
+
+	c.mc = &matchCache{
+		matcher:      commonenrich.NewMatcher(args.Targets, strategyMap),
+		labelsToCopy: args.LabelsToCopy,
 	}
-	c.targetsCache = newCache
 }
diff --git a/internal/component/loki/enrich/enrich_test.go b/internal/component/loki/enrich/enrich_test.go
index 870d6dc96b8..43f2f9d5dff 100644
--- a/internal/component/loki/enrich/enrich_test.go
+++ b/internal/component/loki/enrich/enrich_test.go
@@ -157,6 +157,103 @@ func TestEnricher(t *testing.T) {
 				Entry: expectedEntry,
 			},
 		},
+		{
+			name: "multi-label match selects the target using all labels",
+			args: Arguments{
+				Targets: []discovery.Target{
+					discovery.NewTargetFromMap(map[string]string{
+						"__meta_kubernetes_namespace": "production",
+						"__meta_kubernetes_pod_name":  "api-0",
+						"environment":                 "prod",
+					}),
+					discovery.NewTargetFromMap(map[string]string{
+						"__meta_kubernetes_namespace": "staging",
+						"__meta_kubernetes_pod_name":  "api-0",
+						"environment":                 "stage",
+					}),
+				},
+				TargetToLogMatch: map[string]string{
+					"__meta_kubernetes_namespace": "namespace",
+					"__meta_kubernetes_pod_name":  "pod",
+				},
+				LabelsToCopy: []string{"environment"},
+			},
+			input: loki.Entry{
+				Labels: model.LabelSet{
+					"namespace": "staging",
+					"pod":       "api-0",
+				},
+				Entry: inputEntry,
+			},
+			expected: loki.Entry{
+				Labels: model.LabelSet{
+					"namespace":   "staging",
+					"pod":         "api-0",
+					"environment": "stage",
+				},
+				Entry: expectedEntry,
+			},
+		},
+		{
+			name: "multi-label match requires every log label",
+			args: Arguments{
+				Targets: []discovery.Target{
+					discovery.NewTargetFromMap(map[string]string{
+						"__meta_kubernetes_namespace": "staging",
+						"__meta_kubernetes_pod_name":  "api-0",
+						"environment":                 "stage",
+					}),
+				},
+				TargetToLogMatch: map[string]string{
+					"__meta_kubernetes_namespace": "namespace",
+					"__meta_kubernetes_pod_name":  "pod",
+				},
+				LabelsToCopy: []string{"environment"},
+			},
+			input: loki.Entry{
+				Labels: model.LabelSet{
+					"namespace": "staging",
+				},
+				Entry: inputEntry,
+			},
+			expected: loki.Entry{
+				Labels: model.LabelSet{
+					"namespace": "staging",
+				},
+				Entry: expectedEntry,
+			},
+		},
+		{
+			name: "target_to_log_match takes precedence over legacy labels",
+			args: Arguments{
+				Targets: []discovery.Target{
+					discovery.NewTargetFromMap(map[string]string{
+						"cluster":   "cluster-a",
+						"legacy_id": "legacy-a",
+						"env":       "prod",
+					}),
+				},
+				TargetToLogMatch: map[string]string{"cluster": "cluster_id"},
+				TargetMatchLabel: "legacy_id",
+				LogsMatchLabel:   "legacy_id",
+				LabelsToCopy:     []string{"env"},
+			},
+			input: loki.Entry{
+				Labels: model.LabelSet{
+					"cluster_id": "cluster-a",
+					"legacy_id":  "does-not-match",
+				},
+				Entry: inputEntry,
+			},
+			expected: loki.Entry{
+				Labels: model.LabelSet{
+					"cluster_id": "cluster-a",
+					"legacy_id":  "does-not-match",
+					"env":        "prod",
+				},
+				Entry: expectedEntry,
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -202,6 +299,64 @@ func TestEnricher(t *testing.T) {
 	}
 }
 
+func TestValidate(t *testing.T) {
+	tests := []struct {
+		name    string
+		args    Arguments
+		wantErr string
+	}{
+		{
+			name: "valid legacy",
+			args: Arguments{
+				TargetMatchLabel: "service",
+			},
+		},
+		{
+			name: "valid legacy with logs_match_label",
+			args: Arguments{
+				TargetMatchLabel: "service",
+				LogsMatchLabel:   "service_name",
+			},
+		},
+		{
+			name: "valid multi-label match",
+			args: Arguments{
+				TargetToLogMatch: map[string]string{"namespace": "namespace", "pod_name": "pod"},
+			},
+		},
+		{
+			name:    "missing match mechanism",
+			args:    Arguments{},
+			wantErr: "at least one match mechanism must be specified",
+		},
+		{
+			name: "new match takes precedence over legacy",
+			args: Arguments{
+				TargetMatchLabel: "service",
+				TargetToLogMatch: map[string]string{"namespace": "namespace"},
+			},
+		},
+		{
+			name: "logs_match_label requires target_match_label",
+			args: Arguments{
+				LogsMatchLabel: "service_name",
+			},
+			wantErr: "target_match_label must be set",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.args.Validate()
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
 func TestUpdate(t *testing.T) {
 	comp, err := New(component.Options{
 		Logger:        logging.NewSlogNop(),
diff --git a/internal/component/prometheus/enrich/enrich.go b/internal/component/prometheus/enrich/enrich.go
index ce99b765613..630ac32be23 100644
--- a/internal/component/prometheus/enrich/enrich.go
+++ b/internal/component/prometheus/enrich/enrich.go
@@ -3,10 +3,8 @@ package enrich
 import (
 	"context"
 	"fmt"
-	"sort"
 	"sync"
 
-	"github.com/cespare/xxhash/v2"
 	prometheus_client "github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/common/model"
 	"github.com/prometheus/prometheus/model/exemplar"
@@ -17,6 +15,7 @@ import (
 	"go.uber.org/atomic"
 
 	"github.com/grafana/alloy/internal/component"
+	commonenrich "github.com/grafana/alloy/internal/component/common/enrich"
 	"github.com/grafana/alloy/internal/component/discovery"
 	"github.com/grafana/alloy/internal/component/prometheus"
 	"github.com/grafana/alloy/internal/featuregate"
@@ -77,51 +76,10 @@ type Exports struct {
 	Receiver storage.Appendable `alloy:"receiver,attr"`
 }
 
-var sep = []byte{0xff} // separator to prevent hash collisions across value boundaries
-
-// hashValuesFromLabelSet hashes the values of the given label names (in order)
-// from a model.LabelSet. Returns (0, false) if names is empty or any label is
-// missing or empty.
-func hashValuesFromLabelSet(ls model.LabelSet, names []string) (uint64, bool) {
-	if len(names) == 0 {
-		return 0, false
-	}
-	h := xxhash.New()
-	for _, name := range names {
-		v := string(ls[model.LabelName(name)])
-		if v == "" {
-			return 0, false
-		}
-		_, _ = h.WriteString(v)
-		_, _ = h.Write(sep)
-	}
-	return h.Sum64(), true
-}
-
-// hashValuesFromLabels hashes the values of the given label names (in order)
-// from a labels.Labels. Returns (0, false) if names is empty or any label is
-// missing or empty.
-func hashValuesFromLabels(lbls labels.Labels, names []string) (uint64, bool) {
-	if len(names) == 0 {
-		return 0, false
-	}
-	h := xxhash.New()
-	for _, name := range names {
-		v := lbls.Get(name)
-		if v == "" {
-			return 0, false
-		}
-		_, _ = h.WriteString(v)
-		_, _ = h.Write(sep)
-	}
-	return h.Sum64(), true
-}
-
 // matchCache holds the hash-based lookup for a match strategy.
 type matchCache struct {
-	sortedMetricLabels []string                  // metric label names to hash, sorted by corresponding target label name
-	cache              map[uint64]model.LabelSet // hash of values -> target label set
-	labelsToCopy       []string                  // snapshot of which target labels to copy (empty means copy all)
+	matcher      *commonenrich.Matcher
+	labelsToCopy []string // snapshot of which target labels to copy (empty means copy all)
 }
 
 type Component struct {
@@ -257,12 +215,8 @@ func (c *Component) enrich(lbls labels.Labels) labels.Labels {
 		return lbls
 	}
 
-	h, ok := hashValuesFromLabels(lbls, mc.sortedMetricLabels)
-	if !ok {
-		return lbls
-	}
-	targetSet, found := mc.cache[h]
-	if !found {
+	targetSet := mc.matcher.Match(lbls.Get)
+	if targetSet == nil {
 		return lbls
 	}
 
@@ -281,22 +235,6 @@ func (c *Component) enrich(lbls labels.Labels) labels.Labels {
 	return newLabels.Labels()
 }
 
-// sortStrategyMap converts a target_label->metric_label map into sorted
-// parallel slices for deterministic hashing.
-func sortStrategyMap(m map[string]string) (targetLabels, metricLabels []string) {
-	targetLabels = make([]string, 0, len(m))
-	for k := range m {
-		targetLabels = append(targetLabels, k)
-	}
-	sort.Strings(targetLabels)
-
-	metricLabels = make([]string, 0, len(targetLabels))
-	for _, k := range targetLabels {
-		metricLabels = append(metricLabels, m[k])
-	}
-	return targetLabels, metricLabels
-}
-
 func (c *Component) refreshCacheFromTargets(args Arguments) {
 	// Build the strategy map: target_label -> metric_label.
 	strategyMap := args.TargetToMetricMatch
@@ -309,28 +247,14 @@ func (c *Component) refreshCacheFromTargets(args Arguments) {
 		strategyMap = map[string]string{args.TargetMatchLabel: metricsLabel}
 	}
 
-	sortedTargetLabels, sortedMetricLabels := sortStrategyMap(strategyMap)
-	cache := make(map[uint64]model.LabelSet)
-	for _, target := range args.Targets {
-		labelSet := make(model.LabelSet)
-		target.ForEachLabel(func(k, v string) bool {
-			labelSet[model.LabelName(k)] = model.LabelValue(v)
-			return true
-		})
-		h, ok := hashValuesFromLabelSet(labelSet, sortedTargetLabels)
-		if !ok {
-			continue
-		}
-		cache[h] = labelSet
-	}
+	matcher := commonenrich.NewMatcher(args.Targets, strategyMap)
 
 	c.cacheMutex.Lock()
 	c.mc = &matchCache{
-		sortedMetricLabels: sortedMetricLabels,
-		cache:              cache,
-		labelsToCopy:       args.LabelsToCopy,
+		matcher:      matcher,
+		labelsToCopy: args.LabelsToCopy,
 	}
 	c.cacheMutex.Unlock()
 
-	c.cacheSize.Set(float64(len(cache)))
+	c.cacheSize.Set(float64(matcher.Len()))
 }