# Observability (/docs/python/observability)

## Query events [#query-events]

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

<CodeBlock>
```python
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),
)
```
</CodeBlock>

- 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 [#diagnostics]

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

<CodeBlock>
```python
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})
```
</CodeBlock>

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 [#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](/docs/python/http-security#request-ids).
