aiqa-client 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

aiqa/__init__.py

@@ -1,29 +1,66 @@
 """
 Python client for AIQA server - OpenTelemetry tracing decorators.
+
+IMPORTANT: Before using any AIQA functionality, you must call get_aiqa_client() to initialize
+the client and load environment variables (AIQA_SERVER_URL, AIQA_API_KEY, AIQA_COMPONENT_TAG, etc.).
+
+Example:
+    from dotenv import load_dotenv
+    from aiqa import get_aiqa_client, WithTracing
+    
+    # Load environment variables from .env file (if using one)
+    load_dotenv()
+    
+    # Initialize client (must be called before using WithTracing or other functions)
+    get_aiqa_client()
+    
+    @WithTracing
+    def my_function():
+        return "Hello, AIQA!"
 """
 
 from .tracing import (
     WithTracing,
-    flush_spans,
+    flush_tracing,
     shutdown_tracing,
     set_span_attribute,
     set_span_name,
     get_active_span,
-    provider,
-    exporter,
+    get_provider,
+    get_exporter,
+    get_trace_id,
+    get_span_id,
+    create_span_from_trace_id,
+    inject_trace_context,
+    extract_trace_context,
+    set_conversation_id,
+    set_component_tag,
+    get_span,
 )
+from .client import get_aiqa_client
+from .experiment_runner import ExperimentRunner
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "WithTracing",
-    "flush_spans",
+    "flush_tracing",
     "shutdown_tracing",
     "set_span_attribute",
     "set_span_name",
     "get_active_span",
-    "provider",
-    "exporter",
+    "get_provider",
+    "get_exporter",
+    "get_aiqa_client",
+    "ExperimentRunner",
+    "get_trace_id",
+    "get_span_id",
+    "create_span_from_trace_id",
+    "inject_trace_context",
+    "extract_trace_context",
+    "set_conversation_id",
+    "set_component_tag",
+    "get_span",
     "__version__",
 ]
 

aiqa/aiqa_exporter.py

@@ -8,11 +8,12 @@ import json
 import logging
 import threading
 import time
+import io
 from typing import List, Dict, Any, Optional
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("AIQA")
 
 
 class AIQASpanExporter(SpanExporter):
@@ -39,6 +40,7 @@ class AIQASpanExporter(SpanExporter):
         self._api_key = api_key
         self.flush_interval_ms = flush_interval_seconds * 1000
         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()
         self.flush_lock = threading.Lock()
         self.shutdown_requested = False
