Observability

Observability#

Introduction#

DBLayer observability is event-driven. Query and transaction events can feed logger, profiler, telemetry export, and custom callbacks simultaneously.

Query lifecycle events:

  • successful queries emit db.query.executed

  • failed queries emit db.query.failed

Logger#

DB::enableLogger('/tmp/dblayer.log');
DB::select('select 1');
DB::disableLogger();

Logger writes structured entries to file and can also forward entries to any PSR-3 compatible logger backend. Binding values are redacted by default.

use Psr\Log\LoggerInterface;

/** @var LoggerInterface $psrLogger */
DB::enableLogger('/tmp/dblayer.log', $psrLogger);

// Or configure backend separately:
// DB::setPsrLogger($psrLogger);
// DB::enableLogger('/tmp/dblayer.log');

DB::enableLogger('/tmp/dblayer.log');
DB::logger()->setRedactBindings(true); // default
// DB::logger()->setRedactBindings(false); // only for controlled local debugging

Profiler#

DB::enableProfiler();
DB::table('users')->limit(1)->get();
$stats = DB::profiler()->getStats();

Profiler captures query duration and memory deltas for local diagnosis.

Facade Listener#

DB::listen(function (array $event): void {
    // query, bindings, time, connection, rows
});

Use listeners for metrics adapters, custom tracing, or alerting hooks.

Telemetry#

DB::enableTelemetry();
DB::table('sqlite_master')->select('name')->limit(1)->get();
$snapshot = DB::telemetry();
$otel = DB::telemetryOtel('dblayer-service');
$report = DB::slowQueryReport([50, 90, 95, 99], 1.0);
$flushed = DB::flushTelemetry();

Buffers are bounded by default (query and transaction events), and can be adjusted:

DB::setTelemetryBufferLimits(queryEvents: 2000, transactionEvents: 2000);
DB::setProfilerMaxProfiles(2000);

Failed-query telemetry defaults to redacted SQL/error payloads while preserving statement type, fingerprint, connection, duration, attempts, and exception class metadata.

Telemetry Exports#

  • telemetry(): snapshot, does not clear buffers.

  • flushTelemetry(): returns payload and clears buffers.

  • telemetryOtel() / flushTelemetryOtel(): OpenTelemetry-like shape.

Long Query Threshold Hook#

Register a callback once cumulative query time exceeds a threshold:

DB::whenQueryingForLongerThan(500.0, function (): void {
    // threshold crossed
});

Note

For production pipelines, export and clear telemetry buffers on a regular cadence to keep in-memory diagnostic data tight and recent.