aiqa-client 0.3.6__tar.gz → 0.3.7__tar.gz

{aiqa_client-0.3.6/aiqa_client.egg-info → aiqa_client-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.6
+Version: 0.3.7
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -134,12 +134,12 @@ asyncio.run(main())
 To ensure all spans are sent before process exit:
 
 ```python
-from aiqa import shutdown_tracing
+from aiqa import flush_tracing
 import asyncio
 
 async def main():
     # Your code here
-    await shutdown_tracing()
+    await flush_tracing()
 
 asyncio.run(main())
 ```
@@ -154,10 +154,10 @@ from aiqa import get_aiqa_client
 client = get_aiqa_client()
 
 # Disable tracing (spans won't be created or exported)
-client.set_enabled(False)
+client.enabled = False
 
 # Re-enable tracing
-client.set_enabled(True)
+client.enabled = True
 
 # Check if tracing is enabled
 if client.enabled:

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/README.md

@@ -97,12 +97,12 @@ asyncio.run(main())
 To ensure all spans are sent before process exit:
 
 ```python
-from aiqa import shutdown_tracing
+from aiqa import flush_tracing
 import asyncio
 
 async def main():
     # Your code here
-    await shutdown_tracing()
+    await flush_tracing()
 
 asyncio.run(main())
 ```
@@ -117,10 +117,10 @@ from aiqa import get_aiqa_client
 client = get_aiqa_client()
 
 # Disable tracing (spans won't be created or exported)
-client.set_enabled(False)
+client.enabled = False
 
 # Re-enable tracing
-client.set_enabled(True)
+client.enabled = True
 
 # Check if tracing is enabled
 if client.enabled:

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/aiqa/__init__.py

@@ -22,12 +22,9 @@ Example:
 from .tracing import (
     WithTracing,
     flush_tracing,
-    shutdown_tracing,
     set_span_attribute,
     set_span_name,
     get_active_span,
-    get_provider,
-    get_exporter,
     get_active_trace_id,
     get_span_id,
     create_span_from_trace_id,
@@ -37,22 +34,18 @@ from .tracing import (
     set_component_tag,
     get_span,
 )
-from .client import get_aiqa_client, set_enabled
+from .client import get_aiqa_client
 from .experiment_runner import ExperimentRunner
 
-__version__ = "0.3.6"
+__version__ = "0.3.7"
 
 __all__ = [
     "WithTracing",
     "flush_tracing",
-    "shutdown_tracing",
     "set_span_attribute",
     "set_span_name",
     "get_active_span",
-    "get_provider",
-    "get_exporter",
     "get_aiqa_client",
-    "set_enabled",
     "ExperimentRunner",
     "get_active_trace_id",
     "get_span_id",

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/aiqa/aiqa_exporter.py

@@ -13,6 +13,9 @@ from typing import List, Dict, Any, Optional
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
+from .constants import AIQA_TRACER_NAME
+from . import __version__
+
 logger = logging.getLogger("AIQA")
 
 
@@ -28,6 +31,7 @@ class AIQASpanExporter(SpanExporter):
         api_key: Optional[str] = None,
         flush_interval_seconds: float = 5.0,
         max_batch_size_bytes: int = 5 * 1024 * 1024,  # 5MB default
+        max_buffer_spans: int = 10000,  # Maximum spans to buffer (prevents unbounded growth)
     ):
         """
         Initialize the AIQA span exporter.
@@ -42,6 +46,7 @@ class AIQASpanExporter(SpanExporter):
         self._api_key = api_key
         self.flush_interval_ms = flush_interval_seconds * 1000
         self.max_batch_size_bytes = max_batch_size_bytes
+        self.max_buffer_spans = max_buffer_spans
         self.buffer: List[Dict[str, Any]] = []
         self.buffer_span_keys: set = set()  # Track (traceId, spanId) tuples to prevent duplicates (Python 3.8 compatible)
         self.buffer_lock = threading.Lock()
@@ -88,7 +93,13 @@ class AIQASpanExporter(SpanExporter):
         with self.buffer_lock:
             serialized_spans = []
             duplicates_count = 0
+            dropped_count = 0
             for span in spans:
+                # Check if buffer is full (prevent unbounded growth)
+                if len(self.buffer) >= self.max_buffer_spans:
+                    dropped_count += 1
+                    continue
+                
                 serialized = self._serialize_span(span)
                 span_key = (serialized["traceId"], serialized["spanId"])
                 if span_key not in self.buffer_span_keys:
@@ -100,6 +111,12 @@ class AIQASpanExporter(SpanExporter):
             
             self.buffer.extend(serialized_spans)
             buffer_size = len(self.buffer)
+            
+            if dropped_count > 0:
+                logger.warning(
+                    f"WARNING: Buffer full ({buffer_size} spans), dropped {dropped_count} span(s). "
+                    f"Consider increasing max_buffer_spans or fixing server connectivity."
+                )
         
         if duplicates_count > 0:
             logger.debug(
@@ -172,10 +189,16 @@ class AIQASpanExporter(SpanExporter):
             "traceFlags": span_context.trace_flags,
             "duration": self._time_to_tuple(span.end_time - span.start_time) if span.end_time else None,
             "ended": span.end_time is not None,
-            "instrumentationLibrary": {
-                "name": self._get_instrumentation_name(),
-                "version": self._get_instrumentation_version(),
-            },
+            "instrumentationLibrary": self._get_instrumentation_library(span),
+        }
+
+    def _get_instrumentation_library(self, span: ReadableSpan) -> Dict[str, Any]:
+        """
+        Get instrumentation library information from the span: just use the package version.
+        """
+        return {
+            "name": AIQA_TRACER_NAME,
+            "version": __version__,
         }
 
     def _time_to_tuple(self, nanoseconds: int) -> tuple:
@@ -183,19 +206,6 @@ class AIQASpanExporter(SpanExporter):
         seconds = int(nanoseconds // 1_000_000_000)
         nanos = int(nanoseconds % 1_000_000_000)
         return (seconds, nanos)
-    
-    def _get_instrumentation_name(self) -> str:
-        """Get instrumentation library name - always 'aiqa-tracer'."""
-        from .client import AIQA_TRACER_NAME
-        return AIQA_TRACER_NAME
-    
-    def _get_instrumentation_version(self) -> Optional[str]:
-        """Get instrumentation library version from __version__."""
-        try:
-            from . import __version__
-            return __version__
-        except (ImportError, AttributeError):
-            return None
 
     def _build_request_headers(self) -> Dict[str, str]:
         """Build HTTP headers for span requests."""

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/aiqa/client.py

@@ -2,17 +2,20 @@
 import os
 import logging
 from functools import lru_cache
-from typing import Optional
+from typing import Optional, TYPE_CHECKING, Any
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
+if TYPE_CHECKING:
+    from .aiqa_exporter import AIQASpanExporter
+
 logger = logging.getLogger("AIQA")
 
 # Compatibility import for TraceIdRatioBased sampler
 # In older OpenTelemetry versions it was TraceIdRatioBasedSampler
 # In newer versions (>=1.24.0) it's TraceIdRatioBased
-TraceIdRatioBased = None
+TraceIdRatioBased: Optional[Any] = None
 try:
     from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
 except ImportError:
@@ -28,10 +31,7 @@ except ImportError:
         # Set to None so we can check later
         TraceIdRatioBased = None
 
-from .aiqa_exporter import AIQASpanExporter
-
-AIQA_TRACER_NAME = "aiqa-tracer"
-
+from .constants import AIQA_TRACER_NAME
 
 class AIQAClient:
     """
@@ -78,32 +78,38 @@ class AIQAClient:
     
     @enabled.setter
     def enabled(self, value: bool) -> None:
-        """Set the enabled state."""
-        self._enabled = value
-    
-    def set_enabled(self, enabled: bool) -> None:
-        """
-        Enable or disable AIQA tracing.
+        """Set the enabled state.
         
         When disabled:
         - Tracing does not create spans
         - Export does not send spans
-        
-        Args:
-            enabled: True to enable tracing, False to disable
         """
-        self._enabled = enabled
-        if enabled:
-            logger.info("AIQA tracing enabled")
-        else:
-            logger.info("AIQA tracing disabled")
+        logger.info(f"AIQA tracing {'enabled' if value else 'disabled'}")
+        self._enabled = value
     
-    def is_enabled(self) -> bool:
-        """Check if tracing is enabled."""
-        return self._enabled
+    def shutdown(self) -> None:
+        """
+        Shutdown the tracer provider and exporter.
+        It is not necessary to call this function. 
+        Use this to clean up resources at the end of all tracing.
+        
+        This will also set enabled=False to prevent further tracing attempts.
+        """
+        try:
+            logger.info("AIQA tracing shutting down")
+            # Disable tracing to prevent attempts to use shut-down system
+            self.enabled = False
+            if self._provider:
+                self._provider.shutdown()
+            if self._exporter:
+                self._exporter.shutdown()
+        except Exception as e:
+            logger.error(f"Error shutting down tracing: {e}")
+            # Still disable even if shutdown had errors
+            self.enabled = False
 
 
-# Global singleton instance (for backward compatibility with direct access)
+# Global singleton instance
 client: AIQAClient = AIQAClient()
 
 # Component tag to add to all spans (can be set via AIQA_COMPONENT_TAG env var or programmatically)
@@ -154,24 +160,19 @@ def get_aiqa_client() -> AIQAClient:
         logger.warning("AIQA tracing is disabled. Your application will continue to run without tracing.")
     return client
 
-def _init_tracing():
+def _init_tracing() -> None:
     """Initialize tracing system and load configuration from environment variables."""
     global client
     if client._initialized:
         return
     
     try:
-        # Check for required environment variables
         server_url = os.getenv("AIQA_SERVER_URL")
         api_key = os.getenv("AIQA_API_KEY")
         
         if not server_url or not api_key:
             client.enabled = False
-            missing_vars = []
-            if not server_url:
-                missing_vars.append("AIQA_SERVER_URL")
-            if not api_key:
-                missing_vars.append("AIQA_API_KEY")
+            missing_vars = [var for var, val in [("AIQA_SERVER_URL", server_url), ("AIQA_API_KEY", api_key)] if not val]
             logger.warning(
                 f"AIQA tracing is disabled: missing required environment variables: {', '.join(missing_vars)}"
             )
@@ -218,10 +219,12 @@ def _init_tracing():
         client._initialized = True  # Mark as initialized even on error to prevent retry loops
         raise
 
-def _attach_aiqa_processor(provider: TracerProvider):
+def _attach_aiqa_processor(provider: TracerProvider) -> None:
     """Attach AIQA span processor to the provider. Idempotent - safe to call multiple times."""
+    from .aiqa_exporter import AIQASpanExporter
+    
     try:
-        # Avoid double-adding if get_aiqa_client() is called multiple times
+        # Check if already attached
         for p in provider._active_span_processor._span_processors:
             if isinstance(getattr(p, "exporter", None), AIQASpanExporter):
                 logger.debug("AIQA span processor already attached, skipping")
@@ -241,44 +244,19 @@ def _attach_aiqa_processor(provider: TracerProvider):
         raise
 
 
-def set_enabled(enabled: bool) -> None:
-    """
-    Enable or disable AIQA tracing.
-    
-    When disabled:
-    - Tracing does not create spans
-    - Export does not send spans
-    
-    Args:
-        enabled: True to enable tracing, False to disable
-    
-    Example:
-        from aiqa import get_aiqa_client
-        
-        client = get_aiqa_client()
-        client.set_enabled(False)  # Disable tracing
-    """
-    client = get_aiqa_client()
-    client.set_enabled(enabled)
 
-
-def get_aiqa_tracer():
+def get_aiqa_tracer() -> trace.Tracer:
     """
     Get the AIQA tracer with version from __init__.py __version__.
-    This should be used instead of trace.get_tracer() to ensure version is set.
+    This should be used instead of trace.get_tracer() so that the version is set.
     """
     try:
         # Import here to avoid circular import
         from . import __version__
-        
         # Compatibility: version parameter may not be supported in older OpenTelemetry versions
-        try:
-            # Try with version parameter (newer OpenTelemetry versions)
-            return trace.get_tracer(AIQA_TRACER_NAME, version=__version__)
-        except TypeError:
-            # Fall back to without version parameter (older versions)
-            return trace.get_tracer(AIQA_TRACER_NAME)
+        # Try with version parameter (newer OpenTelemetry versions)
+        return trace.get_tracer(AIQA_TRACER_NAME, version=__version__)
     except Exception as e:
-        logger.error(f"Error getting AIQA tracer: {e}")
-        # Return a basic tracer as fallback to prevent crashes
+        # Log issue but still return a tracer
+        logger.info(f"Issue getting AIQA tracer with version: {e}, using fallback")
         return trace.get_tracer(AIQA_TRACER_NAME)

aiqa_client-0.3.7/aiqa/constants.py

@@ -0,0 +1,5 @@
+"""
+Constants used across the AIQA client package.
+"""
+
+AIQA_TRACER_NAME = "aiqa-tracer"

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/aiqa/tracing.py

@@ -14,7 +14,8 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.trace import Status, StatusCode, SpanContext, TraceFlags
 from opentelemetry.propagate import inject, extract
 from .aiqa_exporter import AIQASpanExporter
-from .client import get_aiqa_client, AIQA_TRACER_NAME, get_component_tag, set_component_tag as _set_component_tag, get_aiqa_tracer
+from .client import get_aiqa_client, get_component_tag, set_component_tag as _set_component_tag, get_aiqa_tracer
+from .constants import AIQA_TRACER_NAME
 from .object_serialiser import serialize_for_span
 
 logger = logging.getLogger("AIQA")
@@ -25,6 +26,7 @@ async def flush_tracing() -> None:
     Flush all pending spans to the server.
     Flushes also happen automatically every few seconds. So you only need to call this function
     if you want to flush immediately, e.g. before exiting a process.
+    A common use is if you are tracing unit tests or experiment runs.
 
     This flushes both the BatchSpanProcessor and the exporter buffer.
     """
@@ -35,25 +37,10 @@ async def flush_tracing() -> None:
         await client.exporter.flush()
 
 
-async def shutdown_tracing() -> None:
-    """
-    Shutdown the tracer provider and exporter.
-    It is not necessary to call this function.
-    """
-    try:
-        client = get_aiqa_client()
-        if client.provider:
-            client.provider.shutdown()  # Synchronous method
-        if client.exporter:
-            client.exporter.shutdown()  # Synchronous method
-    except Exception as e:
-        logger.error(f"Error shutting down tracing: {e}")
-
-
 # Export provider and exporter accessors for advanced usage
 
 __all__ = [
-    "get_provider", "get_exporter", "flush_tracing", "shutdown_tracing", "WithTracing",
+    "flush_tracing", "WithTracing",
     "set_span_attribute", "set_span_name", "get_active_span",
     "get_active_trace_id", "get_span_id", "create_span_from_trace_id", "inject_trace_context", "extract_trace_context",
     "set_conversation_id", "set_component_tag", "set_token_usage", "set_provider_and_model", "get_span", "submit_feedback"
@@ -969,16 +956,6 @@ def set_component_tag(tag: str) -> None:
     """
     _set_component_tag(tag)
 
-def get_provider() -> Optional[TracerProvider]:
-    """Get the tracer provider for advanced usage."""
-    client = get_aiqa_client()
-    return client.provider
-
-def get_exporter() -> Optional[AIQASpanExporter]:
-    """Get the exporter for advanced usage."""
-    client = get_aiqa_client()
-    return client.exporter
-
 
 def get_active_trace_id() -> Optional[str]:
     """

{aiqa_client-0.3.6 → aiqa_client-0.3.7/aiqa_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.6
+Version: 0.3.7
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -134,12 +134,12 @@ asyncio.run(main())
 To ensure all spans are sent before process exit:
 
 ```python
-from aiqa import shutdown_tracing
+from aiqa import flush_tracing
 import asyncio
 
 async def main():
     # Your code here
-    await shutdown_tracing()
+    await flush_tracing()
 
 asyncio.run(main())
 ```
@@ -154,10 +154,10 @@ from aiqa import get_aiqa_client
 client = get_aiqa_client()
 
 # Disable tracing (spans won't be created or exported)
-client.set_enabled(False)
+client.enabled = False
 
 # Re-enable tracing
-client.set_enabled(True)
+client.enabled = True
 
 # Check if tracing is enabled
 if client.enabled:

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/aiqa_client.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ setup.py
 aiqa/__init__.py
 aiqa/aiqa_exporter.py
 aiqa/client.py
+aiqa/constants.py
 aiqa/experiment_runner.py
 aiqa/object_serialiser.py
 aiqa/py.typed

{aiqa_client-0.3.6 → aiqa_client-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aiqa-client"
-version = "0.3.6"
+version = "0.3.7"
 description = "OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server"
 readme = "README.md"
 requires-python = ">=3.8"