Skip to content

For Developers

Native Observability exposes four extension surfaces. Each targets a different kind of integration; pick the one that matches what you are building rather than reaching for the widest one available.

Events

Two Symfony events, defined in Drupal\native_observability\Event\NativeObservabilityEvents: TRACE_RECORDED fires after every request trace is persisted, TRACES_DELETED fires after a bulk purge. Use these when you need to react to trace activity from PHP code in your own module: forwarding data to another system, triggering a custom notification, keeping a derived dataset in sync. This is the same mechanism native_observability_spans uses internally to delete spans when all traces are deleted.

See Events.

Exporter plugins

Drupal\native_observability_otel\Attribute\NativeObservabilityExporter plugins, discovered under Plugin/NativeObservabilityExporter in any enabled module. Use this when you need to push captured trace data to a destination that is not Prometheus, OTLP, or Elastic: a custom webhook, a message queue, a vendor-specific ingestion API. The three shipped plugins (opentelemetry, prometheus, null_exporter) are all registered in native_observability_otel.

See Exporter plugins.

Services

A handful of services from the twelve tiered modules are declared public: true and meant to be injected by a third-party module: trace and span storage, the report builders, the dashboard section builders, the Prometheus and Elastic payload builders, the exporter manager. Most services in the family are private by design, resolved only through autowiring inside the module that declares them. Use this surface when you need to read or build on observability data programmatically, for example rendering your own summary block from TraceStorageInterface.

See Services.

ECA plugins

native_observability_eca_bridge exposes TRACE_RECORDED and TRACES_DELETED as ECA event triggers, through a single deriving plugin (native_observability, derivatives trace_recorded and traces_deleted). Use this when the reaction to a trace event belongs in a no-code ECA model rather than in a custom PHP subscriber, for example alerting on 500 responses or slow requests through the ECA UI. The bundled native_observability_eca_bridge_demo module ships five ready-made rules of this kind.

See ECA plugins.

Choosing between them

  • Reacting to trace activity in PHP you control: an event subscriber (see Events).
  • Reacting to trace activity without writing PHP: an ECA model (see ECA plugins).
  • Pushing traces to a new external system: an exporter plugin (see Exporter plugins).
  • Reading or building on stored observability data from your own service: inject one of the public services (see Services). Drupal