One call, and you see everything that's happening in your code.

Meet omniray — OMNIVISER's X-RAY

Built and battle-tested at OMNIVISER.

---

How it works

Demo app built to show omniray(v1.0) in action — every function call traced live with timing and I/O.

• Live function, error, I/O and performance tracing in clear logs.
• Full context for you and your AI.
• No decorators, no config files — just one call.

Quick Setup

Install:

pip install omniray              # console tracing
pip install omniray[otel]        # + OpenTelemetry spans
pip install omniwrap             # wrapping engine only (custom wrappers)

Requires Python >= 3.12. omniray is built on omniwrap — installing omniray installs both.

Add to your code:

from omniwrap import wrap_all
from omniray import create_trace_wrapper

wrap_all(create_trace_wrapper())

Run your app:

OMNIRAY_LOG=true python app.py

Output:

13:44  INFO: ┌─ BigRedButton.press
13:44  INFO: ├─ ┌─ BigRedButton.pre_launch_check
13:44  INFO: │  ├─ ┌─ MissileLauncher.authenticate
13:44  INFO: │  │  └─ (52.80ms) MissileLauncher.authenticate
13:44  INFO: │  └─ (53.34ms) BigRedButton.pre_launch_check
13:44  INFO: ├─ ┌─ BigRedButton.launch_sequence
13:44  INFO: │  ├─ ┌─ MissileLauncher.arm_warhead
13:44  INFO: │  │  └─ (124.97ms) MissileLauncher.arm_warhead
13:44  INFO: │  ├─ ┌─ MissileLauncher.select_target
13:44  INFO: │  │  IN: {
13:44  INFO: │  │    "coordinates": "51.5074° N, 0.1278° W"
13:44  INFO: │  │  }
13:44  INFO: │  │  └─ (34.74ms) MissileLauncher.select_target
13:44  INFO: │  ├─ ┌─ MissileLauncher.fire
13:44  INFO: │  │  └─ (202.05ms) MissileLauncher.fire [SLOW]
13:44  INFO: │  │  OUT: {
13:44  INFO: │  │    "status": "BOOM!",
13:44  INFO: │  │    "impact": true,
13:44  INFO: │  │    "debris_radius_km": 4.2
13:44  INFO: │  │  }
13:44  INFO: │  └─ (363.92ms) BigRedButton.launch_sequence [SLOW]
13:44  INFO: └─ (418.23ms) BigRedButton.press [SLOW]

Why omniray?

• Zero-touch instrumentation — One call wraps every function and method in your codebase. No @decorator on each function, no manual setup per module.
• Live call tree — See the full call hierarchy in your terminal as it happens, with color-coded timing (green/yellow/red) and [SLOW] tags on bottlenecks. Unlike cProfile or py-spy, there's no post-mortem step.
• OpenTelemetry bridge — Flip one flag to export spans to Jaeger, Datadog, or any OTel-compatible backend. Cherry-pick which functions get spans.
• Production-safe — Never masks exceptions, never wraps dunders or properties, skips already-wrapped functions. Designed to be safe even if accidentally left on.

Features

• @trace decorator — Per-function control over logging, I/O capture, and OTel spans
• I/O logging — Log function arguments and return values for selected functions
• Conditional skip — Skip tracing for health checks or noisy functions via skip_if
• Selective OpenTelemetry — Enable OTel spans on specific functions without global overhead
• Custom wrappers — Build your own wrappers with the omniwrap engine
• Streak compaction — Hot loops collapse into one summary line (xN count, sum/mean/max stats) — N+1 patterns visible at a glance instead of drowning the trace
• Configuration — Control paths, exclusions, and behavior via pyproject.toml and env vars

Performance

~250 ns per wrapped call (omniwrap). ~17 us per traced call with console output (omniray). A typical request tracing 50 functions adds under 1 ms.

Safety

omniray never wraps: dunder methods, properties, exception classes, already-wrapped functions, imported objects, functions decorated with @trace, or its own package. Exceptions are never masked — if your function raises, the exception propagates unchanged.

Environment Variables

Variable	Type	Default	Description
OMNIWRAP	bool	false	Enable/disable wrapping when enabled=None is passed to wrap_all()

The remaining omniray flags use a tri-state system:

• true — enabled
• false — kill switch (overrides all decorator parameters, cannot be turned back on per-function)
• unset — local decides (decorator parameters or defaults apply)

Variable	Type	Default	Description
OMNIRAY_LOG	bool	unset	Console tree output
OMNIRAY_LOG_INPUT	bool	unset	Log function arguments (requires OMNIRAY_LOG)
OMNIRAY_LOG_OUTPUT	bool	unset	Log function return values (requires OMNIRAY_LOG)
OMNIRAY_LOG_COLOR	bool	true	ANSI colors in console output
OMNIRAY_LOG_STYLE	str	auto	Box-drawing style: unicode, ascii, or auto
OMNIRAY_OTEL	bool	unset	OpenTelemetry span creation

Documentation

Read the full docs — configuration, API reference, performance benchmarks, examples, and more.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache 2.0 — see LICENSE for details.