aiqa-client 0.4.7__py3-none-any.whl → 0.5.2__py3-none-any.whl

aiqa/__init__.py

@@ -6,7 +6,7 @@ The client initializes automatically when WithTracing is first used.
 
 Set environment variables:
     AIQA_SERVER_URL: URL of the AIQA server
-    AIQA_API_KEY: API key for authentication
+    AIQA_API_KEY: API key for authentication (required)
     AIQA_COMPONENT_TAG: Optional component identifier
     AIQA_STARTUP_DELAY_SECONDS: Optional delay before first flush (default: 10s)
 

aiqa/client.py

@@ -2,10 +2,12 @@
 import os
 import logging
 from functools import lru_cache
-from typing import Optional, TYPE_CHECKING, Any
+from typing import Optional, TYPE_CHECKING, Any, Dict
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+import requests
 
 from .constants import AIQA_TRACER_NAME, LOG_TAG
 
@@ -30,7 +32,7 @@ except ImportError:
         # Set to None so we can check later
         TraceIdRatioBased = None
 
-from .http_utils import get_server_url, get_api_key
+from .http_utils import get_server_url, get_api_key, build_headers, format_http_error
 
 class AIQAClient:
     """
@@ -100,14 +102,14 @@ class AIQAClient:
             self.enabled = False
             if self._provider:
                 self._provider.shutdown()
-            if self._exporter:
-                self._exporter.shutdown()
+            # OTLP exporter doesn't have a separate shutdown method - it's handled by the provider
         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
 client: AIQAClient = AIQAClient()
 
@@ -176,11 +178,10 @@ def _init_tracing() -> None:
         server_url = get_server_url()
         api_key = get_api_key()
         
-        if not server_url or not api_key:
+        if not api_key:
             client.enabled = False
-            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)}"
+                f"AIQA tracing is disabled: missing required environment variables: AIQA_API_KEY"
             )
             client._initialized = True
             return
@@ -227,20 +228,39 @@ def _init_tracing() -> None:
 
 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:
         # Check if already attached
         for p in provider._active_span_processor._span_processors:
-            if isinstance(getattr(p, "exporter", None), AIQASpanExporter):
+            if isinstance(getattr(p, "exporter", None), OTLPSpanExporter):
                 logger.debug(f"AIQA span processor already attached, skipping")
                 return
 
-        exporter = AIQASpanExporter(
-            server_url=os.getenv("AIQA_SERVER_URL"),
-            api_key=os.getenv("AIQA_API_KEY"),
-            # max_buffer_spans will be read from AIQA_MAX_BUFFER_SPANS env var by the exporter
+        server_url = get_server_url()
+        api_key = get_api_key()
+        
+        # Build headers for authentication
+        # OTLP exporter sets its own Content-Type, so we only need Authorization
+        auth_headers = {}
+        if api_key:
+            auth_headers["Authorization"] = f"ApiKey {api_key}"
+        elif os.getenv("AIQA_API_KEY"):
+            auth_headers["Authorization"] = f"ApiKey {os.getenv('AIQA_API_KEY')}"
+        
+        # OTLP HTTP exporter requires the full endpoint URL including /v1/traces
+        # Ensure server_url doesn't have trailing slash or /v1/traces, then append /v1/traces
+        base_url = server_url.rstrip('/')
+        if base_url.endswith('/v1/traces'):
+            endpoint = base_url
+        else:
+            endpoint = f"{base_url}/v1/traces"
+        
+        # Create OTLP exporter with authentication headers only
+        # The exporter will set Content-Type and other headers automatically
+        exporter = OTLPSpanExporter(
+            endpoint=endpoint,
+            headers=auth_headers if auth_headers else None,
         )
+        
         provider.add_span_processor(BatchSpanProcessor(exporter))
         global client
         client.exporter = exporter
@@ -266,4 +286,66 @@ def get_aiqa_tracer() -> trace.Tracer:
     except Exception as e:
         # 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)
+        return trace.get_tracer(AIQA_TRACER_NAME)
+
+
+def get_organisation(
+    organisation_id: str,
+    server_url: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Get organisation information based on API key via an API call.
+    
+    Args:
+        organisation_id: ID of the organisation to retrieve
+        server_url: Optional server URL (defaults to AIQA_SERVER_URL env var)
+        api_key: Optional API key (defaults to AIQA_API_KEY env var)
+    
+    Returns:
+        Organisation object as a dictionary
+    """
+    url = get_server_url(server_url)
+    key = get_api_key(api_key)
+    headers = build_headers(key)
+    
+    response = requests.get(
+        f"{url}/organisation/{organisation_id}",
+        headers=headers,
+    )
+    
+    if not response.ok:
+        raise Exception(format_http_error(response, "get organisation"))
+    
+    return response.json()
+
+
+def get_api_key_info(
+    api_key_id: str,
+    server_url: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Get API key information via an API call.
+    
+    Args:
+        api_key_id: ID of the API key to retrieve
+        server_url: Optional server URL (defaults to AIQA_SERVER_URL env var)
+        api_key: Optional API key (defaults to AIQA_API_KEY env var)
+    
+    Returns:
+        ApiKey object as a dictionary
+    """
+    url = get_server_url(server_url)
+    key = get_api_key(api_key)
+    headers = build_headers(key)
+    
+    response = requests.get(
+        f"{url}/api-key/{api_key_id}",
+        headers=headers,
+    )
+    
+    if not response.ok:
+        raise Exception(format_http_error(response, "get api key info"))
+    
+    return response.json()

aiqa/constants.py

@@ -3,6 +3,6 @@ Constants used across the AIQA client package.
 """
 
 AIQA_TRACER_NAME = "aiqa-tracer"
-VERSION = "0.4.7" # automatically updated by set-version-json.sh
+VERSION = "0.5.2" # automatically updated by set-version-json.sh
 
 LOG_TAG = "AIQA" # Used in all logging output to identify AIQA messages

aiqa/http_utils.py

@@ -1,6 +1,7 @@
 """
 Shared HTTP utilities for AIQA client.
 Provides common functions for building headers, handling errors, and accessing environment variables.
+Supports AIQA-specific env vars (AIQA_SERVER_URL, AIQA_API_KEY) with fallback to OTLP standard vars.
 """
 
 import os
@@ -11,17 +12,46 @@ def build_headers(api_key: Optional[str] = None) -> Dict[str, str]:
     """
     Build HTTP headers for AIQA API requests.
     
+    Checks AIQA_API_KEY first, then falls back to OTEL_EXPORTER_OTLP_HEADERS if not set.
+    
     Args:
-        api_key: Optional API key. If not provided, will try to get from AIQA_API_KEY env var.
+        api_key: Optional API key. If not provided, will try to get from AIQA_API_KEY env var,
+                 then from OTEL_EXPORTER_OTLP_HEADERS.
     
     Returns:
-        Dictionary with Content-Type and optionally Authorization header.
+        Dictionary with Content-Type, Accept-Encoding, and optionally Authorization header.
     """
-    headers = {"Content-Type": "application/json"}
+    headers = {
+        "Content-Type": "application/json",
+        "Accept-Encoding": "gzip, deflate, br",  # Request compression (aiohttp handles decompression automatically)
+    }
+    
+    # Check parameter first
     if api_key:
         headers["Authorization"] = f"ApiKey {api_key}"
-    elif os.getenv("AIQA_API_KEY"):
-        headers["Authorization"] = f"ApiKey {os.getenv('AIQA_API_KEY')}"
+        return headers
+    
+    # Check AIQA_API_KEY env var
+    aiqa_api_key = os.getenv("AIQA_API_KEY")
+    if aiqa_api_key:
+        headers["Authorization"] = f"ApiKey {aiqa_api_key}"
+        return headers
+    
+    # Fallback to OTLP headers (format: "key1=value1,key2=value2")
+    otlp_headers = os.getenv("OTEL_EXPORTER_OTLP_HEADERS")
+    if otlp_headers:
+        # Parse comma-separated key=value pairs
+        for header_pair in otlp_headers.split(","):
+            header_pair = header_pair.strip()
+            if "=" in header_pair:
+                key, value = header_pair.split("=", 1)
+                key = key.strip()
+                value = value.strip()
+                if key.lower() == "authorization":
+                    headers["Authorization"] = value
+                else:
+                    headers[key] = value
+    
     return headers
 
 
@@ -29,27 +59,71 @@ def get_server_url(server_url: Optional[str] = None) -> str:
     """
     Get server URL from parameter or environment variable, with trailing slash removed.
     
+    Checks AIQA_SERVER_URL first, then falls back to OTEL_EXPORTER_OTLP_ENDPOINT if not set.
+    
     Args:
-        server_url: Optional server URL. If not provided, will get from AIQA_SERVER_URL env var.
+        server_url: Optional server URL. If not provided, will get from AIQA_SERVER_URL env var,
+                    then from OTEL_EXPORTER_OTLP_ENDPOINT.
     
     Returns:
-        Server URL with trailing slash removed, or empty string if not set.
+        Server URL with trailing slash removed. Defaults to https://server-aiqa.winterwell.com if not set.
     """
-    url = server_url or os.getenv("AIQA_SERVER_URL", "")
-    return url.rstrip("/")
+    # Check parameter first
+    if server_url:
+        return server_url.rstrip("/")
+    
+    # Check AIQA_SERVER_URL env var
+    url = os.getenv("AIQA_SERVER_URL")
+    if url:
+        return url.rstrip("/")
+    
+    # Fallback to OTLP endpoint
+    url = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+    if url:
+        return url.rstrip("/")
+    
+    # Default fallback
+    return "https://server-aiqa.winterwell.com"
 
 
 def get_api_key(api_key: Optional[str] = None) -> str:
     """
     Get API key from parameter or environment variable.
     
+    Checks AIQA_API_KEY first, then falls back to OTEL_EXPORTER_OTLP_HEADERS if not set.
+    
     Args:
-        api_key: Optional API key. If not provided, will get from AIQA_API_KEY env var.
+        api_key: Optional API key. If not provided, will get from AIQA_API_KEY env var,
+                 then from OTEL_EXPORTER_OTLP_HEADERS (looking for Authorization header).
     
     Returns:
         API key or empty string if not set.
     """
-    return api_key or os.getenv("AIQA_API_KEY", "")
+    # Check parameter first
+    if api_key:
+        return api_key
+    
+    # Check AIQA_API_KEY env var
+    aiqa_api_key = os.getenv("AIQA_API_KEY")
+    if aiqa_api_key:
+        return aiqa_api_key
+    
+    # Fallback to OTLP headers (look for Authorization header)
+    otlp_headers = os.getenv("OTEL_EXPORTER_OTLP_HEADERS")
+    if otlp_headers:
+        for header_pair in otlp_headers.split(","):
+            header_pair = header_pair.strip()
+            if "=" in header_pair:
+                key, value = header_pair.split("=", 1)
+                key = key.strip()
+                value = value.strip()
+                if key.lower() == "authorization":
+                    # Extract API key from "ApiKey <key>" or just return the value
+                    if value.startswith("ApiKey "):
+                        return value[7:]
+                    return value
+    
+    return ""
 
 
 def format_http_error(response, operation: str) -> str:

aiqa/tracing.py

@@ -8,13 +8,13 @@ import logging
 import inspect
 import os
 import copy
+import requests
 from typing import Any, Callable, Optional, List
 from functools import wraps
 from opentelemetry import trace
 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, get_component_tag, set_component_tag as _set_component_tag, get_aiqa_tracer
 from .constants import AIQA_TRACER_NAME, LOG_TAG
 from .object_serialiser import serialize_for_span
@@ -31,13 +31,11 @@ async def flush_tracing() -> None:
     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.
+    This flushes the BatchSpanProcessor (OTLP exporter doesn't have a separate flush method).
     """
     client = get_aiqa_client()
     if client.provider:
         client.provider.force_flush()  # Synchronous method
-    if client.exporter:    
-        await client.exporter.flush()
 
 
 # Export provider and exporter accessors for advanced usage
@@ -117,12 +115,10 @@ class TracingOptions:
         self.filter_output = filter_output
 
 
-def _prepare_input(args: tuple, kwargs: dict) -> Any:
+def _prepare_input(args: tuple, kwargs: dict, sig: Optional[inspect.Signature] = None) -> Any:
     """Prepare input for span attributes. 
-    Aims to produce nice span attributes for the input, since {args, kwargs} is not a natural way to read function input. 
-    So can "unwrap" the args, kwargs.
-    
-    For single-arg-dicts or kwargs-only, returns a shallow copy of the input data.
+    Converts args and kwargs into a unified dict structure using function signature when available.
+    Falls back to legacy behavior for functions without inspectable signatures.
     
     Note: This function does NOT serialize values - it just structures the data.
     Serialization happens later via serialize_for_span() to avoid double-encoding
@@ -130,6 +126,22 @@ def _prepare_input(args: tuple, kwargs: dict) -> Any:
     """
     if not args and not kwargs:
         return None
+    
+    # Try to bind args to parameter names using function signature
+    if sig is not None:
+        try:
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            # Return dict of all arguments (positional args are now named)
+            result = bound.arguments.copy()
+            # Shallow copy to protect against mutating the input
+            return result
+        except (TypeError, ValueError):
+            # Binding failed (e.g., wrong number of args, *args/**kwargs issues)
+            # Fall through to legacy behavior
+            pass
+    
+    # in case binding fails
     if not kwargs:
         if len(args) == 1:
             arg0 = args[0]
@@ -150,15 +162,17 @@ def _prepare_and_filter_input(
     kwargs: dict,
     filter_input: Optional[Callable[[Any], Any]],
     ignore_input: Optional[List[str]],
+    sig: Optional[inspect.Signature] = None,
 ) -> Any:
     """
     Prepare and filter input for span attributes - applies the user's filter_input and ignore_input.
-    For single-arg-dicts or kwargs-only, returns a shallow copy of the input data.
+    Converts all args to a dict using function signature when available.
     """
     # Handle "self" in ignore_input by skipping the first argument
     filtered_args = args
     filtered_kwargs = kwargs.copy() if kwargs else {}
     filtered_ignore_input = ignore_input
+    filtered_sig = sig
     if ignore_input and "self" in ignore_input:
         # Remove "self" from ignore_input list (we'll handle it specially)
         filtered_ignore_input = [key for key in ignore_input if key != "self"]
@@ -168,8 +182,14 @@ def _prepare_and_filter_input(
         # Also remove "self" from kwargs if present
         if "self" in filtered_kwargs:
             del filtered_kwargs["self"]
-    # turn args, kwargs into one "nice" object
-    input_data = _prepare_input(filtered_args, filtered_kwargs)
+        # Adjust signature to remove "self" parameter if present
+        # This is needed because we removed self from args, so signature binding will fail otherwise
+        if filtered_sig is not None:
+            params = list(filtered_sig.parameters.values())
+            if params and params[0].name == "self":
+                filtered_sig = filtered_sig.replace(parameters=params[1:])
+    # turn args, kwargs into one "nice" object (now always a dict when signature is available)
+    input_data = _prepare_input(filtered_args, filtered_kwargs, filtered_sig)
     if filter_input and input_data is not None:
         input_data = filter_input(input_data)
     if filtered_ignore_input and len(filtered_ignore_input) > 0:
@@ -447,6 +467,15 @@ def WithTracing(
         is_generator = inspect.isgeneratorfunction(fn)
         is_async_generator = inspect.isasyncgenfunction(fn) if hasattr(inspect, 'isasyncgenfunction') else False
         
+        # Get function signature once at decoration time for efficient arg name resolution
+        fn_sig: Optional[inspect.Signature] = None
+        try:
+            fn_sig = inspect.signature(fn)
+        except (ValueError, TypeError):
+            # Some callables (e.g., builtins, C extensions) don't have inspectable signatures
+            # Will fall back to legacy behavior
+            pass
+        
         # Don't get tracer here - get it lazily when function is called
         # This ensures initialization only happens when tracing is actually used
         
@@ -595,7 +624,7 @@ def WithTracing(
         if is_async_generator:
             @wraps(fn)
             async def async_gen_traced_fn(*args, **kwargs):
-                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input)
+                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input, fn_sig)
                 return await _execute_generator_async(
                     lambda: fn(*args, **kwargs),
                     input_data
@@ -607,7 +636,7 @@ def WithTracing(
         elif is_generator:
             @wraps(fn)
             def gen_traced_fn(*args, **kwargs):
-                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input)
+                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input, fn_sig)
                 return _execute_generator_sync(
                     lambda: fn(*args, **kwargs),
                     input_data
@@ -619,7 +648,7 @@ def WithTracing(
         elif is_async:
             @wraps(fn)
             async def async_traced_fn(*args, **kwargs):
-                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input)
+                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input, fn_sig)
                 return await _execute_with_span_async(
                     lambda: fn(*args, **kwargs),
                     input_data
@@ -631,7 +660,7 @@ def WithTracing(
         else:
             @wraps(fn)
             def sync_traced_fn(*args, **kwargs):
-                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input)
+                input_data = _prepare_and_filter_input(args, kwargs, filter_input, ignore_input, fn_sig)
                 return _execute_with_span_sync(
                     lambda: fn(*args, **kwargs),
                     input_data
@@ -678,6 +707,7 @@ def get_active_span() -> Optional[trace.Span]:
 
 def set_conversation_id(conversation_id: str) -> bool:
     """
+    Naturally a conversation might span several traces. 
     Set the gen_ai.conversation.id attribute on the active span.
     This allows you to group multiple traces together that are part of the same conversation.
     See https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/ for more details.
@@ -1027,14 +1057,12 @@ def get_span(span_id: str, organisation_id: Optional[str] = None, exclude: Optio
             print(f"Found span: {span['name']}")
             my_function(**span['input'])
     """
-    import os
-    import requests
-    
     server_url = get_server_url()
     api_key = get_api_key()
     org_id = organisation_id or os.getenv("AIQA_ORGANISATION_ID", "")
     
-    if not server_url:
+    # Check if server_url is the default (meaning AIQA_SERVER_URL was not set)
+    if not os.getenv("AIQA_SERVER_URL"):
         raise ValueError("AIQA_SERVER_URL is not set. Cannot retrieve span.")    
     if not org_id:
         raise ValueError("Organisation ID is required. Provide it as parameter or set AIQA_ORGANISATION_ID environment variable.")

{aiqa_client-0.4.7.dist-info → aiqa_client-0.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.4.7
+Version: 0.5.2
 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.5.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+aiqa/__init__.py,sha256=V1VLfpxU_BXfkvKyhGckZsPYF43NJhoXeVX6FkeHr9g,1721
+aiqa/client.py,sha256=Ba3v-voBlTSCr-RU88INLXsF_5vqp42QiQWCFciSJbU,12542
+aiqa/constants.py,sha256=tZuh7XvKs6hFvWc-YnQ5Na6uogJMsRrMy-rWOauvcIA,226
+aiqa/experiment_runner.py,sha256=XAZsjVP70UH_QTk5ANSOQYAhmozuGXwKB5qWWHs-zeE,11186
+aiqa/http_utils.py,sha256=OIB4tRI2TiDl4VKDmtbLWg9Q7TicMBeL7scLYEhVPXI,4944
+aiqa/object_serialiser.py,sha256=DBv7EyXIwfwjwXHDsIwdZNFmQffRb5fKAE0r8qhoqgc,16958
+aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiqa/tracing.py,sha256=gdmtpvBVbvc_HrJHgtr78_XH9sIWRjUoEkXuCuNmuc0,45662
+aiqa/tracing_llm_utils.py,sha256=rNx6v6Wh_Mhv-_DPU9_aWS7YQcO46oiv0YPdBK1KVL8,9338
+aiqa_client-0.5.2.dist-info/licenses/LICENSE.txt,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
+aiqa_client-0.5.2.dist-info/METADATA,sha256=xMaQSnI3AiNE6lYs2vM6BV9VxQWMHXyDoIl6JXwdi3I,7705
+aiqa_client-0.5.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aiqa_client-0.5.2.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
+aiqa_client-0.5.2.dist-info/RECORD,,

aiqa/aiqa_exporter.py

@@ -1,772 +0,0 @@
-"""
-OpenTelemetry span exporter that sends spans to the AIQA server API.
-Buffers spans and flushes them periodically or on shutdown. Thread-safe.
-"""
-
-import os
-import json
-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, LOG_TAG
-from .http_utils import get_server_url, get_api_key, build_headers
-from .object_serialiser import toNumber
-
-logger = logging.getLogger(LOG_TAG)
-
-
-class AIQASpanExporter(SpanExporter):
-    """
-    Exports spans to AIQA server. Buffers spans and auto-flushes every flush_interval_seconds.
-    Call shutdown() before process exit to flush remaining spans.
-    """
-
-    def __init__(
-        self,
-        server_url: Optional[str] = None,
-        api_key: Optional[str] = None,
-        flush_interval_seconds: float = 5.0,
-        max_batch_size_bytes: int = 5 * 1024 * 1024,  # 5MB default
-        max_buffer_spans: Optional[int] = None,  # Maximum spans to buffer (prevents unbounded growth)
-        max_buffer_size_bytes: Optional[int] = None,  # Maximum buffer size in bytes (prevents unbounded memory growth)
-        startup_delay_seconds: Optional[float] = None,
-    ):
-        """
-        Initialize the AIQA span exporter.
-
-        Args:
-            server_url: URL of the AIQA server (defaults to AIQA_SERVER_URL env var)
-            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). 
-                Defaults to 10000, or AIQA_MAX_BUFFER_SPANS env var if set.
-            max_buffer_size_bytes: Maximum total buffer size in bytes (prevents unbounded memory growth).
-                Defaults to None (no limit), or AIQA_MAX_BUFFER_SIZE_BYTES env var if set.
-            startup_delay_seconds: Delay before starting auto-flush (default: 10s, or AIQA_STARTUP_DELAY_SECONDS env var)
-        """
-        self._server_url = get_server_url(server_url)
-        self._api_key = get_api_key(api_key)
-        self.flush_interval_ms = flush_interval_seconds * 1000
-        self.max_batch_size_bytes = max_batch_size_bytes
-        
-        # Get max_buffer_spans from parameter, environment variable, or default
-        if not max_buffer_spans:
-            max_buffer_spans = toNumber(os.getenv("AIQA_MAX_BUFFER_SPANS")) or 10000
-        self.max_buffer_spans = max_buffer_spans
-        
-        # Get max_buffer_size_bytes from parameter, environment variable, or default
-        if not max_buffer_size_bytes:
-            max_buffer_size_bytes = toNumber(os.getenv("AIQA_MAX_BUFFER_SIZE_BYTES")) or toNumber("100m")
-        self.max_buffer_size_bytes = max_buffer_size_bytes
-        
-        # 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_size_bytes: int = 0  # Track total size of buffered spans in bytes
-        # Cache span sizes to avoid recalculation (maps span_key -> size_bytes)
-        # Limited to max_buffer_spans * 2 to prevent unbounded growth
-        self._span_size_cache: Dict[tuple, int] = {}
-        self._max_cache_size = self.max_buffer_spans * 2  # Allow cache to be 2x buffer size
-        self.buffer_lock = threading.Lock()
-        self.flush_lock = threading.Lock()
-        # shutdown_requested is only set once (in shutdown()) and read many times
-        # No lock needed: worst case is reading stale False, which is acceptable
-        self.shutdown_requested = False
-        self.flush_timer: Optional[threading.Thread] = None
-        self._auto_flush_started = False
-        self._auto_flush_lock = threading.Lock()  # Lock for lazy thread creation
-        
-        logger.info(f"Initializing AIQASpanExporter: server_url={self._server_url or 'not set'}, "
-            f"flush_interval={flush_interval_seconds}s, startup_delay={startup_delay_seconds}s"
-        )
-        # Don't start thread immediately - start lazily on first export to avoid startup issues
-
-    def export(self, spans: List[ReadableSpan]) -> SpanExportResult:
-        """
-        Export spans to the AIQA server. Adds spans to buffer for async flushing.
-        Deduplicates spans based on (traceId, spanId) to prevent repeated exports.
-        Actual send is done by flush -> _send_spans, or shutdown -> _send_spans_sync
-        """
-        if not spans:
-            logger.debug(f"export: called with empty spans list")
-            return SpanExportResult.SUCCESS
-        
-        # Check if AIQA tracing is enabled
-        try:
-            from .client import get_aiqa_client
-            client = get_aiqa_client()
-            if not client.enabled:
-                logger.debug(f"AIQA export: skipped: tracing is disabled")
-                return SpanExportResult.SUCCESS
-        except Exception:
-            # If we can't check enabled status, proceed (fail open)
-            pass
-        
-        logger.debug(f"AIQA export() to buffer called with {len(spans)} spans")
-        
-        # Lazy initialization: start auto-flush thread on first export
-        # This avoids thread creation during initialization, which can cause issues in ECS deployments
-        self._ensure_auto_flush_started()
-        
-        # Serialize and add to buffer, deduplicating by (traceId, spanId)
-        with self.buffer_lock:
-            serialized_spans = []
-            serialized_sizes = []  # Track sizes of serialized spans
-            duplicates_count = 0
-            dropped_count = 0
-            dropped_memory_count = 0
-            flush_in_progress = self.flush_lock.locked()
-            
-            for span in spans:
-                # Check if buffer is full by span count (prevent unbounded growth)
-                if len(self.buffer) >= self.max_buffer_spans:
-                    if flush_in_progress:
-                        # Flush in progress, drop this span
-                        dropped_count += 1
-                        continue
-                    # Flush not in progress, will trigger flush after adding spans
-                    # Continue processing remaining spans to add them before flush
-                
-                serialized = self._serialize_span(span)
-                span_key = (serialized["traceId"], serialized["spanId"])
-                if span_key not in self.buffer_span_keys:
-                    # Estimate size of this span when serialized (cache for later use)
-                    span_size = self._get_span_size(span_key, serialized)
-                    
-                    # Check if buffer is full by memory size (prevent unbounded memory growth)
-                    if self.max_buffer_size_bytes is not None and self.buffer_size_bytes + span_size > self.max_buffer_size_bytes:
-                        if flush_in_progress:
-                            # Flush in progress, drop this span
-                            # Don't cache size for dropped spans to prevent memory leak
-                            dropped_memory_count += 1
-                            continue
-                        # Flush not in progress, will trigger flush after adding spans
-                        # Continue processing remaining spans to add them before flush
-                    
-                    serialized_spans.append(serialized)
-                    serialized_sizes.append(span_size)
-                    self.buffer_span_keys.add(span_key)
-                else:
-                    duplicates_count += 1
-                    logger.debug(f"export: skipping duplicate span: traceId={serialized['traceId']}, spanId={serialized['spanId']}")
-            
-            # Add spans and update buffer size
-            self.buffer.extend(serialized_spans)
-            self.buffer_size_bytes += sum(serialized_sizes)
-            buffer_size = len(self.buffer)
-            
-            # Check if thresholds are reached after adding spans
-            threshold_reached = self._check_thresholds_reached()
-            
-            if dropped_count > 0:
-                logger.warning(f"WARNING: Buffer full ({buffer_size} spans), dropped {dropped_count} span(s) (flush in progress). "
-                    f"Consider increasing max_buffer_spans or fixing server connectivity."
-                )
-            if dropped_memory_count > 0:
-                logger.warning(f"WARNING: Buffer memory limit reached ({self.buffer_size_bytes} bytes / {self.max_buffer_size_bytes} bytes), "
-                    f"dropped {dropped_memory_count} span(s) (flush in progress). "
-                    f"Consider increasing AIQA_MAX_BUFFER_SIZE_BYTES or fixing server connectivity."
-                )
-        
-        # Trigger immediate flush if threshold reached and flush not in progress
-        if threshold_reached and not flush_in_progress:
-            logger.info(f"Buffer threshold reached ({buffer_size} spans, {self.buffer_size_bytes} bytes), triggering immediate flush")
-            self._trigger_immediate_flush()
-        
-        if duplicates_count > 0:
-            logger.debug(f"export() added {len(serialized_spans)} span(s) to buffer, skipped {duplicates_count} duplicate(s). "
-                f"Total buffered: {buffer_size}"
-            )
-        else:
-            logger.debug(f"export() added {len(spans)} span(s) to buffer. "
-                f"Total buffered: {buffer_size}"
-            )
-
-        return SpanExportResult.SUCCESS
-
-    def _serialize_span(self, span: ReadableSpan) -> Dict[str, Any]:
-        """Convert ReadableSpan to a serializable format."""
-        span_context = span.get_span_context()
-        
-        # Get parent span ID
-        parent_span_id = None
-        if hasattr(span, "parent") and span.parent:
-            parent_span_id = format(span.parent.span_id, "016x")
-        elif hasattr(span, "parent_span_id") and span.parent_span_id:
-            parent_span_id = format(span.parent_span_id, "016x")
-        
-        # Get span kind (handle both enum and int)
-        span_kind = span.kind
-        if hasattr(span_kind, "value"):
-            span_kind = span_kind.value
-        
-        # Get status code (handle both enum and int)
-        status_code = span.status.status_code
-        if hasattr(status_code, "value"):
-            status_code = status_code.value
-        
-        return {
-            "name": span.name,
-            "kind": span_kind,
-            "parentSpanId": parent_span_id,
-            "startTime": self._time_to_tuple(span.start_time),
-            "endTime": self._time_to_tuple(span.end_time) if span.end_time else None,
-            "status": {
-                "code": status_code,
-                "message": getattr(span.status, "description", None),
-            },
-            "attributes": dict(span.attributes) if span.attributes else {},
-            "links": [
-                {
-                    "context": {
-                        "traceId": format(link.context.trace_id, "032x"),
-                        "spanId": format(link.context.span_id, "016x"),
-                    },
-                    "attributes": dict(link.attributes) if link.attributes else {},
-                }
-                for link in (span.links or [])
-            ],
-            "events": [
-                {
-                    "name": event.name,
-                    "time": self._time_to_tuple(event.timestamp),
-                    "attributes": dict(event.attributes) if event.attributes else {},
-                }
-                for event in (span.events or [])
-            ],
-            "resource": {
-                "attributes": dict(span.resource.attributes) if span.resource.attributes else {},
-            },
-            "traceId": format(span_context.trace_id, "032x"),
-            "spanId": format(span_context.span_id, "016x"),
-            "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": 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:
-        """Convert nanoseconds to (seconds, nanoseconds) tuple."""
-        seconds = int(nanoseconds // 1_000_000_000)
-        nanos = int(nanoseconds % 1_000_000_000)
-        return (seconds, nanos)
-
-    def _get_span_size(self, span_key: tuple, serialized: Dict[str, Any]) -> int:
-        """
-        Get span size from cache or calculate and cache it.
-        Thread-safe when called within buffer_lock.
-        Limits cache size to prevent unbounded memory growth.
-        """
-        if span_key in self._span_size_cache:
-            return self._span_size_cache[span_key]
-        span_json = json.dumps(serialized)
-        span_size = len(span_json.encode('utf-8'))
-        # Only cache if we have valid keys and cache isn't too large
-        if span_key[0] and span_key[1] and len(self._span_size_cache) < self._max_cache_size:
-            self._span_size_cache[span_key] = span_size
-        return span_size
-
-    def _check_thresholds_reached(self) -> bool:
-        """Check if buffer thresholds are reached. Must be called within buffer_lock."""
-        if len(self.buffer) >= self.max_buffer_spans:
-            return True
-        if self.max_buffer_size_bytes is not None and self.buffer_size_bytes >= self.max_buffer_size_bytes:
-            return True
-        return False
-
-    def _build_request_headers(self) -> Dict[str, str]:
-        """Build HTTP headers for span requests."""
-        return build_headers(self._api_key)
-
-    def _get_span_url(self) -> str:
-        return f"{self._server_url}/span"
-
-    def _is_interpreter_shutdown_error(self, error: Exception) -> bool:
-        """Check if error is due to interpreter shutdown."""
-        error_str = str(error)
-        return "cannot schedule new futures after" in error_str or "interpreter shutdown" in error_str
-
-    def _extract_spans_from_buffer(self) -> List[Dict[str, Any]]:
-        """Extract spans from buffer (thread-safe). Returns copy of buffer."""
-        with self.buffer_lock:
-            return self.buffer[:]
-
-    def _extract_and_remove_spans_from_buffer(self) -> List[Dict[str, Any]]:
-        """
-        Atomically extract and remove all spans from buffer (thread-safe).
-        Returns the extracted spans. This prevents race conditions where spans
-        are added between extraction and clearing.
-        Note: Does NOT clear buffer_span_keys - that should be done after successful send
-        to avoid unnecessary clearing/rebuilding on failures.
-        Also resets buffer_size_bytes to 0.
-        """
-        with self.buffer_lock:
-            spans = self.buffer[:]
-            self.buffer.clear()
-            self.buffer_size_bytes = 0
-            return spans
-    
-    def _remove_span_keys_from_tracking(self, spans: List[Dict[str, Any]]) -> None:
-        """
-        Remove span keys from tracking set and size cache (thread-safe). Called after successful send.
-        """
-        with self.buffer_lock:
-            for span in spans:
-                span_key = (span["traceId"], span["spanId"])
-                self.buffer_span_keys.discard(span_key)
-                # Also remove from size cache to free memory
-                self._span_size_cache.pop(span_key, None)
-
-    def _prepend_spans_to_buffer(self, spans: List[Dict[str, Any]]) -> None:
-        """
-        Prepend spans back to buffer (thread-safe). Used to restore spans
-        if sending fails. Rebuilds the span keys tracking set and buffer size.
-        Uses cached sizes when available to avoid re-serialization.
-        """
-        with self.buffer_lock:
-            self.buffer[:0] = spans
-            # Rebuild span keys set from current buffer contents
-            self.buffer_span_keys = {(span["traceId"], span["spanId"]) for span in self.buffer}
-            # Recalculate buffer size using cache when available
-            total_size = 0
-            for span in self.buffer:
-                span_key = (span.get("traceId"), span.get("spanId"))
-                total_size += self._get_span_size(span_key, span)
-            self.buffer_size_bytes = total_size
-
-    def _clear_buffer(self) -> None:
-        """Clear the buffer (thread-safe)."""
-        with self.buffer_lock:
-            self.buffer.clear()
-            self.buffer_span_keys.clear()
-            self.buffer_size_bytes = 0
-            self._span_size_cache.clear()
-
-    def _split_into_batches(self, spans: List[Dict[str, Any]]) -> List[List[Dict[str, Any]]]:
-        """
-        Split spans into batches based on max_batch_size_bytes.
-        Each batch will be as large as possible without exceeding the limit.
-        If a single span exceeds the limit, it will be sent in its own batch with a warning.
-        """
-        if not spans:
-            return []
-        
-        batches = []
-        current_batch = []
-        current_batch_size = 0
-        
-        for span in spans:
-            # Get size from cache if available, otherwise calculate it
-            span_key = (span.get("traceId"), span.get("spanId"))
-            span_size = self._get_span_size(span_key, span)
-            
-            # Check if this single span exceeds the limit
-            if span_size > self.max_batch_size_bytes:
-                # If we have a current batch, save it first
-                if current_batch:
-                    batches.append(current_batch)
-                    current_batch = []
-                    current_batch_size = 0
-                
-                # Log warning about oversized span
-                span_name = span.get('name', 'unknown')
-                span_trace_id = span.get('traceId', 'unknown')
-                logger.warning(f"Span \'{span_name}' (traceId={span_trace_id}) exceeds max_batch_size_bytes "
-                    f"({span_size} bytes > {self.max_batch_size_bytes} bytes). "
-                    f"Will attempt to send it anyway - may fail if server/nginx limit is exceeded."
-                )
-                # Still create a batch with just this span - we'll try to send it
-                batches.append([span])
-                continue
-            
-            # If adding this span would exceed the limit, start a new batch
-            if current_batch and current_batch_size + span_size > self.max_batch_size_bytes:
-                batches.append(current_batch)
-                current_batch = []
-                current_batch_size = 0
-            
-            current_batch.append(span)
-            current_batch_size += span_size
-        
-        # Add the last batch if it has any spans
-        if current_batch:
-            batches.append(current_batch)
-        
-        return batches
-
-    async def flush(self) -> None:
-        """
-        Flush buffered spans to the server. Thread-safe: ensures only one flush operation runs at a time.
-        Atomically extracts spans to prevent race conditions with concurrent export() calls.
-        
-        Lock ordering: flush_lock -> buffer_lock (must be consistent to avoid deadlocks)
-        """
-        logger.debug(f"flush: called - attempting to acquire flush lock")
-        with self.flush_lock:
-            logger.debug(f"flush() acquired flush lock")
-            # Atomically extract and remove spans to prevent race conditions
-            # where export() adds spans between extraction and clearing
-            spans_to_flush = self._extract_and_remove_spans_from_buffer()
-            logger.debug(f"flush: extracted {len(spans_to_flush)} span(s) from buffer")
-
-            if not spans_to_flush:
-                logger.debug(f"flush() completed: no spans to flush")
-                return
-
-            # Skip sending if server URL is not configured
-            if not self._server_url:
-                logger.warning(f"Skipping flush: AIQA_SERVER_URL is not set. {len(spans_to_flush)} span(s) will not be sent."
-                )
-                # Spans already removed from buffer, clear their keys to free memory
-                self._remove_span_keys_from_tracking(spans_to_flush)
-                return
-
-        # Release flush_lock before I/O to avoid blocking other flush attempts
-        # Spans are already extracted, so concurrent exports won't interfere
-        logger.info(f"flush: sending {len(spans_to_flush)} span(s) to server")
-        try:
-            await self._send_spans(spans_to_flush)
-            logger.info(f"flush() successfully sent {len(spans_to_flush)} span(s) to server")
-            # Spans already removed from buffer during extraction
-            # Now clear their keys from tracking set to free memory
-            self._remove_span_keys_from_tracking(spans_to_flush)
-        except RuntimeError as error:
-            if self._is_interpreter_shutdown_error(error):
-                if self.shutdown_requested:
-                    logger.debug(f"flush: skipped due to interpreter shutdown: {error}")
-                else:
-                    logger.warning(f"flush() interrupted by interpreter shutdown: {error}")
-                # Put spans back for retry with sync send during shutdown
-                self._prepend_spans_to_buffer(spans_to_flush)
-                raise
-            logger.error(f"Error flushing spans to server: {error}")
-            # Put spans back for retry
-            self._prepend_spans_to_buffer(spans_to_flush)
-            raise
-        except Exception as error:
-            logger.error(f"Error flushing spans to server: {error}")
-            # Put spans back for retry
-            self._prepend_spans_to_buffer(spans_to_flush)
-            if self.shutdown_requested:
-                raise
-
-    def _ensure_auto_flush_started(self) -> None:
-        """Ensure auto-flush thread is started (lazy initialization). Thread-safe."""
-        # Fast path: check without lock first
-        if self._auto_flush_started or self.shutdown_requested:
-            return
-        
-        # Slow path: acquire lock and double-check
-        with self._auto_flush_lock:
-            if self._auto_flush_started or self.shutdown_requested:
-                return
-            
-            try:
-                self._start_auto_flush()
-                self._auto_flush_started = True
-            except Exception as e:
-                logger.error(f"Failed to start auto-flush thread: {e}", exc_info=True)
-                # Don't raise - allow spans to be buffered even if auto-flush fails
-                # They can still be flushed manually or on shutdown
-
-    def _trigger_immediate_flush(self) -> None:
-        """
-        Trigger an immediate flush in a background thread.
-        This is called when buffer thresholds are reached and no flush is in progress.
-        """
-        def flush_in_thread():
-            """Run flush in a new thread with its own event loop."""
-            try:
-                loop = asyncio.new_event_loop()
-                asyncio.set_event_loop(loop)
-                try:
-                    loop.run_until_complete(self.flush())
-                finally:
-                    if not loop.is_closed():
-                        loop.close()
-            except Exception as e:
-                logger.error(f"Error in immediate flush thread: {e}", exc_info=True)
-        
-        # Start flush in background thread (daemon so it doesn't block shutdown)
-        flush_thread = threading.Thread(target=flush_in_thread, daemon=True, name="AIQA-ImmediateFlush")
-        flush_thread.start()
-
-    def _flush_worker(self) -> None:
-        """Worker function for auto-flush thread. Runs in a separate thread with its own event loop."""
-        import asyncio
-        logger.debug(f"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(f"Auto-flush startup delay interrupted by shutdown")
-                return
-            
-            logger.info(f"Auto-flush startup delay complete, beginning flush operations")
-        
-        # Create event loop in this thread (isolated from main thread's event loop)
-        # This prevents interference with the main application's event loop
-        try:
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-        except Exception as e:
-            logger.error(f"Failed to create event loop for auto-flush thread: {e}", exc_info=True)
-            return
-        
-        # Ensure event loop is always closed, even if an exception occurs
-        try:
-            cycle_count = 0
-            while not self.shutdown_requested:
-                cycle_count += 1
-                logger.debug(f"Auto-flush cycle #{cycle_count} starting")
-                try:
-                    loop.run_until_complete(self.flush())
-                    logger.debug(f"Auto-flush cycle #{cycle_count} completed, sleeping {self.flush_interval_ms / 1000.0}s")
-                except Exception as e:
-                    logger.error(f"Error in auto-flush cycle #{cycle_count}: {e}")
-                    logger.debug(f"Auto-flush cycle #{cycle_count} error handled, sleeping {self.flush_interval_ms / 1000.0}s")
-                
-                # Sleep after each cycle (including errors) to avoid tight loops
-                if not self.shutdown_requested:
-                    time.sleep(self.flush_interval_ms / 1000.0)
-            
-            logger.info(f"Auto-flush worker thread stopping (shutdown requested). Completed {cycle_count} cycles.")
-            # Don't do final flush here - shutdown() will handle it with synchronous send
-            # This avoids event loop shutdown issues
-            logger.debug(f"Auto-flush thread skipping final flush (will be handled by shutdown() with sync send)")
-        finally:
-            # Always close the event loop, even if an exception occurs
-            try:
-                if not loop.is_closed():
-                    loop.close()
-                logger.debug(f"Auto-flush worker thread event loop closed")
-            except Exception:
-                pass  # Ignore errors during cleanup
-    
-    def _start_auto_flush(self) -> None:
-        """Start the auto-flush timer with startup delay."""
-        if self.shutdown_requested:
-            logger.warning(f"_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, "
-            f"startup delay {self.startup_delay_seconds}s"
-        )
-
-        flush_thread = threading.Thread(target=self._flush_worker, daemon=True, name="AIQA-AutoFlush")
-        flush_thread.start()
-        self.flush_timer = flush_thread
-        logger.info(f"Auto-flush thread started: {flush_thread.name} (daemon={flush_thread.daemon})")
-
-    async def _send_spans(self, spans: List[Dict[str, Any]]) -> None:
-        """Send spans to the server API (async). Batches large payloads automatically."""
-        import aiohttp
-
-        # Split into batches if needed
-        batches = self._split_into_batches(spans)
-        if len(batches) > 1:
-            logger.info(f"_send_spans: splitting {len(spans)} spans into {len(batches)} batches")
-        
-        url = self._get_span_url()
-        headers = self._build_request_headers()
-        
-        if not self._api_key: # This should not happen
-            logger.error(f"_send_spans: fail - no API key provided. {len(spans)} spans lost.")
-            # Spans were already removed from buffer before calling this method. They will now get forgotten
-            return
-
-        # Use timeout to prevent hanging on unreachable servers
-        timeout = aiohttp.ClientTimeout(total=30.0, connect=10.0)
-        errors = []
-        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}")
-                    # Pre-serialize JSON to bytes and wrap in BytesIO to avoid blocking event loop
-                    json_bytes = json.dumps(batch).encode('utf-8')
-                    data = io.BytesIO(json_bytes)
-                    
-                    async with session.post(url, data=data, headers=headers) as response:
-                        logger.debug(f"_send_spans: batch {batch_idx + 1} received response: status={response.status}")
-                        if not response.ok:
-                            error_text = await response.text()
-                            error_msg = f"Failed to send batch {batch_idx + 1}/{len(batches)}: {response.status} {response.reason} - {error_text[:200]}"
-                            logger.error(f"_send_spans: {error_msg}")
-                            errors.append((batch_idx + 1, error_msg))
-                            # 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:
-                            logger.debug(f"_send_spans: skipped due to interpreter shutdown: {e}")
-                        else:
-                            logger.warning(f"_send_spans: interrupted by interpreter shutdown: {e}")
-                        raise
-                    error_msg = f"RuntimeError in batch {batch_idx + 1}: {type(e).__name__}: {e}"
-                    logger.error(f"_send_spans: {error_msg}")
-                    errors.append((batch_idx + 1, error_msg))
-                    # Continue with other batches
-                except Exception as e:
-                    error_msg = f"Exception in batch {batch_idx + 1}: {type(e).__name__}: {e}"
-                    logger.error(f"_send_spans: {error_msg}")
-                    errors.append((batch_idx + 1, error_msg))
-                    # 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}")
-        
-        logger.debug(f"_send_spans: successfully sent all {len(spans)} spans in {len(batches)} batch(es)")
-
-    def _send_spans_sync(self, spans: List[Dict[str, Any]]) -> None:
-        """Send spans to the server API (synchronous, for shutdown scenarios). Batches large payloads automatically."""
-        import requests
-
-        # Split into batches if needed
-        batches = self._split_into_batches(spans)
-        if len(batches) > 1:
-            logger.info(f"_send_spans_sync() splitting {len(spans)} spans into {len(batches)} batches")
-        
-        url = self._get_span_url()
-        headers = self._build_request_headers()
-        
-        if not self._api_key:
-            logger.error(f"_send_spans_sync() fail - no API key provided")
-            return
-
-        errors = []
-        for batch_idx, batch in enumerate(batches):
-            try:
-                logger.debug(f"_send_spans_sync() sending batch {batch_idx + 1}/{len(batches)} with {len(batch)} spans to {url}")
-                response = requests.post(url, json=batch, headers=headers, timeout=10.0)
-                logger.debug(f"_send_spans_sync() batch {batch_idx + 1} received response: status={response.status_code}")
-                if not response.ok:
-                    error_text = response.text[:200] if response.text else ""
-                    error_msg = f"Failed to send batch {batch_idx + 1}/{len(batches)}: {response.status_code} {response.reason} - {error_text}"
-                    logger.error(f"_send_spans_sync() {error_msg}")
-                    errors.append((batch_idx + 1, error_msg))
-                    # Continue with other batches even if one fails
-                    continue
-                logger.debug(f"_send_spans_sync() batch {batch_idx + 1} successfully sent {len(batch)} spans")
-            except Exception as e:
-                error_msg = f"Exception in batch {batch_idx + 1}: {type(e).__name__}: {e}"
-                logger.error(f"_send_spans_sync() {error_msg}")
-                errors.append((batch_idx + 1, error_msg))
-                # Continue with other batches
-        
-        # If any batches failed, raise an exception with details
-        if errors:
-            error_summary = "; ".join([f"batch {idx}: {msg}" for idx, msg in errors])
-            raise Exception(f"Failed to send some spans: {error_summary}")
-        
-        logger.debug(f"_send_spans_sync() successfully sent all {len(spans)} spans in {len(batches)} batch(es)")
-
-    def shutdown(self) -> None:
-        """Shutdown the exporter, flushing any remaining spans. Call before process exit."""
-        logger.info(f"shutdown: called - initiating exporter shutdown")
-        self.shutdown_requested = True
-
-        # Check buffer state before shutdown
-        with self.buffer_lock:
-            buffer_size = len(self.buffer)
-            logger.info(f"shutdown: buffer contains {buffer_size} span(s) before shutdown")
-
-        # Wait for flush thread to finish (it will do final flush)
-        # Only wait if thread was actually started
-        if self._auto_flush_started and self.flush_timer and self.flush_timer.is_alive():
-            logger.info(f"shutdown: waiting for auto-flush thread to complete (timeout=10s)")
-            self.flush_timer.join(timeout=10.0)
-            if self.flush_timer.is_alive():
-                logger.warning(f"shutdown: auto-flush thread did not complete within timeout")
-            else:
-                logger.info(f"shutdown: auto-flush thread completed")
-        else:
-            logger.debug(f"shutdown: no active auto-flush thread to wait for")
-
-        # Final flush attempt (use synchronous send to avoid event loop issues)
-        with self.flush_lock:
-            logger.debug(f"shutdown: performing final flush with synchronous send")
-            # Atomically extract and remove spans to prevent race conditions
-            spans_to_flush = self._extract_and_remove_spans_from_buffer()
-            logger.debug(f"shutdown: extracted {len(spans_to_flush)} span(s) from buffer for final flush")
-
-            if spans_to_flush:
-                if not self._server_url:
-                    logger.warning(f"shutdown: skipping final flush: AIQA_SERVER_URL is not set. "
-                        f"{len(spans_to_flush)} span(s) will not be sent."
-                    )
-                    # Spans already removed from buffer, clear their keys to free memory
-                    self._remove_span_keys_from_tracking(spans_to_flush)
-                else:
-                    logger.info(f"shutdown: sending {len(spans_to_flush)} span(s) to server (synchronous)")
-                    try:
-                        self._send_spans_sync(spans_to_flush)
-                        logger.info(f"shutdown: successfully sent {len(spans_to_flush)} span(s) to server")
-                        # Spans already removed from buffer during extraction
-                        # Clear their keys from tracking set to free memory
-                        self._remove_span_keys_from_tracking(spans_to_flush)
-                    except Exception as e:
-                        logger.error(f"shutdown: failed to send spans: {e}")
-                        # Spans already removed, but process is exiting anyway
-                        logger.warning(f"shutdown: {len(spans_to_flush)} span(s) were not sent due to error")
-                        # Keys will remain in tracking set, but process is exiting so memory will be freed
-            else:
-                logger.debug(f"shutdown: no spans to flush")
-        
-        # Check buffer state after shutdown
-        with self.buffer_lock:
-            buffer_size = len(self.buffer)
-            if buffer_size > 0:
-                logger.warning(f"shutdown: buffer still contains {buffer_size} span(s) after shutdown")
-            else:
-                logger.info(f"shutdown: buffer is empty after shutdown")
-        
-        logger.info(f"shutdown: completed")
-

aiqa_client-0.4.7.dist-info/RECORD

@@ -1,15 +0,0 @@
-aiqa/__init__.py,sha256=8MQBrnisjeYNrwrbTheUafEWS09GtIF7ff0fBZ1Jb24,1710
-aiqa/aiqa_exporter.py,sha256=PAEwnrqTiII_OY1q6bskPob7rKGoYOYaE7ismU1pIv4,38630
-aiqa/client.py,sha256=lcENe5LlyfH8v312ElcX_HtVuOoyIMzzJnmeKrbjXYw,10063
-aiqa/constants.py,sha256=rUI3WuY1fKB_Isaok4C9vYer2XZYEgAVxAIe13pJi14,226
-aiqa/experiment_runner.py,sha256=XAZsjVP70UH_QTk5ANSOQYAhmozuGXwKB5qWWHs-zeE,11186
-aiqa/http_utils.py,sha256=m4fu3NI9CSAfdz4yz3S-nYLoAOmUhDGas4ZcpuMLog8,2241
-aiqa/object_serialiser.py,sha256=DBv7EyXIwfwjwXHDsIwdZNFmQffRb5fKAE0r8qhoqgc,16958
-aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aiqa/tracing.py,sha256=1DLiQ-HHRgVV-mLIdkzeBeWD0bLsNCV4kh1yRlurvps,44080
-aiqa/tracing_llm_utils.py,sha256=rNx6v6Wh_Mhv-_DPU9_aWS7YQcO46oiv0YPdBK1KVL8,9338
-aiqa_client-0.4.7.dist-info/licenses/LICENSE.txt,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
-aiqa_client-0.4.7.dist-info/METADATA,sha256=a8uGQEoyu0rmY4N2UcS7FyTC6sIyGSb8Qn_-cxJq8Yc,7705
-aiqa_client-0.4.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aiqa_client-0.4.7.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
-aiqa_client-0.4.7.dist-info/RECORD,,