fiddler-langgraph 1.3.0__tar.gz → 1.3.1__tar.gz

{fiddler_langgraph-1.3.0/fiddler_langgraph.egg-info → fiddler_langgraph-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiddler-langgraph
-Version: 1.3.0
+Version: 1.3.1
 Summary: Python SDK for instrumenting GenAI Applications with Fiddler
 Home-page: https://fiddler.ai
 Author: Fiddler AI

fiddler_langgraph-1.3.1/fiddler_langgraph/VERSION

@@ -0,0 +1 @@
+1.3.1

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1}/fiddler_langgraph/core/client.py

@@ -1,5 +1,8 @@
 """Core client for Fiddler instrumentation."""
 
+import asyncio
+import atexit
+import logging
 import uuid
 from typing import Any
 from urllib.parse import urlparse
@@ -23,6 +26,8 @@ from fiddler_langgraph.core.attributes import FiddlerResourceAttributes
 from fiddler_langgraph.core.span_processor import FiddlerSpanProcessor
 from fiddler_langgraph.tracing.jsonl_capture import JSONLSpanExporter, initialize_jsonl_capture
 
+logger = logging.getLogger(__name__)
+
 
 class FiddlerClient:
     """The main client for instrumenting Generative AI applications with Fiddler observability.
@@ -31,6 +36,20 @@ class FiddlerClient:
     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).
+
     Attributes:
         application_id (str): The UUID4 identifier for the application.
         url (str): The Fiddler backend URL.
@@ -182,6 +201,92 @@ class FiddlerClient:
         resource = Resource.create({FiddlerResourceAttributes.APPLICATION_ID: self.application_id})
         self.resource = self._get_aggregated_resources_with_fallback(resource)
 
+        # Flush and shutdown tracer on process exit to reduce span loss (BatchSpanProcessor buffers in memory)
+        atexit.register(self._atexit_shutdown)
+
+    def __enter__(self) -> 'FiddlerClient':
+        """Context manager entry. Returns this client."""
+        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:
+        """Flushes pending spans to the exporter.
+
+        Call this before process exit (e.g. in signal handlers or atexit) to reduce
+        intermittent span loss. BatchSpanProcessor buffers spans in memory and exports
+        on a schedule; without flush, buffered spans can be lost on exit.
+
+        This method is blocking (up to ``timeout_millis``). From async code, use
+        :meth:`aflush` to avoid blocking the event loop.
+
+        Args:
+            timeout_millis: Maximum time to wait for flush in milliseconds. Default 30000.
+
+        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.
+        Use this when shutting down an asyncio application.
+        """
+        return await asyncio.to_thread(self.force_flush, timeout_millis)
+
+    def shutdown(self) -> None:
+        """Shuts down the tracer provider after flushing pending spans.
+
+        Call this when the application is exiting to ensure all spans are exported.
+        Safe to call multiple times. Registered automatically via atexit when the
+        client is created. The atexit handler is unregistered so it will not run
+        again at process exit.
+
+        This method is blocking (flush can take up to 30 seconds). From async code,
+        use :meth:`ashutdown` to avoid blocking the event loop.
+        """
+        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:
+            # Handler may already have been removed or not registered
+            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.
+        Use this when shutting down an asyncio application, e.g. in an
+        ``async with`` cleanup or before closing the event loop.
+        """
+        await asyncio.to_thread(self.shutdown)
+
     def get_tracer_provider(self) -> TracerProvider:
         """Gets the OpenTelemetry TracerProvider instance.
 
@@ -225,8 +330,8 @@ class FiddlerClient:
 
         try:
             return get_aggregated_resources(detectors, initial_resource=initial_resource)
-        except Exception:
-            # Fallback to initial resource if aggregation fails
+        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:

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1}/fiddler_langgraph/core/span_processor.py

@@ -11,7 +11,10 @@ from fiddler_langgraph.core.attributes import (
 
 
 class FiddlerSpanProcessor(SpanProcessor):
-    def on_start(self, span: Span, parent_context: context.Context | None = None):
+    """OpenTelemetry SpanProcessor that injects conversation ID and session attributes into spans."""
+
+    def on_start(self, span: Span, parent_context: context.Context | None = None) -> None:
+        """Injects custom session attributes and conversation ID from context vars into the span."""
         # inject custom attributes
         try:
             custom_attributes = _CUSTOM_ATTRIBUTES.get().copy()

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1}/fiddler_langgraph/tracing/callback.py

@@ -593,18 +593,13 @@ class _CallbackHandler(BaseCallbackHandler):
         child_span = self._create_child_span(parent_span, kwargs.get('name', 'unknown'))
 
         child_span.set_attribute(FiddlerSpanAttributes.TYPE, SpanType.TOOL)
+        child_span.set_attribute(FiddlerSpanAttributes.TOOL_NAME, kwargs.get('name', 'unknown'))
         child_span.set_attribute(FiddlerSpanAttributes.TOOL_INPUT, query)
 
         if metadata is not None:
             _set_agent_name(child_span, metadata)
             self._set_fiddler_attributes_from_metadata(child_span, metadata)
 
-        # semantic convention attributes
-        child_span.set_attribute(
-            FiddlerSpanAttributes.TYPE, SpanType.TOOL
-        )  # document retrieval is a tool
-        child_span.set_attribute(FiddlerSpanAttributes.TOOL_NAME, kwargs.get('name', 'unknown'))
-        child_span.set_attribute(FiddlerSpanAttributes.TOOL_INPUT, str(query))
         self._set_session_id(child_span)
         self._add_span(child_span, run_id)
 

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1}/fiddler_langgraph/tracing/jsonl_capture.py

@@ -1,6 +1,7 @@
 """JSONL data capture module for simplified span data in structured format."""
 
 import json
+import logging
 import os
 import threading
 from collections.abc import Sequence
@@ -13,6 +14,8 @@ from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
 from fiddler_langgraph.core.attributes import FiddlerSpanAttributes, SpanType
 
+logger = logging.getLogger(__name__)
+
 
 class JSONLSpanCapture:
     """Captures OpenTelemetry span data and saves it to JSONL format with structured fields."""
@@ -37,7 +40,7 @@ class JSONLSpanCapture:
                 self.jsonl_file_path.parent.mkdir(parents=True, exist_ok=True)
                 self.jsonl_file_path.touch()
         except Exception as e:
-            print(f'Warning: Could not create JSONL file {self.jsonl_file_path}: {e}')
+            logger.warning('Could not create JSONL file %s: %s', self.jsonl_file_path, e)
 
     def capture_span(self, span: ReadableSpan) -> None:
         """Capture a span and write it to JSONL file."""
@@ -45,7 +48,7 @@ class JSONLSpanCapture:
             span_data = self._convert_span_to_structured_format(span)
             self._write_span_to_jsonl(span_data)
         except Exception as e:
-            print(f'Error capturing span to JSONL: {e}')
+            logger.warning('Error capturing span to JSONL: %s', e)
 
     def _convert_span_to_structured_format(self, span: ReadableSpan) -> dict[str, Any]:
         """Convert ReadableSpan to structured format for JSONL export."""
@@ -156,7 +159,7 @@ class JSONLSpanCapture:
                     json.dump(span_data, f, ensure_ascii=False)
                     f.write('\n')
             except Exception as e:
-                print(f'Error writing to JSONL file {self.jsonl_file_path}: {e}')
+                logger.warning('Error writing to JSONL file %s: %s', self.jsonl_file_path, e)
 
 
 class JSONLSpanExporter(SpanExporter):
@@ -177,7 +180,7 @@ class JSONLSpanExporter(SpanExporter):
                 self.jsonl_capture.capture_span(span)
             return SpanExportResult.SUCCESS
         except Exception as e:
-            print(f'Error exporting spans to JSONL: {e}')
+            logger.warning('Error exporting spans to JSONL: %s', e)
             return SpanExportResult.FAILURE
 
 

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1}/fiddler_langgraph/tracing/util.py

@@ -42,8 +42,8 @@ class _LanggraphJSONEncoder(json.JSONEncoder):
         if hasattr(o, 'to_json'):
             return o.to_json()
 
-        if isinstance(o, BaseModel) and hasattr(o, 'model_dump_json'):
-            return o.model_dump_json()
+        if isinstance(o, BaseModel) and hasattr(o, 'model_dump'):
+            return o.model_dump()
 
         if isinstance(o, datetime.datetime):
             return o.isoformat()
@@ -68,10 +68,6 @@ def _check_langgraph_version(
     langgraph_version: pkg_version.Version,
 ) -> None:
     """Check if the installed LangGraph version is compatible with the version of fiddler-langgraph."""
-
-    if langgraph_version is None:
-        raise ImportError('Either langgraph or langchain_core should be installed')
-
     # check compatibility range
     min_langgraph_version = pkg_version.parse('0.3.28')
     max_langgraph_version = pkg_version.parse('1.1.0')

{fiddler_langgraph-1.3.0 → fiddler_langgraph-1.3.1/fiddler_langgraph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiddler-langgraph
-Version: 1.3.0
+Version: 1.3.1
 Summary: Python SDK for instrumenting GenAI Applications with Fiddler
 Home-page: https://fiddler.ai
 Author: Fiddler AI

fiddler_langgraph-1.3.0/fiddler_langgraph/VERSION

@@ -1 +0,0 @@
-1.3.0