Skip to main content

nexus-observability

Vendor-neutral telemetry contracts — tracing, metrics, and context-propagation interfaces with zero-cost no-op defaults. Every satellite package depends on this foundation; application code can reference it without committing to an SDK.

Install​

terminal
composer require nexus-actors/observability

What's in this package​

Class / InterfacePurpose
ObservabilityEntry-point interface: tracer(), meter(), propagator(), currentContext(), shutdown()
NoopObservabilityZero-overhead default; isEnabled() returns false so call sites skip work
ObservabilityConfigImmutable config value object; fromEnv() reads standard OTEL env vars
TracerInterface: startSpan(name, kind, attributes, parent): Span
SpanInterface: setAttribute(), recordException(), setStatus(), end()
SpanKindEnum: Server, Client, Producer, Consumer, Internal
StatusCodeEnum: Unset, Ok, Error
MeterInterface: counter(), histogram(), upDownCounter(), observableGauge()
ContextPropagatorInterface: inject(context, carrier) / extract(carrier): Context
ContextImmutable ambient span context passed to startSpan as $parent

Quick example​

src/Bootstrap/ObservabilitySetup.php
use Monadial\Nexus\Observability\NoopObservability;
use Monadial\Nexus\Observability\Observability;

// Default: zero-overhead no-op — safe to wire anywhere without an SDK
$obs = new NoopObservability();

// Type-hint the interface so callers are SDK-agnostic
function instrumentedWork(Observability $obs): void
{
    if (!$obs->isEnabled()) {
        return;
    }

    $span = $obs->tracer()->startSpan('my.operation');
    $span->end();
}

Use ObservabilityConfig::fromEnv($_SERVER) to read OTEL_SDK_DISABLED, OTEL_SERVICE_NAME, and related env vars, then pass the config to ObservabilityFactory::fromConfig() from nexus-actors/observability-otel.

See also​