fiddler-otel 0.1.1__py3-none-any.whl

fiddler_otel/__init__.py

@@ -0,0 +1,26 @@
+"""Fiddler OTel - core OpenTelemetry instrumentation for GenAI applications."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from fiddler_otel.attributes import set_conversation_id
+from fiddler_otel.client import FiddlerClient, get_client
+from fiddler_otel.decorators import get_current_span, trace
+from fiddler_otel.span_wrapper import FiddlerChain, FiddlerGeneration, FiddlerSpan, FiddlerTool
+
+try:
+    __version__ = version('fiddler-otel')
+except PackageNotFoundError:
+    __version__ = 'unknown'
+
+__all__ = [
+    'FiddlerChain',
+    'FiddlerClient',
+    'FiddlerGeneration',
+    'FiddlerSpan',
+    'FiddlerTool',
+    '__version__',
+    'get_client',
+    'get_current_span',
+    'set_conversation_id',
+    'trace',
+]

fiddler_otel/attributes.py

@@ -0,0 +1,97 @@
+"""OpenTelemetry span attributes for Fiddler instrumentation."""
+
+import contextvars
+from typing import Any
+
+from pydantic import ConfigDict, validate_call
+
+# Key used for storing Fiddler-specific attributes in metadata dictionary
+FIDDLER_METADATA_KEY = '_fiddler_attributes'
+
+# Template strings for OpenTelemetry attribute key formatting
+FIDDLER_USER_SPAN_ATTRIBUTE_TEMPLATE = 'fiddler.span.user.{key}'
+FIDDLER_USER_SESSION_ATTRIBUTE_TEMPLATE = 'fiddler.session.user.{key}'
+
+
+class FiddlerSpanAttributes:  # pylint: disable=too-few-public-methods
+    """Constants for Fiddler OpenTelemetry span attributes."""
+
+    # common attributes
+    AGENT_NAME = 'gen_ai.agent.name'
+    AGENT_ID = 'gen_ai.agent.id'
+    CONVERSATION_ID = 'gen_ai.conversation.id'
+    TYPE = 'fiddler.span.type'
+    SERVICE_VERSION = 'service.version'
+
+    # LLM attributes
+    LLM_INPUT_SYSTEM = 'gen_ai.llm.input.system'
+    LLM_INPUT_USER = 'gen_ai.llm.input.user'
+    LLM_OUTPUT = 'gen_ai.llm.output'
+    LLM_CONTEXT = 'gen_ai.llm.context'
+
+    # Model attributes - following OpenTelemetry semantic conventions
+    LLM_REQUEST_MODEL = 'gen_ai.request.model'
+    LLM_SYSTEM = 'gen_ai.system'
+
+    # Token usage attributes
+    LLM_TOKEN_COUNT_INPUT = 'gen_ai.usage.input_tokens'
+    LLM_TOKEN_COUNT_OUTPUT = 'gen_ai.usage.output_tokens'
+    LLM_TOKEN_COUNT_TOTAL = 'gen_ai.usage.total_tokens'
+    GEN_AI_INPUT_MESSAGES = 'gen_ai.input.messages'
+    GEN_AI_OUTPUT_MESSAGES = 'gen_ai.output.messages'
+
+    # tool attributes
+    TOOL_INPUT = 'gen_ai.tool.input'
+    TOOL_OUTPUT = 'gen_ai.tool.output'
+    TOOL_NAME = 'gen_ai.tool.name'
+    TOOL_DEFINITIONS = 'gen_ai.tool.definitions'
+
+
+class FiddlerResourceAttributes:
+    """Constants for Fiddler OpenTelemetry resource attributes."""
+
+    APPLICATION_ID = 'application.id'
+
+
+class SpanType:
+    """Constants for Fiddler OpenTelemetry span types."""
+
+    AGENT = 'agent'
+    CHAIN = 'chain'
+    TOOL = 'tool'
+    LLM = 'llm'
+    OTHER = 'other'
+
+
+# context variable for conversation ID - used to store the conversation ID for the current
+# thread/async coroutine. Note that contextvars are shallow copied; dictionaries/lists are not
+# copied deeply and are shared between threads/coroutines.
+_CONVERSATION_ID: contextvars.ContextVar[str] = contextvars.ContextVar(
+    '_CONVERSATION_ID', default=''
+)
+_CUSTOM_ATTRIBUTES: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
+    '_CUSTOM_ATTRIBUTES', default=None
+)
+
+
+@validate_call(config=ConfigDict(strict=True))
+def set_conversation_id(conversation_id: str) -> None:
+    """Set the conversation ID for the current execution context.
+
+    The conversation ID is propagated to all spans created in the current
+    thread or async coroutine, allowing the Fiddler dashboard to filter and
+    display the full ordered sequence of operations for a single conversation.
+
+    This value persists until it is called again with a new ID.
+
+    :param conversation_id: Unique identifier for the conversation session.
+
+    Example::
+
+        from fiddler_otel import set_conversation_id
+        import uuid
+
+        set_conversation_id(str(uuid.uuid4()))
+        agent.invoke({"messages": [{"role": "user", "content": "Hello"}]})
+    """
+    _CONVERSATION_ID.set(conversation_id)

fiddler_otel/client.py

@@ -0,0 +1,406 @@
+"""Core client for Fiddler OTel instrumentation."""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+import threading
+import uuid
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from opentelemetry import context, trace
+from opentelemetry.context.context import Context
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression, OTLPSpanExporter
+from opentelemetry.sdk.resources import (
+    OTELResourceDetector,
+    ProcessResourceDetector,
+    Resource,
+    get_aggregated_resources,
+)
+from opentelemetry.sdk.trace import SpanLimits, TracerProvider, sampling
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+    SimpleSpanProcessor,
+)
+
+from fiddler_otel.attributes import FiddlerResourceAttributes
+from fiddler_otel.jsonl_capture import JSONLSpanExporter, initialize_jsonl_capture
+from fiddler_otel.span_processor import FiddlerSpanProcessor
+from fiddler_otel.span_wrapper import (
+    _SPAN_TYPE_MAP,
+    FiddlerChain,
+    FiddlerGeneration,
+    FiddlerSpan,
+    FiddlerTool,
+)
+from fiddler_otel.utils import is_fiddler_span
+
+logger = logging.getLogger(__name__)
+
+
+class _FiddlerSpanContextManager:
+    """Context manager that activates a span in Fiddler's isolated context.
+
+    This ensures spans are set as "current" in the Fiddler context, not the global context,
+    maintaining isolation from other OpenTelemetry tracers.
+    """
+
+    def __init__(self, span: trace.Span, fdl_context: Context):
+        """Initialize the context manager.
+
+        :param span: The OpenTelemetry span to manage.
+        :param fdl_context: The Fiddler client's isolated context.
+        """
+        self._span = span
+        self._fdl_context = fdl_context
+        self._token: Any = None
+
+    def __enter__(self) -> trace.Span:
+        """Enter the context and set the span as current in Fiddler's context."""
+        new_context = trace.set_span_in_context(self._span, self._fdl_context)
+        self._token = context.attach(new_context)
+        return self._span
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
+        """Exit the context, end the span, and detach the Fiddler context."""
+        if exc_val is not None:
+            self._span.record_exception(exc_val)
+            self._span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc_val)))
+        else:
+            self._span.set_status(trace.Status(trace.StatusCode.OK))
+
+        self._span.end()
+
+        if self._token is not None:
+            context.detach(self._token)
+
+        return False
+
+
+# Global singleton: first FiddlerClient created in this process.
+# One client => one BatchSpanProcessor (one thread, one connection); OTel
+# uses contextvars for current span per asyncio task, so trace isolation is
+# per-task without per-task clients.
+_default_client: FiddlerClient | None = None
+_client_lock = threading.Lock()
+
+
+def get_client() -> FiddlerClient:
+    """Return the global FiddlerClient singleton (first created in this process).
+
+    :returns: The global client instance.
+    :raises RuntimeError: If no FiddlerClient has been initialized.
+    """
+    global _default_client
+    if _default_client is None:
+        raise RuntimeError(
+            'No FiddlerClient initialized. Create one first: client = FiddlerClient(...)'
+        )
+    return _default_client
+
+
+class FiddlerClient:
+    """The main client for instrumenting Generative AI applications with Fiddler observability.
+
+    This client configures and manages the OpenTelemetry tracer that sends telemetry data
+    to the Fiddler platform for monitoring, analysis, and debugging of your AI agents
+    and workflows.
+
+    Flush on exit: A shutdown handler is registered via :func:`atexit` so that pending
+    spans are flushed and the tracer is shut down when the process exits. For short
+    scripts or critical workloads, call :meth:`force_flush` and :meth:`shutdown` explicitly
+    (e.g. in a ``try``/``finally`` or signal handler) since ``atexit`` may not run in all
+    environments (e.g. SIGKILL, fork).
+
+    Asyncio: Tracing works in asyncio (context vars propagate across ``await``). When
+    shutting down from async code, use :meth:`aflush` and :meth:`ashutdown` so the event
+    loop is not blocked; the sync :meth:`force_flush` and :meth:`shutdown` can block for
+    up to the flush timeout.
+
+    Context manager: Use ``with FiddlerClient(...) as client:`` to ensure
+    :meth:`shutdown` is called on exit (flush then shutdown; atexit is unregistered).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        application_id: str,
+        url: str,
+        console_tracer: bool = False,
+        span_limits: SpanLimits | None = None,
+        sampler: sampling.Sampler | None = None,
+        compression: Compression = Compression.Gzip,
+        jsonl_capture_enabled: bool = False,
+        jsonl_file_path: str = 'fiddler_trace_data.jsonl',
+    ):
+        """Initialise the FiddlerClient.
+
+        :param api_key: The API key for authenticating with the Fiddler backend.
+        :param application_id: The unique identifier (UUID4) for the application.
+        :param url: The base URL for your Fiddler instance (e.g. ``https://your-instance.fiddler.ai``).
+        :param console_tracer: If True, traces are printed to the console instead of being exported.
+        :param span_limits: OpenTelemetry span limits configuration.
+        :param sampler: OpenTelemetry sampler; defaults to parent-based always-on (100% sampling).
+        :param compression: OTLP export compression. Defaults to ``Compression.Gzip``.
+        :param jsonl_capture_enabled: Enable JSONL capture of trace data to a local file.
+        :param jsonl_file_path: Path to the JSONL file (used when ``jsonl_capture_enabled=True``).
+        :raises ValueError: If ``application_id`` is not a valid UUID4 or ``url`` is not valid.
+        """
+        # Validate application_id is a valid UUID4
+        parsed_uuid = uuid.UUID(application_id)
+        if parsed_uuid.version != 4:
+            raise ValueError(
+                f'application_id must be a valid UUID4 (version 4), got version {parsed_uuid.version}'
+            )
+        self.application_id = str(parsed_uuid)
+
+        # Validate URL
+        parsed_url = urlparse(url)
+        if not parsed_url.scheme or not parsed_url.netloc:
+            raise ValueError('URL must have a valid scheme and netloc')
+        if parsed_url.scheme not in ('http', 'https'):
+            raise ValueError('URL scheme must be http or https')
+        self.url = url.rstrip('/')
+
+        self.api_key = api_key
+
+        # Dedicated (non-global) TracerProvider - initialized lazily on first get_tracer() call
+        self._provider: TracerProvider | None = None
+        self._tracer: trace.Tracer | None = None
+        self._console_tracer = console_tracer
+
+        # Fiddler-specific isolated context (prevents ambient global span inheritance)
+        self._context = Context()
+
+        self.span_limits = span_limits
+        self.sampler = sampler
+        self.compression = compression
+        self.jsonl_capture_enabled = jsonl_capture_enabled
+        self.jsonl_file_path = jsonl_file_path
+
+        resource = Resource.create({FiddlerResourceAttributes.APPLICATION_ID: self.application_id})
+        self.resource = self._get_aggregated_resources_with_fallback(resource)
+
+        # Register as default client for singleton pattern
+        global _default_client
+        with _client_lock:
+            if _default_client is None:
+                _default_client = self
+
+        atexit.register(self._atexit_shutdown)
+
+    def __enter__(self) -> FiddlerClient:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit — flushes and shuts down the tracer provider."""
+        self.shutdown()
+
+    def _atexit_shutdown(self) -> None:
+        """Called at process exit to flush and shutdown the tracer provider."""
+        self.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Flush pending spans to the exporter.
+
+        :param timeout_millis: Maximum time to wait for flush in milliseconds.
+        :returns: True if flush completed within the timeout, False otherwise.
+        """
+        if self._provider is None:
+            logger.debug('Tracer provider not initialized, skipping flush')
+            return True
+        logger.info('Flushing tracer provider (timeout_millis=%s)', timeout_millis)
+        return self._provider.force_flush(timeout_millis)
+
+    async def aflush(self, timeout_millis: int = 30000) -> bool:
+        """Async version of :meth:`force_flush`.
+
+        Runs the flush in a thread pool so the event loop is not blocked.
+        """
+        return await asyncio.to_thread(self.force_flush, timeout_millis)
+
+    def shutdown(self) -> None:
+        """Shut down the tracer provider after flushing pending spans.
+
+        Safe to call multiple times. The atexit handler is unregistered on first call.
+        """
+        if self._provider is None:
+            logger.debug('Tracer provider not initialized, skipping shutdown')
+            return
+        logger.info('Shutting down tracer provider')
+        try:
+            atexit.unregister(self._atexit_shutdown)
+        except Exception as e:
+            logger.debug('Could not unregister atexit handler: %s', e)
+        try:
+            self._provider.force_flush(30000)
+        except Exception as e:
+            logger.warning('Error flushing tracer provider during shutdown: %s', e)
+        try:
+            self._provider.shutdown()
+        except Exception as e:
+            logger.warning('Error shutting down tracer provider: %s', e)
+        finally:
+            self._provider = None
+            self._tracer = None
+
+    async def ashutdown(self) -> None:
+        """Async version of :meth:`shutdown`.
+
+        Runs flush and shutdown in a thread pool so the event loop is not blocked.
+        """
+        await asyncio.to_thread(self.shutdown)
+
+    def get_tracer_provider(self) -> TracerProvider:
+        """Return the OpenTelemetry TracerProvider, initializing it on first call.
+
+        :returns: The configured TracerProvider.
+        :raises RuntimeError: If initialization fails.
+        """
+        if self._provider is None:
+            self._initialize_provider()
+            if self._provider is None:
+                raise RuntimeError('Failed to initialize tracer provider')
+        return self._provider
+
+    def _get_aggregated_resources_with_fallback(self, initial_resource: Resource) -> Resource:
+        """Aggregate OTel resource detectors with a fallback for older OTel versions.
+
+        :param initial_resource: The base resource to start with.
+        :returns: The aggregated resource.
+        """
+        detectors = [OTELResourceDetector(), ProcessResourceDetector()]
+
+        try:
+            from opentelemetry.sdk.resources import OsResourceDetector
+
+            detectors.append(OsResourceDetector())
+        except ImportError:
+            pass
+
+        try:
+            return get_aggregated_resources(detectors, initial_resource=initial_resource)
+        except Exception as e:
+            logger.debug('Resource aggregation failed, using initial resource: %s', e)
+            return initial_resource
+
+    def update_resource(self, attributes: dict[str, Any]) -> None:
+        """Update the OTel resource with additional attributes.
+
+        Must be called **before** :meth:`get_tracer` is invoked.
+
+        :param attributes: Key-value pairs to merge into the resource.
+        :raises ValueError: If the tracer has already been initialized.
+        """
+        if self._tracer is not None:
+            raise ValueError('Cannot update resource after tracer is initialized')
+
+        if (
+            self.resource.attributes.get('service.name', '') != 'unknown_service'
+            and attributes.get('service.name') is None
+        ):
+            attributes['service.name'] = self.resource.attributes['service.name']
+
+        self.resource = self.resource.merge(Resource.create(attributes))
+
+    def _initialize_provider(self) -> None:
+        """Initialize the TracerProvider (dedicated, not the global one)."""
+        if self._provider is not None:
+            return
+
+        self._provider = TracerProvider(
+            resource=self.resource,
+            span_limits=self.span_limits,
+            sampler=self.sampler,
+        )
+
+    def _initialize_tracer(self) -> None:
+        """Initialize the OTel tracer and register span processors."""
+        if self._tracer is not None:
+            return
+
+        self._initialize_provider()
+        assert self._provider is not None  # type guard for mypy
+
+        # FiddlerSpanProcessor runs first so it can inject session/conversation attributes
+        self._provider.add_span_processor(FiddlerSpanProcessor())
+
+        if self._console_tracer:
+            self._provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+
+        otlp_exporter = OTLPSpanExporter(
+            endpoint=f'{self.url}/v1/traces',
+            headers={
+                'authorization': f'Bearer {self.api_key}',
+                'fiddler-application-id': self.application_id,
+            },
+            compression=self.compression,
+        )
+        self._provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+
+        if self.jsonl_capture_enabled:
+            jsonl_capture = initialize_jsonl_capture(self.jsonl_file_path)
+            jsonl_exporter = JSONLSpanExporter(jsonl_capture)
+            self._provider.add_span_processor(SimpleSpanProcessor(jsonl_exporter))
+
+        self._tracer = trace.get_tracer('fiddler.otel.tracer', tracer_provider=self._provider)
+
+    def get_tracer(self) -> trace.Tracer:
+        """Return an OTel tracer for creating spans.
+
+        Initializes the tracer on the first call.
+
+        :returns: The OTel tracer instance.
+        :raises RuntimeError: If tracer initialization fails.
+        """
+        if self._tracer is None:
+            self._initialize_tracer()
+            if self._tracer is None:
+                raise RuntimeError('Failed to initialize tracer')
+        return self._tracer
+
+    def start_as_current_span(
+        self,
+        name: str,
+        as_type: Literal['span', 'generation', 'chain', 'tool'] = 'span',
+    ) -> FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool:
+        """Create a span using a context manager (automatic lifecycle management).
+
+        :param name: Name for the span.
+        :param as_type: Span type — ``"span"``, ``"generation"``, ``"chain"``, or ``"tool"``.
+        :returns: Span wrapper with context manager support.
+        """
+        tracer = self.get_tracer()
+        current_context = context.get_current()
+        current_span = trace.get_current_span(current_context)
+
+        parent_context = self._context
+        if is_fiddler_span(current_span):
+            parent_context = current_context
+
+        otel_span = tracer.start_span(name, context=parent_context)
+        fdl_context_manager = _FiddlerSpanContextManager(otel_span, self._context)
+
+        wrapper_class = _SPAN_TYPE_MAP.get(as_type, FiddlerSpan)
+        return wrapper_class(fdl_context_manager)
+
+    def start_span(
+        self,
+        name: str,
+        as_type: Literal['span', 'generation', 'chain', 'tool'] = 'span',
+    ) -> FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool:
+        """Create a span with manual lifecycle control. Caller must call ``span.end()``.
+
+        :param name: Name for the span.
+        :param as_type: Span type — ``"span"``, ``"generation"``, ``"chain"``, or ``"tool"``.
+        :returns: Span wrapper requiring an explicit ``end()`` call.
+        """
+        tracer = self.get_tracer()
+        otel_span = tracer.start_span(name, context=self._context)
+
+        wrapper_class = _SPAN_TYPE_MAP.get(as_type, FiddlerSpan)
+        return wrapper_class(otel_span)