# Native Observability

**Native Observability brings structured, request-level observability directly inside Drupal.**

No external agents.  
No heavy APM stack.  
No vendor lock-in.

This project introduces a native observability layer built specifically for **Drupal 11**, enabling request tracing,
execution monitoring, metrics aggregation, reporting, and telemetry export directly from the application runtime.

Instead of relying on external APM systems, **Native Observability integrates observability capabilities directly into
Drupal's architecture**.

---

# 🎯 Vision

Modern Drupal applications require deep runtime introspection in order to:

- understand request lifecycle behaviour
- measure performance bottlenecks
- inspect internal service execution
- trace external API calls
- correlate AJAX and sub-requests
- analyze performance trends
- generate structured technical reports
- export telemetry to external monitoring platforms

Native Observability provides all of this **natively inside Drupal**, without requiring external agents or invasive
instrumentation.

---

# 🚀 Global Features

Native Observability provides a complete observability stack composed of:

## Request Tracing
- ULID based Request IDs
- Kernel request lifecycle tracing
- Parent / child request correlation
- AJAX request correlation
- Correlation ID injected in response headers

## Execution Instrumentation
- Execution Span Recorder API
- Service execution tracking
- HTTP client tracing
- External API instrumentation
- Span categorization

## Trace Visualization
- Trace list UI
- Trace detail inspection
- Execution timeline visualization

## Performance Metrics
- Route aggregation
- Throughput analysis
- Percentile calculation (P95 / P99)

## Observability Reporting
- Report builder UI
- Printable HTML reports
- KPI summaries
- Technical appendices

## Telemetry Export
- OpenTelemetry exporter
- Prometheus endpoint

---

# 🧱 Architecture Overview

Core contracts:

- TraceRecorderInterface  
- TraceStorageInterface  
- RequestIdGeneratorInterface  
- ExecutionSpanRecorder  

All services follow Drupal 11 best practices.

---

# 🧩 Module Architecture

## Core Module

### native_observability
Core tracing infrastructure.

---

## Extension Modules

### native_observability_execution
Execution tracing.

### native_observability_spans
Span management.

### native_observability_metrics
Performance metrics.

### native_observability_otel
Telemetry export.

### native_observability_status_block
Admin diagnostics.

### native_observability_dashboard
Provides the main observability dashboard UI.

Features:
- Aggregated metrics visualization
- Route performance tables
- AJAX and request analysis
- Cache and database insights
- Technical insight panels

This module acts as the **central visualization layer** of the system.

### native_observability_report
Structured reporting and printable HTML export.

---

# 📦 Installation

## Requirements

- Drupal 11
- PHP 8.2+
- Database (MySQL / MariaDB / PostgreSQL)

## Install via Composer

composer require drupal/native_observability

## Enable modules

drush en native_observability

Recommended:

drush en native_observability_execution
drush en native_observability_spans
drush en native_observability_metrics
drush en native_observability_dashboard
drush en native_observability_report

Optional:

drush en native_observability_otel
drush en native_observability_status_block

## Cache rebuild

drush cr

---

# 🖨️ Report Export

Reports are generated as printable HTML.

Workflow:
1. Generate preview
2. Open printable HTML
3. Use browser print → Save as PDF

---

# 🧠 Philosophy

Observability should be part of the application architecture itself.
