add-metric

name

add-metric

description

Add a new OpenTelemetry metric (counter, up-down counter, histogram, or gauge) to this bundle. Use when asked to "add a metric", "count X", "record a histogram for X", or "publish token/usage metrics" in worldia/instrumentation-bundle. Encodes the metrics conventions, which differ from tracing — DI-only meter (no static facade), hardcoded attribute strings, and a separate feature toggle/subscriber.

Add a metric

Metrics in this bundle are wired separately from tracing and follow different rules. Do not bolt metrics onto a tracing decorator/subscriber — even when both observe the same event, the bundle keeps them as independent subscribers under independent toggles (see Messenger: src/Tracing/Messenger/... vs src/Metrics/EventSubscriber/MessageEventSubscriber.php).

Key differences from tracing

• No static facade. There is no Metrics::getMeter() equivalent to Tracing::getTracer(). Inject OpenTelemetry\API\Metrics\MeterProviderInterface and call $meterProvider->getMeter('instrumentation') in the constructor.
• Attribute names are plain strings (e.g. ['bus' => ..., 'class' => ...]), not OpenTelemetry\SemConv constants. (Tracing uses semconv constants; metrics historically don't.) If a published semconv metric exists for your case (e.g. gen_ai.client.token.usage), prefer that instrument name and its semconv attributes for ecosystem compatibility, but match the surrounding code's style.

Instrument types & naming

Create instruments on the meter and act on them:

• createCounter('<name>_total')->add($n, $attrs) — monotonic.
• createUpDownCounter('<name>')->add(±1, $attrs) — gauge-like running count (e.g. consumers_active, messages_handling).
• createHistogram('<name>_<unit>', '<unit>', '<desc>')->record($v, $attrs) — distributions (e.g. messages_time_to_consume_seconds).
• createGauge('<name>_<unit>', null, '<desc>')->record($v, $attrs) — point-in-time (e.g. memory_usage_bytes).

Naming: snake_case, unit suffix (_seconds, _bytes), _total suffix for monotonic counters. Reference: src/Metrics/EventSubscriber/MessageEventSubscriber.php, ConsumerEventSubscriber.php, RequestEventSubscriber.php.

The subscriber

Add src/Metrics/EventSubscriber/<Feature>EventSubscriber.php implementing EventSubscriberInterface, with MeterProviderInterface injected. Cache the meter in the constructor; create instruments lazily where recorded (the existing code calls createCounter(...) at the record site — that's fine, instruments are idempotent by name).

DI wiring

• src/DependencyInjection/config/metrics/<feature>.php — register the subscriber with ->autoconfigure() and ->args([service(MeterProviderInterface::class)]). Model: config/metrics/message.php.
• src/DependencyInjection/Configuration.php — add arrayNode('<feature>')->addDefaultsIfNotSet() under metrics, with booleanNode('enabled')->defaultFalse() and any blacklist node (see the metrics tree, lines 180–205).
• src/DependencyInjection/Extension.php → loadMetrics() — add if ($this->isConfigEnabled($container, $config['<feature>'])) { ...; $loader->load('<feature>.php'); }. Set metrics.<feature>.blacklist param first if the subscriber filters (model: the request branch, lines 230–233). The core metrics.php (MeterProvider) is always loaded.

Verify

• Subscriber gets the meter from injected MeterProviderInterface, never a static accessor.
• Instrument name follows snake_case + unit/_total convention.
• Feature is opt-in via its own metrics.<feature>.enabled node and loaded in loadMetrics().
• Add/extend a test under tests/Metrics/ using an in-memory metric reader, mirroring existing metric tests.