utrompulse 0.1.0

High-fidelity OpenTelemetry (OTel) bridge for MuJoCo. Industrial-grade observability for agentic robotics.

utrompulse (v0.2.0)

A high-performance, asynchronous telemetry framework for MuJoCo simulations. utrompulse decouples physics computation from observability I/O, providing semantically labeled telemetry via OpenTelemetry (OTLP) and local binary logging (MCAP).

Key Features

• Zero-Blocking Architecture: High-frequency state extraction (<50μs) to preserve physics determinism.
• Semantic Instrumentation: Automatically maps raw mjData indices to human-readable XML joint and actuator names.
• Multiplexed Transports: Simultaneously stream to live OTLP backends (Jaeger) and local disk (MCAP/Foxglove).
• Real-Time Safety: Implements a Head-Dropping Circular Buffer to ensure telemetry freshness without memory overflows.

Architecture

utrompulse utilizes an air-gapped dispatcher model to isolate the simulation thread:

1. ModelInstrument: Inspects the mjModel at runtime to create a semantic name-to-index map.
2. ZeroBlockingHook: Captures state snapshots and pushes them into a thread-safe circular queue.
3. PulseExporter: A background daemon that broadcasts snapshots to all registered BaseTransport backends.

Installation

Ensure you have Python 3.11+ and uv installed.

git clone [https://github.com/mustafa-5493/UtromPulse.git](https://github.com/mustafa-5493/UtromPulse.git)
cd UtromPulse
uv sync

Usage

Modern usage involving semantic mapping and multiple transport outputs:

import mujoco
from utrompulse.bridge.mujoco_hook import ZeroBlockingHook
from utrompulse.bridge.instrumentation import ModelInstrument
from utrompulse.telemetry.otel_exporter import PulseExporter
from utrompulse.transports.otlp import OTLPTransport
from utrompulse.transports.mcap import MCAPTransport

# 1. Load Model
model = mujoco.MjModel.from_xml_path("robot.xml")
data = mujoco.MjData(model)

# 2. Initialize Instrumentation & Hook
instrument = ModelInstrument(model)
hook = ZeroBlockingHook(max_queue_size=5000)

# 3. Configure Transports (Live + Local)
transports = [
    OTLPTransport(endpoint="http://localhost:4317"),
    MCAPTransport(output_path="recording.mcap")
]

# 4. Start Exporter
exporter = PulseExporter(telemetry_queue=hook.telemetry_queue, transports=transports)
exporter.start()

try:
    while True:
        mujoco.mj_step(model, data)
        # Capture state with semantic labels
        hook.capture_state(step=data.time, data=data, instrument=instrument)
finally:
    exporter.stop()

Observability Backends

Live Tracing (Jaeger)

Run Jaeger with OTLP support:

docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one:latest

Access the UI at http://localhost:16686 to view semantically labeled spans (e.g., joint.left_hip_pitch).

Offline Analysis (Foxglove)

The MCAPTransport generates a .mcap file. Drag and drop this file into Foxglove Studio to visualize high-frequency joint data, control signals, and system jitter offline.