Metadata-Version: 2.4
Name: xray-observability
Version: 1.0.0
Summary: Passive observability layer for distributed AI runtime tracing
Project-URL: Homepage, https://github.com/Ovladimirovich/xray-integration-kit
Project-URL: Repository, https://github.com/Ovladimirovich/xray-integration-kit
Project-URL: Documentation, https://github.com/Ovladimirovich/xray-integration-kit/tree/main/docs/xray
Project-URL: Changelog, https://github.com/Ovladimirovich/xray-integration-kit/blob/main/CHANGELOG.md
License: MIT
License-File: LICENSE
Keywords: ai-tracing,causal-analysis,diagnostics,distributed-tracing,monitoring,observability,opentelemetry,telemetry
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: fastapi; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pydantic; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: uvicorn; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == 'fastapi'
Requires-Dist: httpx; extra == 'fastapi'
Requires-Dist: pydantic; extra == 'fastapi'
Requires-Dist: uvicorn; extra == 'fastapi'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg">
    <img src="assets/logo.svg" width="400" alt="X-RAY">
  </picture>
</p>

<p align="center">
  <strong>Passive Observability Layer for Distributed AI Runtime Tracing</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/xray-observability/">
    <img src="https://img.shields.io/pypi/v/xray-observability?style=flat-square&logo=pypi&logoColor=white&color=00d4ff" alt="PyPI">
  </a>
  <a href="https://github.com/Ovladimirovich/xray-integration-kit/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/Ovladimirovich/xray-integration-kit/ci.yml?style=flat-square&logo=github&label=CI" alt="CI">
  </a>
  <a href="https://pypi.org/project/xray-observability/">
    <img src="https://img.shields.io/pypi/pyversions/xray-observability?style=flat-square&logo=python&logoColor=white" alt="Python versions">
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/pypi/l/xray-observability?style=flat-square&color=brightgreen" alt="License: MIT">
  </a>
  <a href="https://github.com/Ovladimirovich/xray-integration-kit/issues">
    <img src="https://img.shields.io/github/issues/Ovladimirovich/xray-integration-kit?style=flat-square" alt="Issues">
  </a>
  <a href="https://github.com/Ovladimirovich/xray-integration-kit/blob/main/CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome">
  </a>
</p>

---

## What is X-RAY?

X-RAY is a **Python library** that brings structured observability to distributed systems, AI pipelines, and multi-agent runtimes. It records execution traces, preserves causal relationships, and gives you the tools to audit, replay, and diagnose complex executions — **without modifying your application's behavior**.

Traditional logging answers _"What happened?"_ X-RAY answers:

> **"What happened, in what order, through which causal chain, and can this execution be reconstructed?"**

---

## Quick Start

```bash
pip install xray-observability
```

```python
from aethon.xray import start_trace, start_span, SpanKind

with start_trace("my_operation") as trace:
    with start_span(SpanKind.INTERNAL, "step_1") as span:
        # Your code here
        span.end(status="ok")
```

That's it. Five seconds to start tracing. No agents, no daemons, no config files.

---

## Why X-RAY?

| | OpenTelemetry | X-RAY |
|---|---|---|
| **Focus** | Telemetry collection protocol | Execution understanding & reconstruction |
| **Causal analysis** | ❌ Not built-in | ✅ Logical clocks, depth tracking, DAG validation |
| **Audit system** | ❌ | ✅ 5 integrity checks (orphans, duplicates, live-vs-disk, ...) |
| **Replay engine** | ❌ | ✅ Ordered execution timeline reconstruction |
| **Sanitizer** | ❌ | ✅ Scan, repair, cleanup orphan traces |
| **Retention policy** | ❌ | ✅ Age/count/size policies with dry-run |
| **Passive by design** | ❌ Exporter may affect perf | ✅ Never modifies application behavior |
| **Dependencies** | Heavy (protobuf, gRPC, exporter SDK) | **Zero** — pure Python stdlib |
| **Deployment** | Collector, exporters, config files | Copy the folder or `pip install` |
| **AI-native** | ❌ Designed for web requests | ✅ Designed for multi-agent, async reasoning |

**When to use OpenTelemetry:** You need standard APM, metrics export to Datadog/Prometheus, and full request tracing across HTTP boundaries.

