Monitoring & Metrics

Observability is crucial for production search engines. pg-smart-search provides built-in health checks and real-time metrics.

Health Checks

Verify the status of your dependencies before accepting traffic.

const status = await engine.health();

console.log(status);
// { healthy: true, database: 'ok', cache: 'ok', details: { ... } }

The health() method checks the database and the configured cache provider. There is no vector-provider check — an unreachable embedding API is only surfaced when a VECTOR-tier search actually runs (as a providerErrors metric increment, see below), not by health().

Real-Time Metrics

engine.metrics is a MetricsCollector instance, not a plain object — call .getSummary() to get a snapshot:

console.log(engine.metrics.getSummary());
// {
//   totalSearches: 4213, cacheHits: 3877, cacheMisses: 336, cacheHitRate: 0.92,
//   dbLatencies: [ ...last 1000 raw samples in ms ], avgDbLatencyMs: 12.4,
//   providerErrors: 0, searchErrors: 2, strategyUsage: { STANDARD: 4100, VECTOR: 113 }
// }

Available Metrics

• cacheHitRate: cacheHits / (cacheHits + cacheMisses), 0 before any cache activity.
• avgDbLatencyMs: Average DB query latency over the last 1000 samples (ring buffer, not a rolling "last 100").
• providerErrors: Failures from the VECTOR tier's embedding provider (OpenAI/Gemini) specifically.
• searchErrors: Any other failed search (DB error, validation, etc.) — kept separate from providerErrors so one doesn't get miscounted as the other.

You can expose these metrics to Prometheus, Datadog, or your preferred monitoring tool by periodically calling engine.metrics.getSummary().