SSL-ACTX/ocular: Ultra-low overhead PEP 669 instruction-level tracer and telemetry engine for Python 3.12+. Built with Rust for hardware cycle accuracy (TSC) and dynamic de-instrumentation. · GitHub

Ocular is a high-performance tracing and profiling runtime built in Rust, designed exclusively for Python 3.12+ via the PEP 669 (sys.monitoring) API.

It bridges the gap between deep, instruction-level visibility and production-grade performance. By utilizing lock-free zero-allocation pipelines and hardware-level cycle counting, Ocular observes Python's execution state without destroying its speed.

Ocular operates in two primary modes:

• Statistical Profiling (Adaptive): Dynamically unhooks from hot loops once a statistical threshold is reached, allowing Python's Specializing Adaptive Interpreter to resume native optimizations (achieving near-zero or even negative overhead).
• Chronological Tracing (Full): Captures a flawless, gapless timeline of every opcode, jump, and function call for deep offline analysis.

• Hardware Cycle Accuracy: Bypasses expensive OS system clock calls, using hardware Time Stamp Counters (TSC) for ultra-low-overhead, nanosecond-precision execution timing.
• Zero-Allocation FFI Pipeline: Uses crossbeam lock-free queues, object pools, and batched FFI transitions to completely eliminate heap allocation in the tracing hot path.
• Dynamic De-instrumentation: Automatically detects hot loops and returns DISABLE to the Python VM after a configurable threshold, gracefully stepping out of the way of CPython's JIT/quickening optimizations.
• Hot Trace Disassembly: Maps runtime traces back to specific file lines and base-to-specialized opcode transitions (e.g., BINARY_SUBSCR -> BINARY_SUBSCR_LIST_INT).
• Perfetto Export: Natively generates Chrome Perfetto (.json) traces for visualizing function execution, loop micro-ops, and call stack hierarchies.

Ensure you have Rust and a Python 3.12+ virtual environment active.

pip install maturin
maturin develop --release

import ocular
import time

def hot_loop_workload(limit):
    total = 0
    for i in range(limit):
        total += i * 2
    return total

# Start Ocular with adaptive de-instrumentation (threshold=500)
# This profiles the first 500 iterations, then drops overhead to zero.
ocular.start_tracing(mode="precise", perfetto=True, deinstrument_threshold=500)

start = time.time()
result = hot_loop_workload(1_000_000)
print(f"Elapsed: {time.time() - start:.4f}s")

# Stops tracing and flushes the telemetry worker queue
ocular.stop_tracing()

• Full Architecture Reference
• Usage Examples & API Guide
• Understanding Dynamic De-instrumentation
• Exporting and Viewing Perfetto Timelines