# Native Observability Database Observer

The **Native Observability Database Observer** submodule adds lightweight database query visibility to the Native
Observability ecosystem.

## Design goals

This observer is intentionally **not** a full SQL profiler.
Its purpose is to provide:

- total query count per request
- total database time per request
- slow query count per request
- optional raw slow-query storage above a configurable threshold
- route-level and request-level correlation for the RAW area

These database signals also help fill out the extended technical report and
the dashboard's database observability views.

## Why this module stays lightweight

The observer uses Drupal's native database logging during the current request and stores **only** records that exceed
the configured threshold.
This avoids a heavy per-query persistence flow and keeps runtime overhead under control.

## Correlation model

The module classifies captured rows using two relation types:

- `request_bound`: the query belongs to a regular HTTP request and can be related to route, path and request identifier
- `unrelated`: the query was executed without enough request context or outside the expected page rendering flow

The `unrelated` class is useful for custom executions, edge cases and debugging activity triggered from code paths that
are not clearly mapped to a page request.

## Recommended usage

- Keep the threshold conservative in production.
- Enable SQL text storage only when really needed.
- Use RAW pages for targeted troubleshooting and retention-based cleanup.

## Future extension points

Later versions may enrich the request trace with aggregated database counters and, when the spans module exposes an
active span context, correlate slow queries with execution spans as well.
