Metadata-Version: 2.4
Name: agent-rl-observability
Version: 0.2.2
Summary: Agent-RL Observability SDK — lightweight OpenTelemetry-based tracing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.25.0
Requires-Dist: opentelemetry-sdk>=1.25.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25.0
Provides-Extra: auto
Requires-Dist: httpx>=0.27.0; extra == "auto"
Requires-Dist: wrapt>=1.14.0; extra == "auto"
Provides-Extra: full
Requires-Dist: agent-rl-observability[auto]; extra == "full"
Requires-Dist: fastapi>=0.75.2; extra == "full"
Requires-Dist: starlette>=0.27.0; extra == "full"

# agent-rl-observability

轻量级可观测性 SDK，基于 OpenTelemetry，为 Agent-RL 平台提供分布式追踪能力。

## 安装

```bash
pip install agent-rl-observability
# 启用自动埋点（httpx 等第三方库）
pip install agent-rl-observability[auto]
# 启用完整功能（含 FastAPI 可视化端点）
pip install agent-rl-observability[full]
```

## 快速开始

```python
from observability import setup_otel, trace, trace_span

setup_otel()

@trace("my.service.action")
def my_function():
    with trace_span("sub.operation"):
        pass
```

## 功能

| 模块 | 说明 |
|------|------|
| `core` | OTel 初始化、装饰器、TraceContext 传播、配置 |
| `auto_instrumentation` | httpx / requests / aiohttp / aiomysql / redis / aiokafka 自动埋点 |
| `middleware` | FastAPI / Starlette ASGI 中间件 |
| `api` | Trace 查看、瀑布图可视化、耗时分析端点 |
| `collector_protocol` | 与 Collector 服务的数据契约 |

## 配置

通过环境变量配置：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OTEL_SERVICE_NAME` | `"unknown"` | 服务名 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `"http://localhost:4318"` | OTLP 导出地址 |
| `OBS_DISABLED` | `"false"` | 禁用可观测性 |

## 架构

```
业务服务 ──OTLP──▶ Collector 服务 ──▶ OceanBase / 告警
    ↑
@trace / trace_span / AutoTraceMiddleware
```
