Skip to content

ECA bridge

The native_observability_eca_bridge submodule exposes trace signals as ECA (Event-Condition-Action) events. It is part of the INTEGRATIONS preset (drush no:preset:integrations).

The optional native_observability_eca_bridge_demo submodule ships five ready-made ECA models. It is not included in any preset (RAW, DASHBOARD, or INTEGRATIONS) and must be enabled manually.

Routes

The bridge defines no routes of its own. ECA models built on top of it are managed through the ECA module's own admin UI at /admin/config/workflow/eca, which requires drupal/bpmn_io for the visual editor and the ECA module's own permissions.

Events exposed to ECA

NativeObservabilityEvent (plugin ID native_observability, deriver NativeObservabilityEventDeriver) wraps the two Symfony events dispatched by native_observability:

ECA trigger Symfony event Fires when
Trace recorded (native_observability:trace_recorded) native_observability.trace_recorded An HTTP request trace is persisted
Traces deleted (native_observability:traces_deleted) native_observability.traces_deleted All traces are bulk-deleted via the admin UI or Drush

Route exclusion is handled upstream: when capture.exclude_own_routes is enabled (the default), the base TraceSubscriber never dispatches TraceRecordedEvent for native_observability* routes, so the bridge needs no additional guard.

Tokens

All tokens are available under the [event:*] prefix.

Token Fires on Description
[event:machine_name] both Machine name of the event variant that fired
[event:route] trace_recorded Drupal route machine name
[event:method] trace_recorded HTTP method, upper case
[event:status_code] trace_recorded HTTP response status code
[event:duration_ms] trace_recorded Request duration in milliseconds
[event:is_ajax] trace_recorded 1 or 0
[event:deleted_count] traces_deleted Number of deleted trace records

ECA requires each Symfony event name to map to exactly one plugin definition, so there is no separate "slow request" trigger. Threshold filtering (for example duration_ms >= 3000) is expressed as an ECA condition on [event:duration_ms] attached to the trace_recorded trigger.

Building a model

flowchart LR
    A[TraceSubscriber persists trace] --> B[TraceRecordedEvent dispatched]
    B --> C[NativeObservabilityEvent: trace_recorded]
    C --> D{Condition, e.g. eca_scalar on duration_ms}
    D -- match --> E[Action, e.g. eca_write_log_message]
    D -- no match --> F[No action]

Steps in the BPMN.io modeler:

  1. Add a Start event, set its plugin to Native Observability > Trace recorded.
  2. Optionally attach a Condition to the outgoing sequence flow, plugin eca_scalar, comparing [event:duration_ms], [event:status_code], or [event:is_ajax] against a value.
  3. Add a Task, set its plugin to an ECA action such as eca_write_log_message (requires eca_log), and reference tokens like [event:route], [event:method], and [event:status_code] in the message.
  4. Save the model, then generate traffic and check the target action fired (for example /admin/reports/dblog filtered by the configured channel).

Models can also be deployed as configuration YAML under config/install/eca.eca.{machine_name}.yml in a custom module. The five files shipped by native_observability_eca_bridge_demo are the authoritative, up-to-date shape for this format.

Demo module

native_observability_eca_bridge_demo depends on native_observability_eca_bridge, eca_base, and eca_log. It installs five ECA config entities, all logging to the watchdog channel native_observability:

Config entity Trigger Condition
eca.eca.no_demo_log_all_traces trace_recorded none, logs every trace
eca.eca.no_demo_500_errors trace_recorded status_code = 500
eca.eca.no_demo_slow_requests trace_recorded duration_ms >= 3000
eca.eca.no_demo_ajax_requests trace_recorded is_ajax = 1
eca.eca.no_demo_traces_deleted traces_deleted none, logs the deleted count

Install it explicitly:

drush pm:install native_observability_eca_bridge_demo -y

Verify with:

drush config:get eca.eca.no_demo_log_all_traces id
drush watchdog:show --type=native_observability --count=20

no_demo_log_all_traces logs one watchdog entry per traced request. Keep the demo module for validation and examples; copy only the rules needed into project-specific configuration before enabling it on a production site with meaningful traffic.