Native Observability¶
This documentation describes the 2.0.x branch
For the differences from 1.1.x, and for the one change that affects module developers, see Versions.
Native Observability adds a request-level observability layer inside Drupal 10 and 11. It traces requests, records execution spans, aggregates route performance metrics, observes cache and database runtime behavior, and exports telemetry to Prometheus, OpenTelemetry collectors, and Elastic. All capture and export logic runs inside the Drupal request lifecycle, through service decorators, an observer, a stack middleware, and kernel event subscribers.
The module instruments Drupal by wrapping core services (a decorator on http_client, an observer on cache_tags.invalidator, a stack middleware around page_cache, and kernel event subscribers) rather than patching them. A built-in sanity check, at /admin/reports/native-observability/sanity-check or drush no:sanity-check, verifies those integration points are intact and flags conflicting third-party overrides.
Who it serves¶
- Site builders and administrators who need an in-Drupal dashboard for traces, execution timelines, cache behavior, and database queries, without provisioning an external stack.
- Operations teams running Prometheus, Mimir, or an OTLP collector who need
drupal_*metrics and OTLP traces pushed or scraped from the application itself. - Teams using ECA who want to trigger no-code rules (alerts, log entries) on trace events such as
native_observability:trace_recorded.
Key features¶
- Request tracing: ULID-based request IDs, parent/child and AJAX correlation, correlation ID injected in response headers.
- Execution spans: service execution tracking, HTTP client tracing, span categorization, stored and rendered per trace.
- Cache and database observation: real cache runtime events (response cache layer, cacheability, tag invalidations) and slow/relevant database queries, each with a filterable report and JSON export.
- Metrics: route-level throughput, average duration, and P95/P99 latency percentiles.
- Dashboard: aggregated visualization, cache and database insight panels, and a Forensic Route Analysis tab that correlates traces, spans, and outbound HTTP/SQL signals for a given route.
- Reporting: a report builder with narrative analysis and privacy-aware export controls, producing printable HTML output.
- Telemetry export: a Prometheus-compatible scrape endpoint and an OpenTelemetry (OTLP) push exporter.
- Request log exclusion: rule-based suppression (exact, prefix, or regex path match, with optional query conditions) that removes noisy or synthetic traffic from traces, spans, metrics, and exports before it pollutes the dataset.
- Event-driven automation: an ECA bridge that exposes trace and deletion events to Event-Condition-Action workflows, with an optional demo rule pack.
Install tiers¶
The module family ships as independent sub-modules grouped into three install tiers that match three consumer profiles. A single drush command installs the right set of modules for each.
| Tier | Intended consumer | Modules in the tier | Install command |
|---|---|---|---|
| raw | External scrapers (Prometheus, Mimir, curl, CI). No human UI. | native_observability, native_observability_spans, native_observability_metrics, native_observability_cache_observer, native_observability_export |
drush no:preset:raw |
| dashboard | Drupal-admin operators using the in-site dashboard. | raw tier plus native_observability_execution, native_observability_database_observer, native_observability_dashboard, native_observability_report, native_observability_status_block |
drush no:preset:dashboard |
| integrations | Sites pushing telemetry into an external stack (Grafana via OTLP) and/or wiring observability events into ECA workflows. | dashboard tier plus native_observability_otel, native_observability_eca_bridge |
drush no:preset:integrations |
See Installation for the full install sequence, dependency list, and the first-time Drush bootstrap step.