Observability

Query events

Pass events=QueryEvents(...) to create_api to receive one event per query from every endpoint, or to one endpoint to override it:

from hypequery.serve import QueryEvents, create_api


def sink(event) -> None:
    logger.info("hypequery query", extra={"event": event})  # your logging or metrics pipeline


api = create_api(
    auth=authenticate,
    client=client,
    datasets={"orders": orders},
    events=QueryEvents(target={"project": "acme", "environment": "production"}, sink=sink),
)

• Events follow the shared query-event format and contain identifiers, outcome, duration, and row count or failure category.
• They never contain request bodies, rows, SQL, credentials, or tenant values.
• The sink is synchronous. A failing sink never fails the query.

Diagnostics

Generated SQL is not returned by default, even with includeMeta. To let trusted callers see it, add DiagnosticAccess:

from hypequery.serve import DiagnosticAccess, Principal, create_dataset_endpoint


def authorize(principal: Principal) -> bool:
    return "admin" in principal.roles


def audit(principal: Principal, request_id: str) -> None:
    audit_log.write(principal.subject, request_id)  # your audit trail


endpoint = create_dataset_endpoint(
    dataset=orders,
    client=client,
    diagnostics=DiagnosticAccess(authorize=authorize, audit=audit),
)
api = create_api(auth=authenticate, datasets={"orders": endpoint})

Only a principal your authorize callback approves receives a separate diagnostics object, and only after audit succeeds. It contains redacted SQL, never bound values or raw tenant ids. Both callbacks run on worker threads.

Request ids

Every response carries an x-request-id, which also appears in meta.requestId and in server logs for unexpected errors. See HTTP security.