Observability

hypequery has two observability layers:

• runtime observability in @hypequery/serve
• builder-level query logging in @hypequery/clickhouse

Runtime observability

Use runtime hooks and query logging when you want visibility into requests flowing through serve({ queries }).

Lifecycle hooks

const api = serve({
  queries: { activeUsers },
  hooks: {
    onRequestStart: async (event) => {
      console.log('start', event.queryKey);
    },
    onRequestEnd: async (event) => {
      console.log('end', event.queryKey, event.durationMs);
    },
    onAuthFailure: async (event) => {
      console.warn('auth failed', event.queryKey, event.reason);
    },
    onAuthorizationFailure: async (event) => {
      console.warn('forbidden', event.queryKey, event.reason, event.required);
    },
    onError: async (event) => {
      console.error('error', event.queryKey, event.error);
    },
  },
});

Query logging

const api = serve({
  queries: { activeUsers },
  queryLogging: 'json',
  slowQueryThreshold: 2_000,
});

queryLogging accepts:

• true
• 'json'
• (event) => void

Lifecycle hooks currently support:

• onRequestStart
• onRequestEnd
• onAuthFailure
• onAuthorizationFailure
• onError

Builder-level query logging

Use the ClickHouse logger when you want SQL-level visibility into the query builder itself.

import { logger } from '@hypequery/clickhouse';

logger.configure({
  enabled: true,
  level: 'debug',
  onQueryLog: (log) => {
    console.log(log.query, log.duration, log.status);
  },
});

This is the right layer when you care about:

• generated SQL
• parameters
• row counts
• cache metadata
• low-level ClickHouse failures

When to use each layer

• use runtime observability for API-level timing, auth failures, and request lifecycle events
• use builder logging for SQL-level analysis and ClickHouse debugging
• use both when you want end-to-end visibility from route to database

See Also

• Runtime Features
• Rate Limiting
• Query Caching