# Native Observability — Spans

The **Native Observability Spans** module introduces structured execution spans
into the Native Observability tracing system.

Spans represent measurable execution segments within a request lifecycle.
They allow developers to understand precisely **which operations occurred
during a request and how long each operation took**.

This module expands the tracing model provided by the `native_observability`
core module and enables detailed execution inspection.

The span layer is part of the broader technical snapshot exposed by the
dashboard and long-form report, helping teams understand both request
structure and execution cost.

---

# 🎯 Purpose

A request trace alone only shows **that a request happened**.

Spans make it possible to understand **what happened during the request**.

Execution spans allow developers to:

- measure internal service execution
- trace external API calls
- inspect nested operations
- analyze request performance at a granular level
- identify slow operations

Spans are the foundation for deeper observability capabilities.

---

# 🚀 Features

### Structured Execution Spans

Spans represent individual execution segments within a request.

Each span typically contains:

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

---

### Span Categorization

Spans can represent different types of operations, such as:

- request lifecycle
- service execution
- external HTTP calls
- database interactions
- custom instrumentation

This categorization allows developers to analyze request behaviour in a
structured and meaningful way.

---

### Nested Span Support

The module supports hierarchical span structures.

This allows representation of:

- parent operations
- child operations
- nested execution flows

This structure enables deeper understanding of complex request execution paths.

---

### Trace Integration

Spans are attached to request traces recorded by the Native Observability core.

Each trace may contain multiple spans describing the operations performed
during the request.

---

### Developer Instrumentation

Developers can create spans programmatically to instrument custom code.

Typical use cases include:

- measuring service execution
- profiling complex logic
- tracing integration layers
- debugging performance issues

---

# 🧩 Architecture

The span system integrates with the Native Observability tracing architecture.

Key components include:

- span recording services
- span lifecycle management
- span storage within trace payloads
- span categorization

Spans are recorded during request execution and stored together with the
request trace.

---

# 📦 Requirements

This module requires:

- Drupal 11
- `native_observability`

Optional integrations:

- `native_observability_execution`
- `native_observability_metrics`
- `native_observability_otel`

---

# ⚙️ Installation

Enable the module using Drush:

```bash
drush en native_observability_spans