@@ -61,21 +63,39 @@ class AIQASpanExporter(SpanExporter):
     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.
         """
         if not spans:
             logger.debug("export() called with empty spans list")
             return SpanExportResult.SUCCESS
-
-        # Serialize and add to buffer
+        logger.debug(f"AIQA export() called with {len(spans)} spans")
+        # Serialize and add to buffer, deduplicating by (traceId, spanId)
         with self.buffer_lock:
-            serialized_spans = [self._serialize_span(span) for span in spans]
+            serialized_spans = []
+            duplicates_count = 0
+            for span in spans:
+                serialized = self._serialize_span(span)
+                span_key = (serialized["traceId"], serialized["spanId"])
+                if span_key not in self.buffer_span_keys:
+                    serialized_spans.append(serialized)
+                    self.buffer_span_keys.add(span_key)
+                else:
+                    duplicates_count += 1
+                    logger.debug(f"export() skipping duplicate span: traceId={serialized['traceId']}, spanId={serialized['spanId']}")
+            
             self.buffer.extend(serialized_spans)
             buffer_size = len(self.buffer)
         
-        logger.debug(
-            f"export() added {len(spans)} span(s) to buffer. "
-            f"Total buffered: {buffer_size}"
-        )
+        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
 
@@ -138,8 +158,8 @@ class AIQASpanExporter(SpanExporter):
             "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": span.instrumentation_info.name if hasattr(span, "instrumentation_info") else "",
-                "version": span.instrumentation_info.version if hasattr(span, "instrumentation_info") else None,
+                "name": self._get_instrumentation_name(),
+                "version": self._get_instrumentation_version(),
             },
         }
 
@@ -148,19 +168,93 @@ 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."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"ApiKey {self.api_key}"
+        return headers
+
+    def _get_span_url(self) -> str:
+        """Get the URL for sending spans."""
+        if not self.server_url:
+            raise ValueError("AIQA_SERVER_URL is not set. Cannot send spans to server.")
+        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.
+        """
+        with self.buffer_lock:
+            spans = self.buffer[:]
+            self.buffer.clear()
+            return spans
+    
+    def _remove_span_keys_from_tracking(self, spans: List[Dict[str, Any]]) -> None:
+        """
+        Remove span keys from tracking set (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)
+
+    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.
+        """
+        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}
+
+    def _clear_buffer(self) -> None:
+        """Clear the buffer (thread-safe)."""
+        with self.buffer_lock:
+            self.buffer.clear()
+            self.buffer_span_keys.clear()
 
     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.
         """
         logger.debug("flush() called - attempting to acquire flush lock")
         with self.flush_lock:
             logger.debug("flush() acquired flush lock")
-            # Get current buffer and clear it atomically
-            with self.buffer_lock:
-                spans_to_flush = self.buffer[:]
-                self.buffer.clear()
-                logger.debug(f"flush() extracted {len(spans_to_flush)} span(s) from buffer")
+            # 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("flush() completed: no spans to flush")
@@ -171,14 +265,36 @@ class AIQASpanExporter(SpanExporter):
                 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
 
             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}")
+                        # Put spans back for retry with sync send during shutdown
+                        self._prepend_spans_to_buffer(spans_to_flush)
+                    else:
+                        logger.warning(f"flush() interrupted by interpreter shutdown: {error}")
+                        # Put spans back for retry
+                        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}", exc_info=True)
+                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
 
@@ -205,23 +321,23 @@ class AIQASpanExporter(SpanExporter):
                     logger.debug(f"Auto-flush cycle #{cycle_count} completed, sleeping {self.flush_interval_ms / 1000.0}s")
                     time.sleep(self.flush_interval_ms / 1000.0)
                 except Exception as e:
-                    logger.error(f"Error in auto-flush cycle #{cycle_count}: {e}", exc_info=True)
+                    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")
                     time.sleep(self.flush_interval_ms / 1000.0)
             
             logger.info(f"Auto-flush worker thread stopping (shutdown requested). Completed {cycle_count} cycles.")
             
-            # Final flush on shutdown
-            if self.shutdown_requested:
-                logger.info("Performing final flush on shutdown")
-                try:
-                    loop.run_until_complete(self.flush())
-                    logger.info("Final flush completed successfully")
-                except Exception as e:
-                    logger.error(f"Error in final flush: {e}", exc_info=True)
-                finally:
+            # Don't do final flush here - shutdown() will handle it with synchronous send
+            # This avoids event loop shutdown issues
+            logger.debug("Auto-flush thread skipping final flush (will be handled by shutdown() with sync send)")
+            
+            # Close the event loop
+            try:
+                if not loop.is_closed():
                     loop.close()
-                    logger.debug("Auto-flush worker thread event loop closed")
+                logger.debug("Auto-flush worker thread event loop closed")
+            except Exception:
+                pass  # Ignore errors during cleanup
 
         flush_thread = threading.Thread(target=flush_worker, daemon=True, name="AIQA-AutoFlush")
         flush_thread.start()
@@ -229,32 +345,25 @@ class AIQASpanExporter(SpanExporter):
         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."""
-        if not self.server_url:
-            raise ValueError("AIQA_SERVER_URL is not set. Cannot send spans to server.")
-
+        """Send spans to the server API (async)."""
         import aiohttp
 
-        url = f"{self.server_url}/span"
+        url = self._get_span_url()
+        headers = self._build_request_headers()
         logger.debug(f"_send_spans() sending {len(spans)} spans to {url}")
-
-        headers = {
-            "Content-Type": "application/json",
-        }
         if self.api_key:
-            headers["Authorization"] = f"ApiKey {self.api_key[:10]}..."  # Log partial key for security
             logger.debug("_send_spans() using API key authentication")
         else:
             logger.debug("_send_spans() no API key provided")
 
         try:
+            # Pre-serialize JSON to bytes and wrap in BytesIO to avoid blocking event loop
+            json_bytes = json.dumps(spans).encode('utf-8')
+            data = io.BytesIO(json_bytes)
+            
             async with aiohttp.ClientSession() as session:
                 logger.debug(f"_send_spans() POST request starting to {url}")
-                async with session.post(
-                    url,
-                    json=spans,
-                    headers=headers,
-                ) as response:
+                async with session.post(url, data=data, headers=headers) as response:
                     logger.debug(f"_send_spans() received response: status={response.status}")
                     if not response.ok:
                         error_text = await response.text()
