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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.6
+Version: 0.4.0
 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.4.0}/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.4.0}/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,17 @@ 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"
+from .constants import VERSION
 
 __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",
@@ -62,6 +54,6 @@ __all__ = [
     "set_conversation_id",
     "set_component_tag",
     "get_span",
-    "__version__",
+    "VERSION",
 ]
 

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

@@ -9,10 +9,13 @@ import logging
 import threading
 import time
 import io
+import asyncio
 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, VERSION
+
 logger = logging.getLogger("AIQA")
 
 
@@ -28,6 +31,8 @@ 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)
+        startup_delay_seconds: Optional[float] = None,
     ):
         """
         Initialize the AIQA span exporter.
@@ -37,11 +42,28 @@ class AIQASpanExporter(SpanExporter):
             api_key: API key for authentication (defaults to AIQA_API_KEY env var)
             flush_interval_seconds: How often to flush spans to the server
             max_batch_size_bytes: Maximum size of a single batch in bytes (default: 5mb)
+            max_buffer_spans: Maximum spans to buffer (prevents unbounded growth)
+            startup_delay_seconds: Delay before starting auto-flush (default: 10s, or AIQA_STARTUP_DELAY_SECONDS env var)
         """
         self._server_url = server_url
         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
+        
+        # Get startup delay from parameter or environment variable (default: 10s)
+        if startup_delay_seconds is None:
+            env_delay = os.getenv("AIQA_STARTUP_DELAY_SECONDS")
+            if env_delay:
+                try:
+                    startup_delay_seconds = float(env_delay)
+                except ValueError:
+                    logger.warning(f"Invalid AIQA_STARTUP_DELAY_SECONDS value '{env_delay}', using default 10.0")
+                    startup_delay_seconds = 10.0
+            else:
+                startup_delay_seconds = 10.0
+        self.startup_delay_seconds = startup_delay_seconds
+        
         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()
@@ -51,7 +73,7 @@ class AIQASpanExporter(SpanExporter):
         
         logger.info(
             f"Initializing AIQASpanExporter: server_url={self.server_url or 'not set'}, "
-            f"flush_interval={flush_interval_seconds}s"
+            f"flush_interval={flush_interval_seconds}s, startup_delay={startup_delay_seconds}s"
         )
         self._start_auto_flush()
 
@@ -88,7 +110,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 +128,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 +206,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 +223,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."""
@@ -367,16 +394,38 @@ class AIQASpanExporter(SpanExporter):
                     raise
 
     def _start_auto_flush(self) -> None:
-        """Start the auto-flush timer."""
+        """Start the auto-flush timer with startup delay."""
         if self.shutdown_requested:
             logger.warning("_start_auto_flush() called but shutdown already requested")
             return
 
-        logger.info(f"Starting auto-flush thread with interval {self.flush_interval_ms / 1000.0}s")
+        logger.info(
+            f"Starting auto-flush thread with interval {self.flush_interval_ms / 1000.0}s, "
+            f"startup delay {self.startup_delay_seconds}s"
+        )
 
         def flush_worker():
             import asyncio
             logger.debug("Auto-flush worker thread started")
+            
+            # Wait for startup delay before beginning flush operations
+            # This gives the container/application time to stabilize, which helps avoid startup issues (seen with AWS ECS, Dec 2025).
+            if self.startup_delay_seconds > 0:
+                logger.info(f"Auto-flush waiting {self.startup_delay_seconds}s before first flush (startup delay)")
+                # Sleep in small increments to allow for early shutdown
+                sleep_interval = 0.5
+                remaining_delay = self.startup_delay_seconds
+                while remaining_delay > 0 and not self.shutdown_requested:
+                    sleep_time = min(sleep_interval, remaining_delay)
+                    time.sleep(sleep_time)
+                    remaining_delay -= sleep_time
+                
+                if self.shutdown_requested:
+                    logger.debug("Auto-flush startup delay interrupted by shutdown")
+                    return
+                
+                logger.info("Auto-flush startup delay complete, beginning flush operations")
+            
             loop = asyncio.new_event_loop()
             asyncio.set_event_loop(loop)
             
@@ -429,8 +478,10 @@ class AIQASpanExporter(SpanExporter):
         else:
             logger.debug("_send_spans() no API key provided")
 
+        # Use timeout to prevent hanging on unreachable servers
+        timeout = aiohttp.ClientTimeout(total=30.0, connect=10.0)
         errors = []
-        async with aiohttp.ClientSession() as session:
+        async with aiohttp.ClientSession(timeout=timeout) as session:
             for batch_idx, batch in enumerate(batches):
                 try:
                     logger.debug(f"_send_spans() sending batch {batch_idx + 1}/{len(batches)} with {len(batch)} spans to {url}")
@@ -448,6 +499,12 @@ class AIQASpanExporter(SpanExporter):
                             # Continue with other batches even if one fails
                             continue
                         logger.debug(f"_send_spans() batch {batch_idx + 1} successfully sent {len(batch)} spans")
+                except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                    # Network errors and timeouts - log but don't fail completely
+                    error_msg = f"Network error in batch {batch_idx + 1}: {type(e).__name__}: {e}"
+                    logger.warning(f"_send_spans() {error_msg} - will retry on next flush")
+                    errors.append((batch_idx + 1, error_msg))
+                    # Continue with other batches
                 except RuntimeError as e:
                     if self._is_interpreter_shutdown_error(e):
                         if self.shutdown_requested:
@@ -466,6 +523,7 @@ class AIQASpanExporter(SpanExporter):
                     # Continue with other batches
         
         # If any batches failed, raise an exception with details
+        # Spans will be restored to buffer for retry on next flush
         if errors:
             error_summary = "; ".join([f"batch {idx}: {msg}" for idx, msg in errors])
             raise Exception(f"Failed to send some spans: {error_summary}")

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

@@ -2,7 +2,7 @@
 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
@@ -12,7 +12,7 @@ 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 +28,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:
     """
@@ -46,7 +43,7 @@ class AIQAClient:
         if cls._instance is None:
             cls._instance = super().__new__(cls)
             cls._instance._provider: Optional[TracerProvider] = None
-            cls._instance._exporter: Optional[AIQASpanExporter] = None
+            cls._instance._exporter = None # reduce circular import issues by not importing for typecheck here
             cls._instance._enabled: bool = True
             cls._instance._initialized: bool = False
         return cls._instance
@@ -62,12 +59,12 @@ class AIQAClient:
         self._provider = value
     
     @property
-    def exporter(self) -> Optional[AIQASpanExporter]:
+    def exporter(self) -> Optional[Any]:
         """Get the span exporter."""
         return self._exporter
     
     @exporter.setter
-    def exporter(self, value: Optional[AIQASpanExporter]) -> None:
+    def exporter(self, value: Optional[Any]) -> None:
         """Set the span exporter."""
         self._exporter = value
     
@@ -78,32 +75,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 +157,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 +216,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 +241,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__
-        
+        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.4.0/aiqa/constants.py

@@ -0,0 +1,6 @@
+"""
+Constants used across the AIQA client package.
+"""
+
+AIQA_TRACER_NAME = "aiqa-tracer"
+VERSION = "0.4.0" # automatically updated by set-version-json.sh

{aiqa_client-0.3.6 → aiqa_client-0.4.0}/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.4.0/aiqa_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.6
+Version: 0.4.0
 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.4.0}/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.4.0}/pyproject.toml

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