# Native Observability Metrics

The **Native Observability Metrics** module provides aggregated performance
metrics for Drupal routes based on trace data collected by the
Native Observability ecosystem.

This module introduces the **Metrics Engine (Phase 3)** of the Native
Observability architecture.

It aggregates request traces and calculates key performance indicators
such as latency percentiles and throughput, exposing them through an
administrative dashboard.

---

## Overview

Native Observability Metrics transforms raw request trace data into
aggregated route-level performance insights.

The module processes trace data collected by the Native Observability
tracing engine and computes statistical metrics for completed
aggregation windows.

These metrics are stored and exposed through a Drupal-native
administrative dashboard.

---

## Features

The module currently provides:

- Aggregated **route-level metrics**
- **Throughput tracking** (requests per minute)
- **Average response duration**
- **Latency percentiles** (P95 / P99)
- **Historical aggregation windows**
- **Manual metrics aggregation**
- **Cron-based aggregation**
- **Metrics dashboard with visual summaries**
- **Metrics retention and cleanup integration**

Metrics are derived directly from trace data recorded by the
Native Observability tracing subsystem.

---

## Metrics Dashboard

The module exposes an administration dashboard at:

/admin/reports/native-observability/metrics

The dashboard provides:

### Summary metrics

Quick overview cards showing:

- Total requests
- Average response duration
- Maximum P95 latency
- Maximum P99 latency
- Peak throughput

### Visual charts

The dashboard includes graphical visualizations such as:

- **Requests by route**
- **Average response duration by route**

These charts help identify the most active or slowest routes
within the latest aggregation window.

### Detailed metrics table

The dashboard also includes a full metrics table displaying:

- Route
- Request count
- Throughput per minute
- Average duration
- P95 latency
- P99 latency

---

## Aggregation model

Metrics are calculated using **aggregation windows**.

Each window represents a completed time interval where
trace data is processed and converted into aggregated
route-level metrics.

The dashboard always displays metrics for the **latest
completed window**, ensuring consistent and stable metrics.

---

## Running aggregation

Metrics aggregation can be triggered in two ways:

### Automatic aggregation (cron)

The module implements a cron hook which periodically
aggregates trace data into metrics snapshots.

drush cron

### Manual aggregation

Administrators can run aggregation directly from the
Metrics dashboard using the **Run aggregation now** action.

This action aggregates the **latest completed window**.

---

## Data storage

Aggregated metrics are stored in the database table:

native_observability_route_metric

Each record represents a snapshot of route-level metrics
for a specific aggregation window.

---

## Retention and cleanup

Metrics snapshots are integrated with the Native Observability
cleanup system.

Administrators can configure retention policies and run
manual cleanup operations through the Observability
configuration interface.

---

## Architecture

The module introduces several core components:

### RouteMetricsAggregator

Responsible for transforming trace data into aggregated
route metrics.

Key responsibilities:

- calculating request counts
- computing throughput
- calculating average response duration
- calculating P95 and P99 percentiles

### DatabaseMetricsStorage

Handles persistence and retrieval of aggregated
metrics snapshots.

### Metrics Dashboard Controller

Provides the administrative dashboard displaying
aggregated metrics.

---

## Requirements

This module requires:

- **Native Observability (core module)**
- **Trace data collection enabled**

Metrics are generated from trace data, therefore the
tracing subsystem must be active.

---

## Roadmap

The Metrics Engine is part of the broader
Native Observability architecture.

Future enhancements may include:

- historical metrics visualization
- time-series trend charts
- route filtering
- export capabilities
- advanced observability dashboards

---

## Maintainers

Native Observability is an experimental observability
stack for Drupal designed to provide deep request-level
insight without requiring external monitoring systems.

## Drush command: metrics aggregation

The module provides a Drush command to execute route metrics aggregation from
the command line.

This command is intended for development, diagnostics, and manual validation
workflows. It triggers the same aggregation pipeline used by the administrative
metrics interface and stores a new aggregated snapshot in the metrics storage.

### Command

```bash
drush native-observability-metric:aggregate