@@ -266,8 +375,46 @@ class AIQASpanExporter(SpanExporter):
                             f"Failed to send spans: {response.status} {response.reason} - {error_text}"
                         )
                     logger.debug(f"_send_spans() successfully sent {len(spans)} spans")
+        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
+            logger.error(f"_send_spans() RuntimeError: {type(e).__name__}: {e}")
+            raise
         except Exception as e:
-            logger.error(f"_send_spans() exception: {type(e).__name__}: {e}", exc_info=True)
+            logger.error(f"_send_spans() exception: {type(e).__name__}: {e}")
+            raise
+
+    def _send_spans_sync(self, spans: List[Dict[str, Any]]) -> None:
+        """Send spans to the server API (synchronous, for shutdown scenarios)."""
+        import requests
+
+        url = self._get_span_url()
+        headers = self._build_request_headers()
+        logger.debug(f"_send_spans_sync() sending {len(spans)} spans to {url}")
+        if self.api_key:
+            logger.debug("_send_spans_sync() using API key authentication")
+        else:
+            logger.debug("_send_spans_sync() no API key provided")
+
+        try:
+            response = requests.post(url, json=spans, headers=headers, timeout=10.0)
+            logger.debug(f"_send_spans_sync() received response: status={response.status_code}")
+            if not response.ok:
+                error_text = response.text[:200] if response.text else ""
+                logger.error(
+                    f"_send_spans_sync() failed: status={response.status_code}, "
+                    f"reason={response.reason}, error={error_text}"
+                )
+                raise Exception(
+                    f"Failed to send spans: {response.status_code} {response.reason} - {error_text}"
+                )
+            logger.debug(f"_send_spans_sync() successfully sent {len(spans)} spans")
+        except Exception as e:
+            logger.error(f"_send_spans_sync() exception: {type(e).__name__}: {e}")
             raise
 
     def shutdown(self) -> None:
@@ -291,24 +438,36 @@ class AIQASpanExporter(SpanExporter):
         else:
             logger.debug("shutdown() no active auto-flush thread to wait for")
 