**When to use X-RAY:** You need causal reconstruction, execution replay, integrity verification, and lightweight per-process observability — especially in AI/agentic systems where non-deterministic execution makes traditional tracing insufficient.

**You can use both.** X-RAY complements OpenTelemetry where causal depth and reconstruction matter.

---

## Architecture

```
Application Runtime
        |
        v
+---------------------------+
|         X-RAY             |
|  Passive Observability    |
+---------------------------+
        |
        +-- Trace Collector
        |     start_trace() → span hierarchy → contextvars
        |
        +-- Span Manager
        |     SpanKind (internal/server/client/producer/consumer)
        |     Logical timestamps, causal depth, parent-child
        |
        +-- Trace Store
        |     In-memory + atomic JSON persistence
        |     Index rebuild on restart
        |
        +-- Audit Engine
        |     5 integrity checks: live↔disk, orphans, duplicates, ...
        |
        +-- Sanitizer
        |     Scan → Repair → Cleanup orphan → Quarantine
        |
        +-- Replay Engine
        |     Ordered span timeline → execution reconstruction
        |
        +-- Diagnostics API
        |     Health metrics: active/completed/interrupted traces
        |
        +-- Event System
        |     Structured lifecycle events (trace created, span completed, ...)
        |
        +-- Retention Policy
              Age / count / size limits → archive → quarantine cleanup
```

---

## Core Capabilities

### 1. Distributed Trace Registration
Record execution traces with parent-child hierarchy, causal dependencies, execution depth, and logical timestamps.

```
Trace
 |
 +-- Span A
 |    |
 |    +-- Span B
 |    +-- Span C
 |
 +-- Span D (client call → external service)
```

### 2. Lifecycle Management
```
created → active → completed → persisted
            |
       interrupted → recovered
```

Detect incomplete or corrupted executions. Freeze/unfreeze/terminate trace operations.

### 3. Persistent Storage
Atomic JSON snapshot writes. Restore full state after process restart. Forensic data preservation.

### 4. Audit System
Five integrity checks: broken parent relationships, invalid lifecycle states, corrupted metadata, missing references, consistency violations.

### 5. Sanitizer
Scan, repair, or cleanup orphan/corrupted records. All operations support `?dry_run=true` for safe preview.

### 6. Replay Engine
Ordered span timeline with lifecycle reconstruction and causal analysis.

```
10:01:01  Request created
10:01:02  Agent started
10:01:05  Database operation (DB-Call)
10:01:07  Response completed
```

### 7. Event Streaming
Real-time lifecycle events (SSE): trace created, span started/completed, recovery events, persistence events.

### 8. Retention Policy
Limit storage by age, count, or size. Dry-run preview before execution. Archive-before-delete protection.

### 9. HTTP Propagation
Five canonical headers for distributed tracing across services:

| Header | Purpose |
|--------|---------|
| `X-Xray-Trace-Id` | Trace identifier |
| `X-Xray-Span-Id` | Current span identifier |
| `X-Xray-Parent-Span-Id` | Parent span identifier |
| `X-Xray-Logical-Ts` | Logical timestamp for causal ordering |
| `X-Xray-Causal-Depth` | Execution depth in the causal graph |

---

## API Overview

Once integrated into your FastAPI application:

| Endpoint | Description |
|----------|-------------|
| `GET /health` | System availability and diagnostics |
| `GET /xray/traces` | List all traces |
| `GET /xray/traces/{id}` | Trace details |
| `POST /xray/traces/{id}/freeze` | Freeze trace (prevent modification) |
| `POST /xray/traces/{id}/unfreeze` | Unfreeze trace |
| `POST /xray/traces/{id}/terminate` | Force-terminate a trace |
| `GET /xray/replay/{id}` | Execution reconstruction |
| `GET /xray/audit/{id}` | Integrity check for single trace |
| `GET /xray/audit` | Integrity check for all traces |
| `GET /xray/diagnostics` | System health metrics |
| `GET /xray/events/stream` | SSE lifecycle event stream |
| `POST /xray/sanitizer/scan` | Scan for issues |
| `POST /xray/sanitizer/repair` | Repair discovered issues |
| `POST /xray/sanitizer/cleanup-orphan` | Remove orphan records |
| `POST /xray/retention/run` | Apply retention policy |

