Telemetry Label Extensibility
INFO
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository. You can find the original version here
Context
Telemetry v2 (ADR 2026-04-23) bounds metric label values in two ways, and neither is open to extensions:
- Allow lists (
allowed_valuesin yaml) are declared withperformNoDeepMerging, so any later config source replaces the list. A plugin that ships its own list overwrites core's, two plugins overwrite each other; only project config can widen a list safely. - Framework internal labels, like
entity_groupordomain, are produced by internal resolvers with hardcoded maps. Everything an extension adds (entities, routes, messages, etc.) folds intoother.
Extensions need a way to surface their values in core metrics, and operators need a way to control the resulting label taxonomy.
Decision
1. Allow lists become additive via add_allowed_values
A label declares its values through two sibling keys with different merge semantics:
add_allowed_valuescontributes values: later sources append (native Symfony list merge).allowed_valuesdeclares the complete, final list: it keepsperformNoDeepMerging, the last source to set it wins. When present, everyadd_allowed_valuescontribution is ignored - settingallowed_valuesis both replace and lock.
Core ships extensible labels (like payment_method) with add_allowed_values, structurally closed labels (result, status_class, ...) keep allowed_values and stay locked.
The key processing is done at container build: a present allowed_values wins and add_allowed_values is cleared, otherwise add_allowed_values becomes the deduplicated union. A label declaring neither values nor a policy fails the container build; no other combination does, so configuration shipped by one party can't fail the build of a merged setup. On a policy: open label both value keys are inert: they stay visible in debug:config but are ignored at runtime. Bounding an open label is an explicit policy override: policy is a last-source-wins key, so a later source sets policy: replace (fold unlisted values) or policy: discard (drop the measurement) together with allowed_values.
Locking a label or overriding its policy is an operator-level decision, so plugins meant for public distribution should not do it (risk of conflicts with other plugins). But this is not enforced - operator's project policy can still be configured through a plugin.
A value outside the effective list is replaced with replace_unknown_label_values_with (default other) silently, in every environment. The previous dev/test replacement notice is removed: an extension that delivers custom route/entity/task should not be forced to provide telemetry configuration (opt-in approach), and should not produce logs noise at the same time. This supersedes the "log replacements at notice level in dev/test" decision of the v2 ADR; typo detection moves to emitter unit tests and to other showing up in dashboards where it should not.
To collapse a label entirely, lock it to exactly the replacement value: allowed_values: [other]; an open label additionally needs the policy override (policy: replace), or a catch-all mapping entry ('*': other).
2. Named mappings for derived labels
A mapping is a named table key → label value under shopware.telemetry.metrics.mappings config key. A label served by a mapping is declared with policy: open; the serving resolver owns the binding name as a class constant and bounds the cardinality. There is deliberately no label-level mapping reference: the key for mapping is extracted by label resolver and mapping reference should stay at the same place.
- A key is exact, or a prefix when it ends with
*. Exact beats prefix, the longest prefix wins. - All keys of one mapping should come from a single identifier space (route names, entity names, event names, ...); resolvers that extract differently-shaped keys should consult different mappings.
- Resolution order: code based rules are kept in the resolver (
is_achecks, route scopes, core pass-through sets). Entries from configuration win so an extension or operator can always correct a heuristic. - Merge is the standard deep merge: a later source overrides the same key, so project config overrides core and plugin entries. Extension-defined mapping names must carry a vendor prefix (
swag_paypal_refund_kind); bare names are reserved for core. - The core maps move out of the resolver constants into the shipped
telemetry.yamlwhere possible, so the known values are visible in one place. Only rules not expressible askey → valuestay in PHP.
Example: task_name uses a mapping rather than an allow list: scheduled tasks are a growing, mostly-noise list, and a mapping gives operators possibility to extract only interesting values, including those that will come with plugin updated (prefix-based approach).
3. The names become contract
At feature stabilization, the following join the BC promise and change only in majors, announced in the upgrade guide:
- metric names and label names,
- mapping names and the identifier space each mapping is keyed on,
- the merge semantics of
add_allowed_values,allowed_valuesandmappings.
The integration test TelemetryMetricContractTest pins these names; updating its snapshot is the conscious decision and, once stable, needs proper deprecation cycle.
The per-label mechanism (allow list or mapping) is deliberately not part of the promise, so core may switch a label's mechanism in a minor. A switch degrades gracefully in both directions: switching to a mapping turns contributed add_allowed_values and operator locks inert (unless operator fixed the policy), but label stays bounded by its mapping; the reverse silently orphans mapping entries.
The shipped group values (the right-hand side of the mapping tables and the core add_allowed_values) are not part of the promise. Core may regroup, rename or add values in minors.
Consequences
- The public surface stays declarative: yaml for plugins and projects, no PHP extension points.
- Plugins and projects widen allow lists with
add_allowed_valuesand contribute mapping entries in yaml. Extensions that do not opt in keep folding intoother, silently. - Operators close an allow list with
allowed_values(which also locks it against further contributions), bound an open label with an explicit policy override, and reshape mappings per key or prefix in project config. debug:config shopwareshows the effective state.- What folded into
otheris not reconstructable from the emitted series. If the need arises, an opt-in debug flag that logs replacements can be added without breaks. - Developers must choose a label's mechanism consciously: allow lists for sets where the raw value is desired and subtraction is rare, mappings for open, growing populations where folding into limited list of values is required.
- Resolvers keep their signatures and
@internalstatus; their job shrinks to key extraction, registry lookup, and code-level fallback.
Considered alternatives
- PHP attribute or interface for declaring groups on classes. Rejected: a declarative table is cacheable and introspectable, and configuration stays the single public surface. If apps support is needed - it can't be implemented using attributes.
- Keep the dev/test replacement notice (conditionally for closed labels only). Rejected: additional complexity, hard to distinguish cases where extension just did not opt-in vs
accidentaltypo cases. task_nameas an allow list with plugin opt-in. Rejected: gives operators no subtractive tool except maintaining the full list, which every plugin update can extend.
Scope note: app support postponed
Apps stay out of scope until a concrete need arises; their identifiers fold into other like any extension that does not opt in. Two (#22232, #22235) app-facing implementations were explored and parked unmerged. When decision is revisited - consult comments on relevant PRs for more context..