Defer rare telemetry instrument creation

[ChiragAgg5k]

Summary

• Upgrade utopia-php/telemetry to the released ^0.4 package that includes lazy instrument factories.
• Keep steady-state breaker instruments eager, including calls, active calls, state, failures, and successes.
• Defer rare/event-driven instruments until first record: callback failures, fallbacks, transitions, and event timestamps.
• Add unit coverage that verifies successful calls do not register rare instruments and transition events create them on first use.

Why

OpenTelemetry registers instruments with the meter when they are created. If circuit breakers eagerly create rare event metrics, periodic exports can include registered instruments that have no datapoints. For event-driven metrics, no event should mean no instrument stream yet.

Steady-state metrics remain eager because zero is meaningful for breaker state and counts. Rare metrics now use the telemetry package's lazy factories so they only register when data is actually recorded.

Testing

• composer test:unit
• ./vendor/bin/phpstan analyse --memory-limit=512M
• composer lint

[greptile-apps]

Greptile Summary

This PR defers creation of four rare/event-driven telemetry instruments (callbackFailures, fallbacks, transitions, eventTimestamp) from eager construction to lazy factories (Counter::lazy() / Gauge::lazy()), and upgrades utopia-php/telemetry to ^0.4 which provides those factories. Steady-state instruments (calls, activeCalls, stateGauge, failuresGauge, successesGauge) remain eager because zero is still a meaningful value for periodic exports.

• CircuitBreaker.php: setTelemetry() replaces four $telemetry->createCounter/createGauge() calls with Counter::lazy() / Gauge::lazy() static factories; all call-sites remain unchanged since the properties still type-check as ?Counter / ?Gauge.
• CircuitBreakerTest.php: Two new tests confirm that successful calls leave rare keys absent from the telemetry adapter, and that trip() (CLOSED→OPEN) materialises exactly transitions and event.timestamp on first use.
• composer.json: Version constraint widens from 0.2.* to ^0.4; Composer treats ^0.4 on a 0.x package as >=0.4.0 <0.5.0, so the constraint is appropriately tight.

Confidence Score: 5/5

Safe to merge — the change is narrowly scoped to instrument creation order, all existing tests pass, and two new tests directly exercise the lazy-creation contract.

The diff touches only how four instruments are registered with the telemetry adapter; the recording call-sites (->add(), ->record()) are identical to before. The lazy factories return the same Counter/Gauge types the properties already declare, so no type unsafety is introduced. The new tests cover the two cases that matter most — no instrument created on a clean success path, and the correct subset created on a forced transition — and the pre-existing suite exercises recording values through those same instruments. No behavioural logic was changed.

No files require special attention.

Important Files Changed

Filename	Overview
composer.json	Bumps utopia-php/telemetry from 0.2.* to ^0.4 to unlock lazy instrument factories; Composer's caret on 0.x constrains to >=0.4.0 <0.5.0, so accidental 0.5 breakage is not a risk.
src/CircuitBreaker/CircuitBreaker.php	Moves callbackFailures, fallbacks, transitions, and eventTimestamp from eager createCounter/createGauge calls to Counter::lazy() / Gauge::lazy() factories; steady-state instruments remain eager. Logic is correct and type-safe given PHPStan passes.
tests/unit/CircuitBreakerTest.php	Extends existing inspection test with assertArrayNotHasKey guards and adds two focused tests that verify rare instruments are absent on successful calls and are created exactly on first record (via trip()).

_{Reviews (1): Last reviewed commit: "Defer rare telemetry instrument creation" | Re-trigger Greptile}