native_observability

🚀 Overview

Native Observability introduces a structured runtime visibility layer for Drupal.
It is designed to make Drupal observable by design, providing request correlation,
structured trace storage, and execution lifecycle visibility without altering core architecture.

Modern applications require insight into how they behave under real-world conditions.
Native Observability lays the foundation for that insight directly inside Drupal.

This is not just logging.

This is execution intelligence.

The project starts with a minimal, stable tracing engine and evolves into a modular observability ecosystem.

🧠 Current Features (Phase 1 — Core Tracing Engine)

• 🆔 Unique Request Correlation ID
• 🔄 Kernel-level request/response tracing
• 🗄 Structured trace storage
• 📦 Dedicated trace database table
• ⏱ Execution duration tracking
• 🖥 Basic administrative inspection interface
• 🔎 Filtering by route, status code, and duration
• ⚙ Configurable sampling strategy
• 🔐 Granular permissions for trace access and management
• 🗑 Trace deletion capability
• ⚙ Extended tracer configuration options

Every traced request becomes an analyzable execution record.

🔥 Why It Matters

Drupal powers complex applications including API-driven platforms, enterprise portals,
high-traffic public services, and microservice integrations.
As systems grow, visibility becomes critical.

Native Observability introduces:

• 🔗 Request-level correlation
• 📚 Structured execution history
• 💾 Trace persistence
• 📊 A foundation for performance analysis
• 🌐 A base for future distributed tracing

It enables developers and architects to understand:

• ✔ What happened
• ✔ When it happened
• ✔ How long it took
• ✔ Where execution slowed down

🚧 Project Status

Work in Progress — Active Development

Native Observability has completed Phase 1: Core Tracing Engine Stabilization and
Phase 2: Service & Execution Monitoring (MVP).
The project is now entering Phase 3: Metrics Engine.

Until version 1.0.0:

• ⚠ Public APIs may evolve
• ⚠ Database schema may change
• ⚠ Configuration structure may be refined

The module is suitable for development, evaluation, and architectural experimentation.
Production hardening will follow the 1.0.0 milestone.

🗺 Roadmap

📍 Phase 1 —✅ Core Tracing Engine (Stabilized)

• 🔗 Request correlation
• 🔄 Lifecycle tracing
• 💾 Persistent structured storage
• 🖥 Basic inspection UI
• 🔐 Permissions and trace management (including deletion)
• ⚙ Configuration and UI refinements

📍 Phase 2 —✅ Service & Execution Monitoring (MVP Completed)

• 🧠 Execution Span Recorder API (internal instrumentation layer)
• 🕒 Execution timeline visualization with semantic performance bars
• 🌍 External API call tracing (external.http spans)
• 🐢 Slow service detection via duration thresholds (fast / mid / slow)
• 🌐 Automatic Guzzle http_client tracing via service decorator
• ⚡ AJAX-driven request tracing via lifecycle interception (parent request propagation + trace linking)

Phase 2 introduces execution-level visibility within a single request lifecycle.
Outbound HTTP calls are automatically traced and correlated with the current request,
marking the transition from request-level tracing to execution-aware observability.

AJAX requests can inherit a parent request correlation ID, enabling parent/child request linking and
navigation directly from the trace detail view.

📍 Phase 3 —▶️ Metrics Engine (In progress)

• 📊 Aggregated route performance
• 📈 Percentile calculations (P95 / P99)
• 📦 Throughput analysis
• 📅 Historical performance trends
• ⏰ Cron and queue tracing

📍 Phase 4 — External Integrations

• 🔌 Exporter plugin system
• 🛰 OpenTelemetry integration
• 📡 Prometheus-compatible metrics
• 📂 Elastic-compatible output

🏗 Architecture Principles

• 🧩 EventSubscriber-based lifecycle interception
• 🔧 Service container integration
• 🚫 No core overrides
• 🚫 No invasive patches
• ⚙ Progressive enablement
• 📦 Modular expansion via submodules

Native Observability is engineered to be extensible from day one.

🌟 Vision

Native Observability aims to become a foundational observability layer for Drupal 11+ projects.

Not a debugging tool.

Not just logging.

A structured, extensible runtime intelligence layer.