@multisystemsuite/db-observability

Collect database metrics for queries, transactions, locks, and connection pools. Export Prometheus text, OpenTelemetry span descriptors, and Grafana panel definitions.

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/db-observability on npm

Installation

pnpm add @multisystemsuite/db-observability

Quick start

import { DbObservability } from '@multisystemsuite/db-observability';

const obs = new DbObservability({ serviceName: 'api' });

obs.recordQuery({ query: 'SELECT 1', executionTime: 42 });
obs.recordTransaction(true);
obs.updatePool({ active: 5, idle: 10, waiting: 0 });

console.log(obs.toPrometheus());

Configuration

| Option | Default | Description | |--------|---------|-------------| | serviceName | database-toolkit | Label on all metrics | | enableOpenTelemetry | — | Reserved for future OTel SDK wiring |

Recording events

| Method | Description | |--------|-------------| | recordQuery(input) | Track query duration (feeds slow query count) | | recordTransaction(committed) | true = commit, false = rollback | | recordLockWait() | Increment lock wait counter | | recordDeadlock() | Increment deadlock counter | | updatePool({ active, idle, waiting }) | Connection pool snapshot |

Dashboard snapshot

const dash = obs.getDashboard();
// {
//   queries: { total, slow, avgMs },
//   transactions: { committed, rolledBack },
//   locks: { waits, deadlocks },
//   pool: { active, idle, waiting }
// }

Exporters

Prometheus

const text = obs.toPrometheus();
// Mount at GET /metrics in Express

Metrics exported:

| Metric | Description | |--------|-------------| | db_query_total | Total queries recorded | | db_query_slow_total | Queries > 1000ms | | db_query_duration_avg_ms | Rolling average duration | | db_transaction_committed_total | Commits | | db_transaction_rollback_total | Rollbacks | | db_lock_waits_total | Lock waits | | db_deadlocks_total | Deadlocks | | db_pool_active / idle / waiting | Pool gauges |

OpenTelemetry

const spans = obs.toOpenTelemetrySpans();
// Span descriptors with attributes for your OTel SDK

Grafana

obs.getGrafanaPanels();
// [{ title, type, query }, ...]

Metric points

obs.toMetricPoints(); // MetricPoint[] for custom pipelines

Express metrics endpoint

app.get('/metrics', (_req, res) => {
  res.type('text/plain').send(obs.toPrometheus());
});

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/db-observability
• Install: npm install @multisystemsuite/db-observability