nexphant/observability

Structured logging, runtime telemetry metrics, resource leak reporting, and runtime system doctor diagnostics.

Install

composer require nexphant/observability

Structured Logger

The Nexphant\Observability\Logger provides context-aware structured logging. Write to STDOUT or STDERR directly with context bindings:

use Nexphant\Observability\Logger;

$logger = new Logger(output: STDOUT, level: 'info', structured: true);

// Log message with context array
$logger->info('User logged in', ['user_id' => 42]);

// Clone logger with persistent context
$userLogger = $logger->withContext(['user_id' => 42]);
$userLogger->warning('Suspicious activity detected');

Output when structured is true (JSON lines format):

{"level":"info","message":"User logged in","user_id":42}

Metrics

Track performance indicators, active counts, and event latencies with Nexphant\Observability\Metrics:

use Nexphant\Observability\Metrics;

// Increment counter
Metrics::increment('http.requests', value: 1);

// Set gauge value
Metrics::gauge('active_fibers', 12.0);

// Record value in histogram
Metrics::histogram('request_latency_ms', 14.2);

Leak Reporter

Group and audit unreleased or active resources at runtime to prevent long-running process leaks:

use Nexphant\Observability\LeakReporter;

$snapshot = LeakReporter::snapshot();

// Get count of leaked resources
$count = $snapshot->count();

// Get raw leaked items details
$leaks = $snapshot->all();

// Group resources by owner
$byOwner = $snapshot->groupByOwner();

Doctor Diagnostics

Run a diagnosis of the persistent runtime environment to identify stuck processes or missing modules:

use Nexphant\Observability\Doctor;

$issues = Doctor::run();

foreach ($issues as $issue) {
    echo "[$issue[severity]] $issue[type]: $issue[count] occurrences\n";
}

Related

• Runtime Doctor
• Runtime Observability