omniray

A live tracing tool for Python -- console profiling with optional OpenTelemetry tracing for omniwrap.

See the main README for full documentation.

Installation

pip install omniray

Quick Start

from omniwrap import wrap_all
from omniray import create_trace_wrapper, trace

# Auto-instrument with console profiling (OTel spans off by default)
wrap_all(create_trace_wrapper())

# Selectively enable OTel on high-value functions
@trace(otel=True)
def process_payment(order_id: str) -> bool: ...

@trace(otel=True)
async def execute_sql(query: str) -> list[dict]: ...

# Regular functions get profiling only — no OTel cost
@trace()
def validate_input(data: dict) -> bool: ...

Environment Variables

Configuration via pyproject.toml

Color thresholds for the per-segment coloring of the timing line live under [tool.omniray] in the host project's pyproject.toml. Each list defines the DIM → GREEN → YELLOW → RED boundaries for its value class.

[tool.omniray]
size = [0.1, 1, 10]              # MB: in/out payload (DIM < 0.1, GREEN < 1, YELLOW < 10, RED ≥ 10)
rss = [100, 500, 1000]           # MB: rss current / peak
rss_delta = [1, 10, 100]         # MB: RSS delta (negative / near-zero → DIM)
duration_ms = [1, 10, 100]       # ms: span duration color boundaries
size_big_tag_mb = 10             # MB: in/out size at/above which the `[BIG]` tag is appended
duration_slow_tag_ms = 200       # ms: duration at/above which the `[SLOW]` tag is appended

All keys are optional — omitted ones fall back to defaults shown above. The file is resolved by walking up from the current working directory until the first pyproject.toml is found; missing/malformed files cause silent fallback to defaults. Thresholds are loaded once at import time; restart the process to pick up changes.

License

Apache 2.0