aiqa-client 0.3.7__py3-none-any.whl → 0.4.0__py3-none-any.whl

aiqa/__init__.py

@@ -36,8 +36,7 @@ from .tracing import (
 )
 from .client import get_aiqa_client
 from .experiment_runner import ExperimentRunner
-
-__version__ = "0.3.7"
+from .constants import VERSION
 
 __all__ = [
     "WithTracing",
@@ -55,6 +54,6 @@ __all__ = [
     "set_conversation_id",
     "set_component_tag",
     "get_span",
-    "__version__",
+    "VERSION",
 ]
 

aiqa/aiqa_exporter.py

@@ -9,12 +9,12 @@ 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
-from . import __version__
+from .constants import AIQA_TRACER_NAME, VERSION
 
 logger = logging.getLogger("AIQA")
 
@@ -32,6 +32,7 @@ class AIQASpanExporter(SpanExporter):
         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.
@@ -41,12 +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()
@@ -56,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()
 
@@ -198,7 +215,7 @@ class AIQASpanExporter(SpanExporter):
         """
         return {
             "name": AIQA_TRACER_NAME,
-            "version": __version__,
+            "version": VERSION,
         }
 
     def _time_to_tuple(self, nanoseconds: int) -> tuple:
@@ -377,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)
             
@@ -439,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}")
@@ -458,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:
@@ -476,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.py

@@ -7,9 +7,6 @@ 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
@@ -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
     
@@ -252,10 +249,10 @@ def get_aiqa_tracer() -> trace.Tracer:
     """
     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 with version parameter (newer OpenTelemetry versions)
-        return trace.get_tracer(AIQA_TRACER_NAME, version=__version__)
+        return trace.get_tracer(AIQA_TRACER_NAME, version=VERSION)
     except Exception as e:
         # Log issue but still return a tracer
         logger.info(f"Issue getting AIQA tracer with version: {e}, using fallback")

aiqa/constants.py

@@ -3,3 +3,4 @@ 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.7.dist-info → aiqa_client-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.7
+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

aiqa_client-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+aiqa/__init__.py,sha256=MZGvPF4XM_EuBRiiAR6EA1bzctLpzmE6crcjuh3Ve6o,1459
+aiqa/aiqa_exporter.py,sha256=-yPJscH0Wc9yIVetwJiOAiwEqFQnL6AYXo_FwsoYGaE,30482
+aiqa/client.py,sha256=wYoVvOHoGnkc3qsEHL5vMRW13hOFPR2d9s_MPKGAbpE,9538
+aiqa/constants.py,sha256=hXRiXeNgAqLOizNeSgucSAMkFO0wGMtpZ2qjKhUWWhA,153
+aiqa/experiment_runner.py,sha256=ZEDwECstAv4lWXpcdB9WSxfDQj43iqkGzB_YzoY933M,12053
+aiqa/object_serialiser.py,sha256=pgcBVw5sZH8f7N6n3-qOvEcbNhuPS5yq7qdhaNT6Sks,15236
+aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiqa/test_experiment_runner.py,sha256=LM8BuCrzBZL0Wyu_ierK0tNLsOUxxMTAHbAGW2G0qp0,5562
+aiqa/test_tracing.py,sha256=mSVrhRQ6Dz5djlSUkCt097sIr84562w6E0BnuQDpMrI,8347
+aiqa/tracing.py,sha256=SsuK6WNgk3LbWt1aQwPPIDhitBmtyU6GOsMRvouXpDw,49706
+aiqa_client-0.4.0.dist-info/licenses/LICENSE,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
+aiqa_client-0.4.0.dist-info/METADATA,sha256=toA-KJzaC0mlWOsYhqHqj83ASP83sox_7wowMczaxrE,7505
+aiqa_client-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aiqa_client-0.4.0.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
+aiqa_client-0.4.0.dist-info/RECORD,,

aiqa_client-0.3.7.dist-info/RECORD

@@ -1,15 +0,0 @@
-aiqa/__init__.py,sha256=dnCT31jRL0nUeSvHksUris3_7lxlxChfzshxY7_gHlk,1455
-aiqa/aiqa_exporter.py,sha256=MbA7SkJoNm03dvrcGteU57Y0YNpVw8fzL_W-RI2lI0Q,27698
-aiqa/client.py,sha256=TolaBb7ZnnD5SawclI9KMBsdGKaAosTxvLVeGlKseAA,9599
-aiqa/constants.py,sha256=3QLmyhyVayKebM5N50P1oYbI0LtQmqxTp17UZnUeixc,89
-aiqa/experiment_runner.py,sha256=ZEDwECstAv4lWXpcdB9WSxfDQj43iqkGzB_YzoY933M,12053
-aiqa/object_serialiser.py,sha256=pgcBVw5sZH8f7N6n3-qOvEcbNhuPS5yq7qdhaNT6Sks,15236
-aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aiqa/test_experiment_runner.py,sha256=LM8BuCrzBZL0Wyu_ierK0tNLsOUxxMTAHbAGW2G0qp0,5562
-aiqa/test_tracing.py,sha256=mSVrhRQ6Dz5djlSUkCt097sIr84562w6E0BnuQDpMrI,8347
-aiqa/tracing.py,sha256=SsuK6WNgk3LbWt1aQwPPIDhitBmtyU6GOsMRvouXpDw,49706
-aiqa_client-0.3.7.dist-info/licenses/LICENSE,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
-aiqa_client-0.3.7.dist-info/METADATA,sha256=LSshQdYneT3PfZIy19TwBt6Ow8L7IlJYHmx3EPH32pg,7505
-aiqa_client-0.3.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aiqa_client-0.3.7.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
-aiqa_client-0.3.7.dist-info/RECORD,,