Native Observability

Native Observability records what a Drupal site does at runtime: request traces, execution spans, cache and database behaviour, metrics aggregated per route, and export to OpenTelemetry, Prometheus and Grafana. It runs inside the application, with no core patches and no external agent.

What it does

• Traces every request with a correlation ID carried across the full hop chain.
• Builds execution spans and draws them on a timeline in the dashboard.
• Captures outbound HTTP through a middleware on Drupal's shared handler stack, so calls issued by libraries that wrap http_client are recorded without touching them.
• Observes the cache: hits, misses, tag invalidations and cacheability decisions, per route and for the events that never reach a route.
• Observes the database: query counts, timing, and slow query evidence per route and per query hash.
• Aggregates metrics per route: request count, throughput, average, P95 and P99 latency, error rate.
• Reconstructs a single route in the Forensic Route Analysis view, correlating its traces, spans, cache signals and outbound calls, and exports that view as a self contained HTML document.
• Exports over OTLP to OpenTelemetry, serves a Prometheus scrape endpoint behind a bearer token, and writes a long form observability report.
• Measures its own runtime cost on the server where it runs, in paired blocks with capture on and capture off, and reports the figure with its sample size, its noise floor and a verdict.
• Publishes observability events to ECA for event driven automation.

Documentation

Installation, configuration, the settings reference with a screenshot of every tab, the data model and the developer surface are documented on the project site. It is built from the repository, so it describes the branch rather than the last release.

Read the documentation

Where to start

The pages an operator reaches for first.

• Installation
• Configuration
• Architecture
• Dashboard
• Traces
• Metrics
• Prometheus export
• OpenTelemetry export
• Drush commands
• For developers

Install

composer require drupal/native_observability, then enable the sub-modules you need. The documentation covers which sub-module does what and the order to turn them on.

Requirements

• PHP 8.2 or newer. This is above Drupal 10's own minimum, and it is deliberate: the code uses language features that Drupal 10 does not require.
• The zlib PHP extension. The dashboard compresses its record exports itself rather than leaving it to the web server, so the extension is a hard requirement and not an optimisation.
• The dashboard pulls Apache ECharts through wikimedia/composer-merge-plugin, configured in the dashboard's composer.libraries.json.
• The ECA bridge needs the ECA module, and only if you want event driven automation.
• OTLP push needs a reachable OTLP/HTTP collector. Grafana Alloy works without extra configuration.

Full tracing adds work to every observed request. Persistence runs at kernel.terminate, after the response has been sent, so the cost lands on tail latency rather than on the response the visitor waits for. Set retention and record limits, and write exclusion rules for the paths you do not want observed, before turning full tracing on in production.

Run drush no:overhead:measure to get that cost for your own installation. A figure measured on someone else's server does not describe yours.

Status

Stable releases on the 2.1.x branch, for Drupal 10, 11 and 12. Actively maintained by Giorgio Alfredo Pagano. Articles and measurements are on the project page on giorgiopagano.org.