All mutation operations support `?dry_run=true` for safe preview.

---

## Integration Examples

### 1. FastAPI Middleware

```python
from fastapi import FastAPI, Request
from aethon.xray.http_propagation import fastapi_extract_xray

app = FastAPI()

@app.middleware("http")
async def xray_middleware(request: Request, call_next):
    trace_id = fastapi_extract_xray(request)
    response = await call_next(request)
    response.headers["X-Trace-Id"] = trace_id
    return response
```

### 2. Custom Spans

```python
from aethon.xray import start_trace, start_span, SpanKind

def process_request():
    trace = start_trace("process_request")
    span = start_span(SpanKind.PROVIDER_CALL, "llm_inference")
    try:
        result = llm.query(prompt)
        span.end(status="ok", metadata={"tokens": result.tokens})
    except Exception as e:
        span.end(status="error", metadata={"error": str(e)})
    trace.end(status="ok")
```

### 3. Diagnostics & Audit

```python
from aethon.xray.trace_store import store
from aethon.xray.consistency_audit import run_all_audit_checks

# Health diagnostics
print(store.diagnostics())
# → {"active_traces": 3, "completed_traces": 42, "disk_usage_mb": 1.2}

# Integrity check
result = run_all_audit_checks("trace-123")
print(result.all_passed)
# → True
```

---

## Advanced: Why Distributed AI Needs X-RAY

Modern AI systems break traditional APM assumptions:

```
User Query
    ↓
Orchestrator
    ↓
Agent A ─────┐
Agent B ─────┼─→ Reasoning Engine → Tool Exec → Memory → Response
Agent C ─────┘
```

- Non-deterministic execution paths
- Parallel agent branches with shared state
- Async tool calls with callbacks
- Multi-step reasoning with retries and fallbacks

X-RAY captures this complexity through **causal spans** — not just timing, but the logical dependency chain that led to each outcome.

> See the [whitepaper](X-RAY_WHITEPAPER.md) for the full architectural rationale (377 pages).

---

## Testing

```bash
pip install xray-observability[dev]
python -m pytest tests/minimal_integration_test.py -v
```

### Verified scenarios
- Trace lifecycle: create → activate → complete → persist
- Persistence: save to disk → restart recovery → restore state
- Integrity: audit validation, metadata consistency, orphan detection
- Three manual scenarios: normal flow, failure+fallback, parallel chaos

---

## Documentation

| Document | Description |
|----------|-------------|
| [System Overview](docs/xray/SYSTEM_OVERVIEW.md) | Architecture and design philosophy |
| [API Specification](docs/xray/API_SPEC.md) | Full REST API reference |
| [Data Model](docs/xray/DATA_MODEL.md) | Trace, span, event schemas |
| [Operational Guarantees](docs/xray/GUARANTEES.md) | What X-RAY guarantees and what it doesn't |
| [Runbook](docs/xray/RUNBOOK.md) | Operational procedures and troubleshooting |
| [Installation Guide](docs/xray/INSTALL.md) | Detailed integration walkthrough |
| [Whitepaper](X-RAY_WHITEPAPER.md) | Full architectural rationale |
| [Changelog](CHANGELOG.md) | Release history |

All documents available in [English](docs/xray/) and [Русский](docs/xray/).

---

## How to Contribute

We welcome contributions from the community.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure all tests pass: `python -m pytest tests/ -v`
5. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## What X-RAY Is NOT

| Not this | Because |
|----------|---------|
| Decision engine | X-RAY does not make decisions, only observes |
| AI reasoning system | No inference, no ML, no optimization |
| Autonomous healer | No auto-remediation or execution control |
| Network mesh | No data-plane involvement |
| Workflow orchestrator | No execution orchestration |
| APM replacement | Complements APMs where causal depth matters |

**X-RAY transforms distributed execution from an opaque process into a measurable and reconstructable system. It does not control intelligence. It provides the infrastructure required to understand it.**

---

## License

[MIT](LICENSE) © 2026 X-RAY Contributors

---

<p align="center">
  <sub>You cannot reliably improve a system you cannot observe.</sub>
</p>