-        # Final flush attempt (synchronous)
-        import asyncio
-        try:
-            loop = asyncio.get_event_loop()
-            if loop.is_running():
-                logger.debug("shutdown() event loop is running, using ThreadPoolExecutor for final flush")
-                # If loop is running, schedule flush
-                import concurrent.futures
-                with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(asyncio.run, self.flush())
-                    future.result(timeout=10.0)
+        # Final flush attempt (use synchronous send to avoid event loop issues)
+        with self.flush_lock:
+            logger.debug("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("shutdown() event loop exists but not running, using run_until_complete")
-                loop.run_until_complete(self.flush())
-        except RuntimeError:
-            # No event loop, create one
-            logger.debug("shutdown() no event loop found, creating new one for final flush")
-            asyncio.run(self.flush())
+                logger.debug("shutdown() no spans to flush")
         
         # Check buffer state after shutdown
         with self.buffer_lock:

aiqa/client.py

@@ -0,0 +1,170 @@
+# aiqa/client.py
+import os
+import logging
+from functools import lru_cache
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+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
+try:
+    from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+except ImportError:
+    try:
+        from opentelemetry.sdk.trace.sampling import TraceIdRatioBasedSampler as TraceIdRatioBased
+    except ImportError:
+        logger.warning(
+            "Could not import TraceIdRatioBased or TraceIdRatioBasedSampler from "
+            "opentelemetry.sdk.trace.sampling. AIQA tracing may not work correctly. "
+            "Please ensure opentelemetry-sdk>=1.24.0 is installed. "
+            "Try: pip install --upgrade opentelemetry-sdk"
+        )
+        # Set to None so we can check later
+        TraceIdRatioBased = None
+
+from .aiqa_exporter import AIQASpanExporter
+
+AIQA_TRACER_NAME = "aiqa-tracer"
+
+client = {
+    "provider": None,
+    "exporter": None,
+}
+
+# Component tag to add to all spans (can be set via AIQA_COMPONENT_TAG env var or programmatically)
+_component_tag: str = ""
+
+
+def get_component_tag() -> str:
+    """Get the current component tag."""
+    return _component_tag
+
+
+def set_component_tag(tag: str | None) -> None:
+    """Set the component tag programmatically (overrides environment variable)."""
+    global _component_tag
+    _component_tag = tag or ""
+
+
+@lru_cache(maxsize=1)
+def get_aiqa_client():
+    """
+    Initialize and return the AIQA client.
+    
+    This function must be called before using any AIQA tracing functionality to ensure
+    that environment variables (such as AIQA_SERVER_URL, AIQA_API_KEY, AIQA_COMPONENT_TAG)
+    are properly loaded and the tracing system is initialized.
+    
+    The function is idempotent - calling it multiple times is safe and will only
+    initialize once.
+    
+    Example:
+        from aiqa import get_aiqa_client, WithTracing
+        
+        # Initialize client (loads env vars)
+        get_aiqa_client()
+        
+        @WithTracing
+        def my_function():
+            pass
+    """
+    global client
+    try:
+        _init_tracing()
+    except Exception as e:
+        logger.error(f"Failed to initialize AIQA tracing: {e}")
+        logger.warning("AIQA tracing is disabled. Your application will continue to run without tracing.")
+    # optionally return a richer client object; for now you just need init    
+    return client
+
+def _init_tracing():
+    """Initialize tracing system and load configuration from environment variables."""
+    try:
+        # Initialize component tag from environment variable
+        set_component_tag(os.getenv("AIQA_COMPONENT_TAG", None))
+        
+        provider = trace.get_tracer_provider()
+
+        # Get sampling rate from environment (default: 1.0 = sample all)
+        sampling_rate = 1.0
+        if env_rate := os.getenv("AIQA_SAMPLING_RATE"):
+            try:
+                rate = float(env_rate)
+                sampling_rate = max(0.0, min(1.0, rate))  # Clamp to [0, 1]
+            except ValueError:
+                logger.warning(f"Invalid AIQA_SAMPLING_RATE value '{env_rate}', using default 1.0")
+
+        # If it's still the default proxy, install a real SDK provider
+        if not isinstance(provider, TracerProvider):
+            if TraceIdRatioBased is None:
+                raise ImportError(
+                    "TraceIdRatioBased sampler is not available. "
+                    "Please install opentelemetry-sdk>=1.24.0"
+                )
+            
+            # Create sampler based on trace-id for deterministic sampling
+            sampler = TraceIdRatioBased(sampling_rate)
+            provider = TracerProvider(sampler=sampler)
+            trace.set_tracer_provider(provider)
+
+        # Idempotently add your processor
+        _attach_aiqa_processor(provider)
+        global client
+        client["provider"] = provider
+        
+        # Log successful initialization
+        server_url = os.getenv("AIQA_SERVER_URL", "not configured")
+        logger.info(f"AIQA initialized and tracing (sampling rate: {sampling_rate:.2f}, server: {server_url})")
+        
+    except Exception as e:
+        logger.error(f"Error initializing AIQA tracing: {e}")
+        raise
+
+def _attach_aiqa_processor(provider: TracerProvider):
+    """Attach AIQA span processor to the provider. Idempotent - safe to call multiple times."""
+    try:
+        # Avoid double-adding if get_aiqa_client() is called multiple times
+        for p in provider._active_span_processor._span_processors:
+            if isinstance(getattr(p, "exporter", None), AIQASpanExporter):
+                logger.debug("AIQA span processor already attached, skipping")
+                return
+
+        exporter = AIQASpanExporter(
+            server_url=os.getenv("AIQA_SERVER_URL"),
+            api_key=os.getenv("AIQA_API_KEY"),
+        )
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        global client
+        client["exporter"] = exporter
+        logger.debug("AIQA span processor attached successfully")
+    except Exception as e:
+        logger.error(f"Error attaching AIQA span processor: {e}")
+        # Re-raise to let _init_tracing handle it - it will log and continue
+        raise
+
+
+def get_aiqa_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.
+    """
+    try:
+        # Import here to avoid circular import
+        from . import __version__
+        
+        # Compatibility: version parameter may not be supported in older OpenTelemetry versions
+        try:
+            # Try with version parameter (newer OpenTelemetry versions)
+            return trace.get_tracer(AIQA_TRACER_NAME, version=__version__)
+        except TypeError:
+            # Fall back to without version parameter (older versions)
+            return trace.get_tracer(AIQA_TRACER_NAME)
+    except Exception as e:
+        logger.error(f"Error getting AIQA tracer: {e}")
+        # Return a basic tracer as fallback to prevent crashes
+        return trace.get_tracer(AIQA_TRACER_NAME)