mirascope 1.25.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

mirascope/ops/_internal/exporters/processors.py

@@ -0,0 +1,104 @@
+"""Span processors for two-phase export system.
+
+This module implements a custom SpanProcessor that sends immediate
+start events and batches end events for efficient export.
+"""
+
+from concurrent.futures import ThreadPoolExecutor
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from .exporters import MirascopeOTLPExporter
+
+
+class MirascopeSpanProcessor(SpanProcessor):
+    """Two-phase span processor for Mirascope telemetry.
+
+    This processor implements a two-phase export strategy:
+    1. Immediate transmission of minimal start events for real-time visibility
+    2. Batched transmission of complete events for efficiency
+
+    The processor uses a thread pool to ensure start events don't block
+    the application while maintaining compatibility with OpenTelemetry's
+    synchronous SDK.
+
+    Attributes:
+        start_exporter: Exporter for immediate start events.
+        batch_processor: Standard batch processor for completed spans.
+        executor: Thread pool for non-blocking start event transmission.
+    """
+
+    def __init__(
+        self,
+        otlp_exporter: MirascopeOTLPExporter,
+        batch_processor: BatchSpanProcessor | None = None,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the two-phase processor.
+
+        Args:
+            start_exporter: Exporter for immediate start events.
+            batch_processor: Optional batch processor for end events.
+            executor: Optional thread pool executor (creates default if None).
+        """
+        self.otlp_exporter = otlp_exporter
+        self.batch_processor = batch_processor
+        self.executor = executor or ThreadPoolExecutor(
+            max_workers=2, thread_name_prefix="mirascope-span-processor"
+        )
+        self._shutdown = False
+
+    def on_start(
+        self, span: ReadableSpan, parent_context: Context | None = None
+    ) -> None:
+        """Handle span start by sending immediate start event.
+
+        This method extracts minimal span data and sends it immediately
+        via the start exporter in a non-blocking manner.
+
+        Args:
+            span: The span that just started.
+            parent_context: Optional parent context for the span.
+        """
+        if self._shutdown:
+            return
+
+        self.executor.submit(self.otlp_exporter.export, [span])
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """Handle span end by delegating to batch processor.
+
+        Args:
+            span: The span that just ended.
+        """
+        if self.batch_processor and not self._shutdown:
+            self.batch_processor.on_end(span)
+
+    def shutdown(self) -> None:
+        """Gracefully shutdown the processor.
+
+        This ensures all pending start events are sent and the
+        batch processor is properly shutdown.
+        """
+        self._shutdown = True
+
+        if self.batch_processor:
+            self.batch_processor.shutdown()
+
+        self.executor.shutdown(wait=True)
+        self.otlp_exporter.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush all pending data.
+
+        Args:
+            timeout_millis: Maximum time to wait in milliseconds.
+
+        Returns:
+            True if flush completed successfully.
+        """
+        if self.batch_processor:
+            return self.batch_processor.force_flush(timeout_millis)
+        return True

mirascope/ops/_internal/exporters/types.py

@@ -0,0 +1,165 @@
+"""Type definitions for the two-phase export system.
+
+This module defines the event types and data structures used for
+immediate start event transmission and batched end event export.
+"""
+
+from enum import Enum
+from typing import Literal, TypedDict
+
+from opentelemetry.util.types import AttributeValue
+
+# TODO: unify/DRY types in the _internal package
+
+SpanKind = Literal["CLIENT", "SERVER", "PRODUCER", "CONSUMER", "INTERNAL"]
+StatusCode = Literal["UNSET", "OK", "ERROR"]
+
+
+class SpanEventType(str, Enum):
+    """Event types for span lifecycle tracking."""
+
+    SPAN_STARTED = "span_started"
+    SPAN_UPDATED = "span_updated"
+    SPAN_COMPLETED = "span_completed"
+
+
+class SpanEvent(TypedDict):
+    """Individual event within a span."""
+
+    name: str
+    """The name of the event."""
+
+    timestamp: int
+    """Nanoseconds since epoch (OTel standard)."""
+
+    attributes: dict[str, AttributeValue]
+    """Event-specific attributes."""
+
+
+class Status(TypedDict):
+    """Status representation for serialization."""
+
+    code: StatusCode
+    """The status code: UNSET, OK, or ERROR."""
+
+    description: str | None
+    """Optional human-readable description of the status."""
+
+
+class SpanContextDict(TypedDict):
+    """Span context for links and parent references."""
+
+    trace_id: str
+    """The trace ID as a 32-character hex string."""
+
+    span_id: str
+    """The span ID as a 16-character hex string."""
+
+    trace_flags: int
+    """Trace flags (e.g., for sampling decisions)."""
+
+    trace_state: str | None
+    """Optional vendor-specific trace state."""
+
+
+class Link(TypedDict):
+    """Link representation for span relationships."""
+
+    context: SpanContextDict
+    """The linked span's context."""
+
+    attributes: dict[str, AttributeValue]
+    """Attributes describing the link."""
+
+
+class SpanStartEvent(TypedDict):
+    """Minimal span data for immediate transmission.
+
+    This event is sent immediately when a span starts to provide
+    real-time visibility into long-running operations.
+    """
+
+    trace_id: str
+    """The trace ID as a 32-character hex string."""
+
+    span_id: str
+    """The span ID as a 16-character hex string."""
+
+    parent_span_id: str | None
+    """The parent span ID if this is a child span."""
+
+    name: str
+    """The name of the span."""
+
+    start_time: int
+    """Nanoseconds since epoch."""
+
+    kind: SpanKind
+    """The span kind: CLIENT, SERVER, PRODUCER, CONSUMER, or INTERNAL."""
+
+    attributes: dict[str, AttributeValue]
+    """Minimal required attributes only."""
+
+
+class SpanUpdateEvent(TypedDict, total=False):
+    """Incremental updates to span data.
+
+    These events are batched and sent periodically to update
+    span attributes or add events without waiting for completion.
+    """
+
+    trace_id: str
+    """The trace ID as a 32-character hex string."""
+
+    span_id: str
+    """The span ID as a 16-character hex string."""
+
+    timestamp: int
+    """Nanoseconds since epoch."""
+
+    attributes: dict[str, AttributeValue]
+    """Additional or updated attributes."""
+
+    events: list[SpanEvent]
+    """New events to add to the span."""
+
+
+class SpanCompleteEvent(TypedDict):
+    """Complete span data for batch export.
+
+    This event contains all span data and is sent when the span
+    completes, typically in batches for efficiency.
+    """
+
+    trace_id: str
+    """The trace ID as a 32-character hex string."""
+
+    span_id: str
+    """The span ID as a 16-character hex string."""
+
+    parent_span_id: str | None
+    """The parent span ID if this is a child span."""
+
+    name: str
+    """The name of the span."""
+
+    kind: SpanKind
+    """The span kind: CLIENT, SERVER, PRODUCER, CONSUMER, or INTERNAL."""
+
+    start_time: int
+    """Nanoseconds since epoch."""
+
+    end_time: int
+    """Nanoseconds since epoch."""
+
+    status: Status
+    """The final status of the span."""
+
+    attributes: dict[str, AttributeValue]
+    """All span attributes."""
+
+    events: list[SpanEvent]
+    """All events that occurred during the span."""
+
+    links: list[Link]
+    """Links to other spans."""

mirascope/ops/_internal/exporters/utils.py

@@ -0,0 +1,29 @@
+"""Utility functions for OpenTelemetry exporters.
+
+This module provides helper functions for formatting and converting
+OpenTelemetry data types for export.
+"""
+
+
+def format_trace_id(trace_id: int) -> str:
+    """Format a trace ID as a 32-character hex string.
+
+    Args:
+        trace_id: The trace ID as an integer.
+
+    Returns:
+        32-character hexadecimal string representation of the trace ID.
+    """
+    return format(trace_id, "032x")
+
+
+def format_span_id(span_id: int) -> str:
+    """Format a span ID as a 16-character hex string.
+
+    Args:
+        span_id: The span ID as an integer.
+
+    Returns:
+        16-character hexadecimal string representation of the span ID.
+    """
+    return format(span_id, "016x")

mirascope/ops/_internal/instrumentation/__init__.py

@@ -0,0 +1,8 @@
+"""Instrumentation modules for various frameworks and libraries."""
+
+from .llm import instrument_llm, uninstrument_llm
+
+__all__ = [
+    "instrument_llm",
+    "uninstrument_llm",
+]

mirascope/ops/_internal/instrumentation/llm/__init__.py

@@ -0,0 +1,8 @@
+"""Instrumentation llm modules for various frameworks and libraries."""
+
+from .llm import instrument_llm, uninstrument_llm
+
+__all__ = [
+    "instrument_llm",
+    "uninstrument_llm",
+]