# Native Observability Execution

The **Native Observability Execution** module introduces execution-level
instrumentation to the Native Observability tracing system.

While the core module records request traces, this module provides
visibility into **what happens during request execution**, capturing
detailed runtime information about internal services, external API calls,
and nested execution flows.

This module enables developers to analyze request performance at a
much deeper level by recording structured **execution spans**.

---

## Overview

The execution module extends the Native Observability tracing architecture
by introducing an **Execution Span Recorder**.

Execution spans represent measurable runtime segments that occur during
request processing.

These spans allow the observability system to capture:

- internal service execution
- external HTTP requests
- nested operations
- execution timing for specific components

This provides detailed insight into how Drupal processes each request.

---

## Features

The module introduces several important runtime observability capabilities.

### Execution Span Recorder

The module provides a span recording system used to instrument execution
segments during a request lifecycle.

Each span records:

- span identifier
- span category
- start timestamp
- end timestamp
- execution duration
- parent span relationship

This allows the tracing system to reconstruct execution flows.

---

### Execution Timeline Visualization

Execution spans are visualized inside the trace detail interface as a
timeline.

The timeline allows developers to quickly identify:

- slow services
- expensive operations
- execution order of internal components

Each span is displayed with a visual duration bar to highlight execution
cost.

---

### Slow Service Detection

Execution spans are classified based on their duration.

Typical classifications include:

- fast operations
- medium duration operations
- slow operations

This allows the observability UI to highlight performance bottlenecks
during trace inspection.

---

### External HTTP Call Tracing

The module automatically instruments Drupal's HTTP client.

External API calls made using the Drupal HTTP client are captured
as execution spans.

This allows developers to identify:

- slow external APIs
- third-party latency
- network bottlenecks

---

### Automatic HTTP Client Instrumentation

The module decorates Drupal's `http_client` service and injects a
middleware layer that automatically records HTTP execution spans.

This instrumentation is transparent and does not require changes
to existing code.

---

### AJAX Request Correlation

The execution module supports correlation between parent requests
and AJAX sub-requests.

When an AJAX request is triggered from a parent page request, the
observability system links the two traces together.

This allows developers to navigate between related traces and
understand the complete execution flow.

---

## Architecture

The execution module introduces several core components:

### ExecutionSpanRecorder

Responsible for recording execution spans during request processing.

It provides an API used by internal instrumentation layers.

---

### HTTP Client Decorator

Decorates Drupal's HTTP client and automatically instruments
external HTTP requests.

---

### Execution Timeline Builder

Transforms recorded spans into visual timeline elements used
by the trace detail interface.

---

### Span Classification Logic

Classifies spans based on execution duration to highlight slow
operations.

---

## Requirements

This module requires:

- **native_observability**

Optional integrations:

- **native_observability_spans**
- **native_observability_metrics**
- **native_observability_otel**

---

## Usage

Once enabled, the module automatically instruments execution
events during request processing.

Execution spans will appear in the **Trace Detail** interface
provided by the Native Observability administration UI.

Developers can also create custom spans programmatically using
the execution span recorder.

---

## Use Cases

Typical use cases include:

- analyzing slow request execution
- identifying expensive services
- debugging performance issues
- tracing external API calls
- profiling complex business logic

---

## Part of the Native Observability Ecosystem

This module is part of the Native Observability platform.

Core module:

- `native_observability`

Extension modules:

- `native_observability_execution`
- `native_observability_spans`
- `native_observability_metrics`
- `native_observability_otel`
- `native_observability_status_block`

Together these modules provide a complete observability stack
directly inside Drupal.
