Installation¶

Requirements¶

Drupal 10 or 11. Every module in the family declares core_version_requirement: ^10 || ^11, and the test suite runs against both majors on every merge request, so the range is exercised rather than only declared.
PHP 8.2 or newer. composer.json requires it, so a site below that floor is refused at install time rather than failing later: the module uses readonly classes, which PHP 8.1 cannot parse. Drupal 10 itself still allows 8.1, so on that major the module is the stricter of the two.
A database supported by Drupal core (MySQL, MariaDB, PostgreSQL, SQLite). The dashboard ranks endpoint samples with a window function. MySQL 5.7 is the only server Drupal allows that has none, and only Drupal 10 allows it: Drupal 11 already requires MySQL 8.0. MariaDB, PostgreSQL and SQLite are never affected, because Drupal's own minimum for each is already above the release that introduced window functions. On MySQL 5.7 the ranking moves to PHP, the pages work, and the status report says so.

Get the code¶

composer require 'drupal/native_observability:^1.0'

First-time bootstrap¶

Drush 12+ only discovers a module's commands once that module is enabled. On a clean site, the drush no:preset:* shortcuts below do not exist yet, so the base module must be enabled manually first:

drush en native_observability -y

Every subsequent invocation, including on upgrades, finds the preset commands without this step.

Install with preset commands¶

Three Drush commands, shipped by the base module, install a whole tier in one call. Each command is idempotent: re-running it on an already-provisioned site prints "Already enabled" for the known modules and exits cleanly without error.

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`

drush no:preset:raw

drush no:preset:dashboard

drush no:preset:integrations

Tiers are cumulative: dashboard installs everything in raw plus its own modules, and integrations installs everything in dashboard plus its own. Running a later-tier preset after an earlier one has already been applied is safe; the already-enabled modules are skipped.

Module dependencies¶

Each sub-module declares its own dependencies in its .info.yml. Enabling a leaf module pulls in everything below it automatically.

Module	Depends on
`native_observability`	(none, base module)
`native_observability_spans`	`native_observability`
`native_observability_metrics`	`native_observability`
`native_observability_execution`	`native_observability`
`native_observability_cache_observer`	`native_observability`
`native_observability_database_observer`	`native_observability`
`native_observability_export`	`native_observability`, `native_observability_spans`, `native_observability_cache_observer`
`native_observability_dashboard`	`native_observability`, `native_observability_metrics`, `native_observability_execution`, `native_observability_spans`, `native_observability_cache_observer`, `native_observability_database_observer`
`native_observability_report`	`native_observability`, `native_observability_dashboard`
`native_observability_status_block`	`native_observability`
`native_observability_otel`	`native_observability`
`native_observability_eca_bridge`	`native_observability`, `native_observability_execution`, `native_observability_spans`, `eca:eca`
`native_observability_eca_bridge_demo`	`native_observability_eca_bridge`, `eca:eca_base`, `eca:eca_log`

Which ECA version the bridge needs¶

Both ECA submodules depend on the ECA contrib project, and the version is not free to choose: ECA 3 requires Drupal 11.3 and PHP 8.3, while ECA 2.1 supports Drupal 10.3 and 11 on PHP 8.1. A Drupal 10 site therefore installs ECA 2.1, and Composer picks the right line on its own from the constraint the module declares:

composer require 'drupal/eca:^2.1 || ^3'

Both lines carry the four classes the bridge builds on, so the bridge behaves the same either way. Neither submodule is enabled by any preset, and sites that do not use them need no ECA at all.

The ECA bridge demo is not part of any preset¶

native_observability_eca_bridge_demo ships five example ECA models (log all traces, log 500 errors, log slow requests, log AJAX calls, log bulk deletions). It is example content, not production functionality, so none of the three presets enable it. Turn it on explicitly:

drush en native_observability_eca_bridge_demo -y

Install Apache ECharts for the dashboard¶

native_observability_dashboard draws its charts with Apache ECharts, loaded by the dashboard library from /libraries/echarts/dist/echarts.min.js. ECharts is not a Composer dependency of the module and is not installed by any preset. DashboardLibraryAvailabilityResolver::hasEchartsLibrary() checks for dist/echarts.min.js or dist/echarts.js under libraries/echarts and the dashboard falls back to its non-chart rendering when neither is present, so a site without ECharts shows the tables and KPI cards but none of the graphs.

ECharts is published as a GitHub release rather than as a Composer package, so Composer needs a package repository entry before it can require it. The module ships that entry in modules/native_observability_dashboard/composer.libraries.json, and the supported way to use it is to let wikimedia/composer-merge-plugin merge that file into the site's own composer.json.

Three edits to the site's root composer.json. Require the plugin:

"require": {
    "wikimedia/composer-merge-plugin": "^2.1"
}

Allow it to run, because Composer blocks unlisted plugins:

"config": {
    "allow-plugins": {
        "wikimedia/composer-merge-plugin": true
    }
}

Point it at the file the module ships:

"extra": {
    "merge-plugin": {
        "include": [
            "web/modules/contrib/native_observability/modules/native_observability_dashboard/composer.libraries.json"
        ]
    }
}

Adjust that path to where the module actually lives. A site that keeps custom checkouts under web/modules/custom points there instead.

Then install:

composer require wikimedia/composer-merge-plugin
composer update apache/echarts --with-dependencies

Without the merge plugin the module's composer.libraries.json is inert: Composer never reads it, apache/echarts stays unknown, and the require fails with a package-not-found error. Copying the repository block into the site composer.json by hand also works, at the cost of a second copy to keep in step with the module.

The drupal-library type plus installer-name: echarts makes composer/installers place it at libraries/echarts, which is where the module looks. Confirm the file exists before opening the dashboard:

ls web/libraries/echarts/dist/echarts.min.js

If your site keeps libraries somewhere other than libraries/, check the installer-paths entry for type:drupal-library in the root composer.json: the module resolves the path from DRUPAL_ROOT and does not read that setting.

Cache rebuild¶

After enabling or disabling modules, rebuild caches:

drush cr

Next steps¶

See Configuration for the full permission matrix and the settings reference for every configurable module.