chuk-tool-processor 0.7.0__py3-none-any.whl → 0.10__py3-none-any.whl

chuk_tool_processor/observability/tracing.py

@@ -0,0 +1,346 @@
+"""
+OpenTelemetry tracing integration for chuk-tool-processor.
+
+Provides drop-in distributed tracing with standardized span names and attributes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from chuk_tool_processor.logging import get_logger
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span, Tracer
+
+logger = get_logger("chuk_tool_processor.observability.tracing")
+
+# Global tracer instance
+_tracer: Tracer | None = None
+_tracing_enabled = False
+
+
+def init_tracer(service_name: str = "chuk-tool-processor") -> Tracer | NoOpTracer:
+    """
+    Initialize OpenTelemetry tracer with best-practice configuration.
+
+    Args:
+        service_name: Service name for tracing
+
+    Returns:
+        Configured OpenTelemetry tracer or NoOpTracer if initialization fails
+    """
+    global _tracer, _tracing_enabled
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        # Create resource with service name
+        resource = Resource.create({"service.name": service_name})
+
+        # Create tracer provider
+        provider = TracerProvider(resource=resource)
+
+        # Add OTLP exporter (exports to OTEL collector)
+        otlp_exporter = OTLPSpanExporter()
+        provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+
+        # Set as global tracer provider
+        trace.set_tracer_provider(provider)
+
+        _tracer = trace.get_tracer(__name__)
+        _tracing_enabled = True
+
+        logger.info(f"OpenTelemetry tracing initialized for service: {service_name}")
+        return _tracer
+
+    except ImportError as e:
+        logger.warning(f"OpenTelemetry packages not installed: {e}. Tracing disabled.")
+        _tracing_enabled = False
+        return NoOpTracer()
+
+
+def get_tracer() -> Tracer | NoOpTracer:
+    """
+    Get the current tracer instance.
+
+    Returns:
+        OpenTelemetry tracer or no-op tracer if not initialized
+    """
+    if _tracer is None:
+        return NoOpTracer()
+    return _tracer
+
+
+def is_tracing_enabled() -> bool:
+    """Check if tracing is enabled."""
+    return _tracing_enabled
+
+
+@contextmanager
+def trace_tool_execution(
+    tool: str,
+    namespace: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[None, None, None]:
+    """
+    Context manager for tracing tool execution.
+
+    Creates a span with name "tool.execute" and standard attributes.
+
+    Args:
+        tool: Tool name
+        namespace: Optional tool namespace
+        attributes: Additional span attributes
+
+    Example:
+        with trace_tool_execution("calculator", attributes={"operation": "add"}):
+            result = await tool.execute(a=5, b=3)
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.execute"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+    }
+
+    if namespace:
+        span_attributes["tool.namespace"] = namespace
+
+    if attributes:
+        # Flatten attributes with "tool." prefix
+        for key, value in attributes.items():
+            # Convert value to string for OTEL compatibility
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"tool.{key}"] = value
+            else:
+                span_attributes[f"tool.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_cache_operation(
+    operation: str,
+    tool: str,
+    hit: bool | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[None, None, None]:
+    """
+    Context manager for tracing cache operations.
+
+    Args:
+        operation: Cache operation (lookup, set, invalidate)
+        tool: Tool name
+        hit: Whether cache hit (for lookup operations)
+        attributes: Additional span attributes
+
+    Example:
+        with trace_cache_operation("lookup", "calculator", hit=True):
+            result = await cache.get(tool, key)
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = f"tool.cache.{operation}"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "cache.operation": operation,
+    }
+
+    if hit is not None:
+        span_attributes["cache.hit"] = hit
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"cache.{key}"] = value
+            else:
+                span_attributes[f"cache.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_retry_attempt(
+    tool: str,
+    attempt: int,
+    max_retries: int,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[None, None, None]:
+    """
+    Context manager for tracing retry attempts.
+
+    Args:
+        tool: Tool name
+        attempt: Current attempt number (0-indexed)
+        max_retries: Maximum retry attempts
+        attributes: Additional span attributes
+
+    Example:
+        with trace_retry_attempt("api_tool", attempt=1, max_retries=3):
+            result = await executor.execute([call])
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.retry.attempt"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "retry.attempt": attempt,
+        "retry.max_attempts": max_retries,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"retry.{key}"] = value
+            else:
+                span_attributes[f"retry.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_circuit_breaker(
+    tool: str,
+    state: str,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[None, None, None]:
+    """
+    Context manager for tracing circuit breaker operations.
+
+    Args:
+        tool: Tool name
+        state: Circuit breaker state (CLOSED, OPEN, HALF_OPEN)
+        attributes: Additional span attributes
+
+    Example:
+        with trace_circuit_breaker("api_tool", state="OPEN"):
+            can_execute = await breaker.can_execute()
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.circuit_breaker.check"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "circuit.state": state,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"circuit.{key}"] = value
+            else:
+                span_attributes[f"circuit.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_rate_limit(
+    tool: str,
+    allowed: bool,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[None, None, None]:
+    """
+    Context manager for tracing rate limiting.
+
+    Args:
+        tool: Tool name
+        allowed: Whether request was allowed
+        attributes: Additional span attributes
+
+    Example:
+        with trace_rate_limit("api_tool", allowed=True):
+            await rate_limiter.acquire()
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.rate_limit.check"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "rate_limit.allowed": allowed,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"rate_limit.{key}"] = value
+            else:
+                span_attributes[f"rate_limit.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+def add_span_event(span: Span | None, name: str, attributes: dict[str, Any] | None = None) -> None:
+    """
+    Add an event to the current span.
+
+    Args:
+        span: Span to add event to (can be None)
+        name: Event name
+        attributes: Event attributes
+    """
+    if span is None or not _tracing_enabled:
+        return
+
+    try:
+        span.add_event(name, attributes=attributes or {})
+    except Exception as e:
+        logger.debug(f"Error adding span event: {e}")
+
+
+def set_span_error(span: Span | None, error: Exception | str) -> None:
+    """
+    Mark span as error and record exception details.
+
+    Args:
+        span: Span to mark as error (can be None)
+        error: Error to record
+    """
+    if span is None or not _tracing_enabled:
+        return
+
+    try:
+        from opentelemetry.trace import Status, StatusCode
+
+        span.set_status(Status(StatusCode.ERROR, str(error)))
+
+        if isinstance(error, Exception):
+            span.record_exception(error)
+        else:
+            span.add_event("error", {"error.message": str(error)})
+
+    except Exception as e:
+        logger.debug(f"Error setting span error: {e}")
+
+
+class NoOpTracer:
+    """No-op tracer when OpenTelemetry is not available."""
+
+    @contextmanager
+    def start_as_current_span(self, _name: str, **_kwargs: Any) -> Generator[None, None, None]:
+        """No-op span context manager."""
+        yield None

chuk_tool_processor/registry/interface.py

@@ -36,7 +36,7 @@ class ToolRegistryInterface(Protocol):
             namespace: Namespace for the tool (default: "default").
             metadata: Optional additional metadata for the tool.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_tool(self, name: str, namespace: str = "default") -> Any | None:
         """
@@ -49,7 +49,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             The tool implementation or None if not found.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
         """
@@ -65,7 +65,7 @@ class ToolRegistryInterface(Protocol):
         Raises:
             ToolNotFoundError: If the tool is not found in the registry.
         """
-        ...
+        ...  # pragma: no cover
 
     async def get_metadata(self, name: str, namespace: str = "default") -> ToolMetadata | None:
         """
@@ -78,7 +78,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             ToolMetadata if found, None otherwise.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_tools(self, namespace: str | None = None) -> list[tuple[str, str]]:
         """
@@ -90,7 +90,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of (namespace, name) tuples.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_namespaces(self) -> list[str]:
         """
@@ -99,7 +99,7 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of namespace names.
         """
-        ...
+        ...  # pragma: no cover
 
     async def list_metadata(self, namespace: str | None = None) -> list[ToolMetadata]:
         """
@@ -113,4 +113,4 @@ class ToolRegistryInterface(Protocol):
         Returns:
             List of ToolMetadata objects.
         """
-        ...
+        ...  # pragma: no cover

chuk_tool_processor/registry/providers/__init__.py

@@ -5,6 +5,7 @@ Async registry provider implementations and factory functions.
 
 import asyncio
 import os
+from typing import Any
 
 from chuk_tool_processor.registry.interface import ToolRegistryInterface
 
@@ -13,7 +14,7 @@ _REGISTRY_CACHE: dict[str, ToolRegistryInterface] = {}
 _REGISTRY_LOCKS: dict[str, asyncio.Lock] = {}
 
 
-async def get_registry(provider_type: str | None = None, **kwargs) -> ToolRegistryInterface:
+async def get_registry(provider_type: str | None = None, **kwargs: Any) -> ToolRegistryInterface:
     """
     Factory function to get a registry implementation asynchronously.
 

chuk_tool_processor/registry/tool_export.py

@@ -28,13 +28,8 @@ async def _build_openai_name_cache() -> None:
     """
     global _OPENAI_NAME_CACHE
 
-    # Fast path - cache already exists
-    if _OPENAI_NAME_CACHE is not None:
-        return
-
-    # Slow path - build the cache with proper locking
+    # Build the cache with proper locking
     async with _CACHE_LOCK:
-        # Double-check pattern: check again after acquiring the lock
         if _OPENAI_NAME_CACHE is not None:
             return