Skip to main content

Observability

Set Config.Observe to collect phase timings without giving a metrics backend access to query contents:

config.Observe = func(ctx context.Context, event query.Observation) {
// Pass fixed endpoint/phase/error-code labels to your metrics backend.
// Record event.Duration.Seconds() in a histogram.
// An empty event.ErrorCode means success.
}

Engine.List and Session.List emit these phases in order:

PhaseWork included
PhaseParseDecode and parse the request using endpoint limits
PhaseValidateBind the query to policy, select default sort, validate cursor
PhaseCountPrepare and execute an explicitly requested count, including search
PhaseDataPrepare and execute the data query, model hooks, and next cursor

A failure emits the current phase's event with the stable error code and stops later phases. Count is absent unless requested; data is absent for limit=0. Parse, Apply, and ValidateConfig do not emit List events. Time spent in the callback itself is excluded from that event's duration. A nil callback avoids clock reads.

The callback is synchronous and receives the caller's context, including cancellation. It must be concurrency-safe, return promptly, and not panic. Gotq does not start goroutines, maintain queues, or recover observer panics. Use your application's bounded telemetry pipeline if exporting needs I/O.

Observation contains only Phase, Duration, and ErrorCode. It never contains SQL, raw errors, filter/search text, cursor keys, or tenant IDs. Use fixed endpoint labels instead of URLs or request values to keep metric cardinality bounded. Although the callback receives the application's context for trace correlation, avoid exporting identity or sensitive context values.

No metrics, tracing, or HTTP framework dependency is added to the library. Applications can connect this hook to their existing telemetry provider.