Versions

This documentation describes the 2.2.x branch.

Which branch to install

Branch	Latest tag	Drupal	Status
2.2.x	2.2.0	10, 11 and 12	Current. Install this one.
2.1.x	2.1.1	10, 11 and 12	Supported, superseded by 2.2.x.
2.0.x	2.0.1	10 and 11	Not supported.
1.1.x	1.1.2	10, 11 and 12	Not supported.
1.0.x	1.0.11	10 and 11	Not supported.

Every branch requires PHP 8.2 or newer. The MCP submodule of 2.2.x is the exception: it needs Drupal 11 and PHP 8.3, see Native Observability via MCP.

Moving to 2.2.x

A site on 1.1.x, 2.0.x or 2.1.x goes straight to 2.2.x. Take a backup, then run drush updb -y, drush cr and drush cex -y, and commit the exported configuration: a sync directory exported before the upgrade would drop the new exposure settings and stop exports without a message. Sites with the export or OpenTelemetry module keep sending in legacy mode until a grade is chosen on the External exposure page. The full list of updates and behavior changes is in the release notes.

What changes for a site:

• External exposure. A new page and the permission administer native observability exposure decide what leaves the site. Grade 0 stops the Prometheus endpoint (403) and OpenTelemetry. See External exposure.
• Prometheus. The route_path_method label strategy and the path label are gone. Update native_observability_export_update_10003 switches such a site to route_only, so the series change identity and queries or dashboards that filter on path have to be rewritten. Requests with no matching route are counted under route="unknown".
• OpenTelemetry. Spans no longer carry url.path or the exception message. http.route holds the route machine name.
• Stored data. Paths are redacted, the trace payload loses uid and client_ip (both stay in their columns) and gains query_keys, exception messages and outbound URLs are redacted, and the sensitive-key list has new defaults. The IPv6 anonymization keeps a /64.
• Client IP hash salt. It moves from the configuration to State. A site with an empty salt gets a new random one, and hashes stored before are not comparable with the new ones.
• Metrics. Rows keyed by a visitor path are merged into the unmatched row. Missed 5-minute windows are aggregated on the next cron run.
• Cache Observer. It no longer needs Spans, and the MCP tools report an uncacheable error response as error_response.
• Database observer. store_slow_query_text stays on for existing sites and the status report warns about it. Literals in stored SQL are replaced by ?.
• MCP. The optional submodule native_observability_mcp is new. It needs Drupal 11 and PHP 8.3.
• Developers. OverheadMeasurementBatch is replaced by the service native_observability.overhead_measurement_operations. The constant LivePrometheusMetricsReader::LABEL_ROUTE_PATH_METHOD stays as a deprecated alias of LABEL_ROUTE_ONLY. See Services.

Moving from 2.0.x to 2.1.x

Run drush updb after deploying the files. Up to three updates run, depending on the sub-modules installed, and one of them rewrites stored data:

• native_observability_update_10107 adds the capture.redact_sensitive_keys switch, on, and the capture.sensitive_keys list with its defaults, only where they are missing. A value already stored is left as it is.
• native_observability_spans_update_10107, if the spans module is installed, redacts credentials and sensitive query keys already stored in outbound HTTP spans: the uri, url, target, host and error_message payload keys and the span name. The original values are not kept. With capture.redact_sensitive_keys off it changes nothing.
• native_observability_cache_observer_post_update_environment_inspector_arguments is empty. It makes drush updb rebuild the container, because a service constructor changed.

One setting changes meaning. max_stored_queries_per_request set to 0 used to store no slow query at all. It now stores all of them. If you set 0 to store nothing, turn the database observer capture off instead.

Sensitive keys now match on name segments instead of substrings. A parameter such as author is no longer redacted, while key, sid and sig now are. Edit capture.sensitive_keys if your site needs a different list. Anonymous requests no longer start a session for the execution history.

Moving from 1.1.x to 2.0.0

The routes, the dashboard tabs and the menu links are byte-identical between 1.1.x and 2.0.0. Nothing in the interface moves. One setting does have to be set again, and the report gains a section it did not have: both are described first below.

What changed:

• The report measures the overhead instead of estimating it. 1.1.x published a percentage summed from four hardcoded constants, printed as "Estimated overhead: 10%". No constant in it was measured, and the figure described no installation. That code is gone. 2.0.0 measures the module's own cost on the server it runs on, from drush no:overhead:measure or from Configuration > Development > Native Observability > Overhead measurement, and publishes the result with a label naming where the number came from.
• The overhead section starts hidden after the upgrade, and that is deliberate. native_observability_report_update_10102 resets the publication state to hidden on every existing site, so no site keeps publishing the old invented percentage. To show a figure again, either run a measurement and record it, or declare one by hand in the report settings. This is the one setting an administrator has to set again.
• Anything that read the estimate directly is a breaking change. ObservabilityImpactEstimator, the estimated_overhead_percent and impact_level config keys and the sections.overhead narrative block are removed, with no replacement value to migrate to: the number they held was never measured. Sites that overrode the report message keys the overhead section used lose those overrides.
• The configuration schema gained validation. Five capture keys now declare their allowed values, so an imported configuration file with client_ip_mode: invented is rejected at import time instead of being stored. No existing valid value is affected.
• The database observer report page shows 100 rows where it used to show 50.
• A database without window functions is handled. The dashboard ranks endpoint samples with ROW_NUMBER() OVER (PARTITION BY ...). MySQL 5.7 has no window functions and Drupal 10 still allows it, so on that server the ranking moves to PHP and the status report says so. See Installation for the full list of database versions.
• Spans recorded outside a web request stay visible. An outbound call made by cron or by drush has no request behind it. Those spans are still counted in the Response Time breakdown on the dashboard, which is how a command-line call shows up at all.

The Cache tab reports which server the site is connected to. That connection is what the module asks about window functions, rather than reading the Drupal version.

The card now states what the breakdown covers, so the Outbound HTTP slice is not read as request time alone.

One break for module developers

ObservabilityCleanupHandlerInterface now declares timestampColumn(): string. A cleanup handler outside this module has to implement it.

public function timestampColumn(): string {
  return 'created_at';
}

Return the literal column name your retention logic filters and orders by. Do not probe the schema for a set of candidate names and use whichever one exists: the handler and the table then disagree without anyone noticing, which is the failure this method exists to prevent.

Nothing else in the public API changed. A site that does not implement that interface has no work to do.

Upgrade path

composer require 'drupal/native_observability:^2.2'
drush updb -y
drush cr

The update hooks migrate configuration in place. Running drush updb a second time reports nothing left to do.