modaltrace 0.1.0__tar.gz

modaltrace-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -v --tb=short
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv pip install -e ".[dev]" --system
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/

modaltrace-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Claude Code
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# OS
+.DS_Store
+
+# Coverage
+.coverage
+htmlcov/
+
+# Environment
+.env

modaltrace-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

modaltrace-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: modaltrace
+Version: 0.1.0
+Summary: OpenTelemetry observability library for real-time AI applications
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: wrapt>=1.16.0
+Provides-Extra: all
+Requires-Dist: aiortc>=1.9.0; extra == 'all'
+Requires-Dist: pynvml>=11.5.0; extra == 'all'
+Requires-Dist: torch>=2.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: pynvml>=11.5.0; extra == 'gpu'
+Provides-Extra: pytorch
+Requires-Dist: torch>=2.0.0; extra == 'pytorch'
+Provides-Extra: webrtc
+Requires-Dist: aiortc>=1.9.0; extra == 'webrtc'

modaltrace-0.1.0/README.md

@@ -0,0 +1,224 @@
+# ModalTrace
+
+<div align="center">
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI version](https://img.shields.io/pypi/v/modaltrace.svg)](https://pypi.org/project/modaltrace/)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue)](https://www.python.org/downloads/)
+[![CI Status](https://github.com/arnabdeypolimi/video-ai-telemetry/actions/workflows/ci.yml/badge.svg)](https://github.com/arnabdeypolimi/video-ai-telemetry/actions)
+
+**OpenTelemetry observability for real-time AI video applications**
+
+[Documentation](https://github.com/arnabdeypolimi/video-ai-telemetry/wiki) • [Issues](https://github.com/arnabdeypolimi/video-ai-telemetry/issues) • [Contributing](./CONTRIBUTING.md)
+
+</div>
+
+---
+
+## 🚀 What is ModalTrace?
+
+ModalTrace is an open-source OpenTelemetry library that provides production-grade observability for real-time AI video applications. It captures traces, metrics, and logs across your entire ML pipeline—from GPU operations and neural network inference to video rendering and transport layer performance.
+
+Built for **production AI systems**, ModalTrace helps you understand latency bottlenecks, monitor resource utilization, and debug performance issues in complex distributed video AI pipelines.
+
+---
+
+## ✨ Features
+
+**📊 Comprehensive Observability**
+Trace execution paths across your entire pipeline with automatic span generation for each processing stage. Correlate traces with structured logging and metrics for complete visibility.
+
+**⚡ Real-time Metrics**
+Monitor frame rates, GPU memory allocation, inference latency, and synchronization drift with sub-millisecond precision. Built-in ring buffer aggregation for efficient metric collection.
+
+**🔍 Semantic Conventions**
+All telemetry uses standardized attribute keys (`modaltrace.*`) eliminating magic strings and enabling consistent instrumentation across teams.
+
+**🧠 PyTorch & GPU Instrumentation**
+Automatic instrumentation of PyTorch operations, GPU memory tracking, and device utilization metrics. Understand exactly where your model is spending time.
+
+**🎬 Audio/Video Synchronization Tracking**
+Detect and monitor A/V sync drift with configurable thresholds. Automatically log chunk mismatches and jitter metrics.
+
+**🎯 Adaptive Sampling**
+Intelligent span sampling based on anomaly detection. Automatically capture high-latency frames and unusual execution patterns without overwhelming your backend.
+
+**🛡️ PII Scrubbing**
+Built-in scrubbing pipeline removes sensitive data from logs and attributes. Customizable patterns for your specific compliance needs.
+
+**📡 OpenTelemetry Export**
+Native support for OTLP over HTTP and gRPC. Export to any OpenTelemetry-compatible backend: Jaeger, Datadog, New Relic, Honeycomb, or on-prem observability stacks.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+pip install modaltrace
+```
+
+For optional features:
+
+```bash
+pip install modaltrace[pytorch,gpu,webrtc]
+```
+
+### 2. Configure & Initialize
+
+Create a `.env` file or set environment variables:
+
+```bash
+MODALTRACE_SERVICE_NAME=my-video-pipeline
+MODALTRACE_OTLP_ENDPOINT=http://localhost:4318
+MODALTRACE_PYTORCH_INSTRUMENTATION=true
+MODALTRACE_GPU_MONITORING=true
+```
+
+Initialize the SDK in your application:
+
+```python
+from modaltrace import ModalTraceSDK
+
+sdk = ModalTraceSDK()
+sdk.start()
+
+# Your ML pipeline code here
+# Spans are automatically created for instrumented operations
+```
+
+### 3. View Telemetry
+
+Access your traces at your observability backend (e.g., `http://localhost:16686` for Jaeger):
+
+```python
+# Start a pipeline span
+from modaltrace import get_tracer
+tracer = get_tracer(__name__)
+
+with tracer.start_as_current_span("process_frame") as span:
+    span.set_attribute("modaltrace.pipeline.frame.sequence_number", frame_id)
+    # Your frame processing logic here
+```
+
+---
+
+## ⚙️ Configuration
+
+All configuration is available via environment variables (prefix: `MODALTRACE_`) or Python kwargs to `ModalTraceConfig`:
+
+| Setting | Env Variable | Type | Default | Description |
+|---------|-------------|------|---------|-------------|
+| **Service Identity** |
+| `service_name` | `MODALTRACE_SERVICE_NAME` | str | `modaltrace-pipeline` | Service identifier in telemetry |
+| `service_version` | `MODALTRACE_SERVICE_VERSION` | str | `0.0.0` | Semantic version of your service |
+| `deployment_environment` | `MODALTRACE_DEPLOYMENT_ENVIRONMENT` | str | `development` | Environment (dev/staging/prod) |
+| **OTLP Export** |
+| `otlp_endpoint` | `MODALTRACE_OTLP_ENDPOINT` | URL | `http://localhost:4318` | OpenTelemetry collector endpoint |
+| `otlp_protocol` | `MODALTRACE_OTLP_PROTOCOL` | str | `http` | Protocol: `http` or `grpc` |
+| `otlp_timeout_ms` | `MODALTRACE_OTLP_TIMEOUT_MS` | int | `10000` | Export timeout in milliseconds |
+| **Feature Flags** |
+| `pytorch_instrumentation` | `MODALTRACE_PYTORCH_INSTRUMENTATION` | bool | `true` | Auto-instrument PyTorch ops |
+| `gpu_monitoring` | `MODALTRACE_GPU_MONITORING` | bool | `true` | Track GPU metrics |
+| `webrtc_monitoring` | `MODALTRACE_WEBRTC_MONITORING` | bool | `false` | Monitor WebRTC transports |
+| `eventloop_monitoring` | `MODALTRACE_EVENTLOOP_MONITORING` | bool | `true` | Track event loop blocks |
+| **Sampler** |
+| `pytorch_sample_rate` | `MODALTRACE_PYTORCH_SAMPLE_RATE` | float (0-1) | `0.01` | Fraction of PyTorch ops to sample |
+| `anomaly_threshold_ms` | `MODALTRACE_ANOMALY_THRESHOLD_MS` | float | `50.0` | Latency threshold for anomaly capture |
+| **Metrics** |
+| `metrics_flush_interval_ms` | `MODALTRACE_METRICS_FLUSH_INTERVAL_MS` | int | `1000` | Metric aggregation window |
+| `ring_buffer_size` | `MODALTRACE_RING_BUFFER_SIZE` | int | `512` | Must be power of 2 |
+| **A/V Sync** |
+| `av_drift_warning_ms` | `MODALTRACE_AV_DRIFT_WARNING_MS` | float | `40.0` | Warn if drift exceeds this |
+| `av_chunk_ttl_s` | `MODALTRACE_AV_CHUNK_TTL_S` | float | `5.0` | Chunk retention period |
+| **PII Scrubbing** |
+| `scrubbing_enabled` | `MODALTRACE_SCRUBBING_ENABLED` | bool | `true` | Enable PII removal |
+| `scrubbing_patterns` | `MODALTRACE_SCRUBBING_PATTERNS` | list[str] | `[]` | Regex patterns to scrub |
+
+---
+
+## 📁 Architecture
+
+```
+modaltrace/
+├── config.py                 # Pydantic configuration model
+├── _registry.py             # Global SDK registry
+├── conventions/
+│   └── attributes.py        # Semantic convention constants
+├── tracing/
+│   ├── pipeline.py          # Main trace pipeline
+│   ├── sampler.py           # Adaptive sampling logic
+│   ├── pending.py           # Pending spans management
+│   └── propagation.py       # Context propagation
+├── metrics/
+│   ├── instruments.py       # Metric instrument definitions
+│   ├── aggregator.py        # Ring buffer aggregation
+│   └── av_sync.py           # A/V sync metrics
+├── instrumentation/
+│   ├── pytorch.py           # PyTorch auto-instrumentation
+│   ├── gpu.py               # GPU monitoring
+│   ├── eventloop.py         # Event loop tracking
+│   └── transport.py         # Network transport metrics
+├── logging/
+│   ├── api.py               # Structured logging API
+│   └── scrubber.py          # PII scrubbing pipeline
+└── exporters/
+    └── setup.py             # OTLP exporter initialization
+```
+
+---
+
+## 🔧 Development
+
+### Setup
+
+```bash
+git clone https://github.com/arnabdeypolimi/video-ai-telemetry.git
+cd video-ai-telemetry
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e ".[dev,all]"
+```
+
+### Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Lint & Format
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+### Type Check
+
+```bash
+mypy src/
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Open an [issue](https://github.com/arnabdeypolimi/video-ai-telemetry/issues) to discuss changes
+2. Fork the repository and create a feature branch
+3. Submit a pull request with tests for new functionality
+4. Ensure all tests pass and code is linted
+
+For detailed guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## 📄 License
+
+ModalTrace is licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details.
+
+---
+
+**Questions?** Open an [issue](https://github.com/arnabdeypolimi/video-ai-telemetry/issues) or check the [documentation](https://github.com/arnabdeypolimi/video-ai-telemetry/wiki).