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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.4
+Version: 0.3.6
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -67,6 +67,9 @@ export AIQA_SERVER_URL="http://localhost:3000"
 export AIQA_API_KEY="your-api-key"
 ```
 
+**Note:** If `AIQA_SERVER_URL` or `AIQA_API_KEY` are not set, tracing will be automatically disabled. You'll see one warning message at the start, and your application will continue to run without tracing.
+You can check if tracing is enabled via `get_aiqa_client().enabled`.
+
 ## Usage
 
 ### Basic Usage
@@ -141,6 +144,30 @@ async def main():
 asyncio.run(main())
 ```
 
+### Enabling/Disabling Tracing
+
+You can programmatically enable or disable tracing:
+
+```python
+from aiqa import get_aiqa_client
+
+client = get_aiqa_client()
+
+# Disable tracing (spans won't be created or exported)
+client.set_enabled(False)
+
+# Re-enable tracing
+client.set_enabled(True)
+
+# Check if tracing is enabled
+if client.enabled:
+    print("Tracing is enabled")
+```
+
+When tracing is disabled:
+- Spans are not created (functions execute normally without tracing overhead)
+- Spans are not exported to the server
+
 ### Setting Span Attributes and Names
 
 ```python
@@ -176,10 +203,10 @@ To link traces across different services or agents, you can extract and propagat
 #### Getting Current Trace ID
 
 ```python
-from aiqa import get_trace_id, get_span_id
+from aiqa import get_active_trace_id, get_span_id
 
 # Get the current trace ID and span ID
-trace_id = get_trace_id()  # Returns hex string (32 chars) or None
+trace_id = get_active_trace_id()  # Returns hex string (32 chars) or None
 span_id = get_span_id()    # Returns hex string (16 chars) or None
 
 # Pass these to another service (e.g., in HTTP headers, message queue, etc.)

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

@@ -30,6 +30,9 @@ export AIQA_SERVER_URL="http://localhost:3000"
 export AIQA_API_KEY="your-api-key"
 ```
 
+**Note:** If `AIQA_SERVER_URL` or `AIQA_API_KEY` are not set, tracing will be automatically disabled. You'll see one warning message at the start, and your application will continue to run without tracing.
+You can check if tracing is enabled via `get_aiqa_client().enabled`.
+
 ## Usage
 
 ### Basic Usage
@@ -104,6 +107,30 @@ async def main():
 asyncio.run(main())
 ```
 
+### Enabling/Disabling Tracing
+
+You can programmatically enable or disable tracing:
+
+```python
+from aiqa import get_aiqa_client
+
+client = get_aiqa_client()
+
+# Disable tracing (spans won't be created or exported)
+client.set_enabled(False)
+
+# Re-enable tracing
+client.set_enabled(True)
+
+# Check if tracing is enabled
+if client.enabled:
+    print("Tracing is enabled")
+```
+
+When tracing is disabled:
+- Spans are not created (functions execute normally without tracing overhead)
+- Spans are not exported to the server
+
 ### Setting Span Attributes and Names
 
 ```python
@@ -139,10 +166,10 @@ To link traces across different services or agents, you can extract and propagat
 #### Getting Current Trace ID
 
 ```python
-from aiqa import get_trace_id, get_span_id
+from aiqa import get_active_trace_id, get_span_id
 
 # Get the current trace ID and span ID
-trace_id = get_trace_id()  # Returns hex string (32 chars) or None
+trace_id = get_active_trace_id()  # Returns hex string (32 chars) or None
 span_id = get_span_id()    # Returns hex string (16 chars) or None
 
 # Pass these to another service (e.g., in HTTP headers, message queue, etc.)

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

@@ -28,7 +28,7 @@ from .tracing import (
     get_active_span,
     get_provider,
     get_exporter,
-    get_trace_id,
+    get_active_trace_id,
     get_span_id,
     create_span_from_trace_id,
     inject_trace_context,
@@ -37,10 +37,10 @@ from .tracing import (
     set_component_tag,
     get_span,
 )
-from .client import get_aiqa_client
+from .client import get_aiqa_client, set_enabled
 from .experiment_runner import ExperimentRunner
 
-__version__ = "0.3.4"
+__version__ = "0.3.6"
 
 __all__ = [
     "WithTracing",
@@ -52,8 +52,9 @@ __all__ = [
     "get_provider",
     "get_exporter",
     "get_aiqa_client",
+    "set_enabled",
     "ExperimentRunner",
-    "get_trace_id",
+    "get_active_trace_id",
     "get_span_id",
     "create_span_from_trace_id",
     "inject_trace_context",

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

@@ -71,6 +71,18 @@ class AIQASpanExporter(SpanExporter):
         if not spans:
             logger.debug("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() called with {len(spans)} spans")
         # Serialize and add to buffer, deduplicating by (traceId, spanId)
         with self.buffer_lock:

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

@@ -2,6 +2,7 @@
 import os
 import logging
 from functools import lru_cache
+from typing import Optional
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
@@ -31,10 +32,79 @@ from .aiqa_exporter import AIQASpanExporter
 
 AIQA_TRACER_NAME = "aiqa-tracer"
 
-client = {
-    "provider": None,
-    "exporter": None,
-}
+
+class AIQAClient:
+    """
+    Singleton client for AIQA tracing.
+    
+    This class manages the tracing provider, exporter, and enabled state.
+    Access via get_aiqa_client() which returns the singleton instance.
+    """
+    _instance: Optional['AIQAClient'] = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._provider: Optional[TracerProvider] = None
+            cls._instance._exporter: Optional[AIQASpanExporter] = None
+            cls._instance._enabled: bool = True
+            cls._instance._initialized: bool = False
+        return cls._instance
+    
+    @property
+    def provider(self) -> Optional[TracerProvider]:
+        """Get the tracer provider."""
+        return self._provider
+    
+    @provider.setter
+    def provider(self, value: Optional[TracerProvider]) -> None:
+        """Set the tracer provider."""
+        self._provider = value
+    
+    @property
+    def exporter(self) -> Optional[AIQASpanExporter]:
+        """Get the span exporter."""
+        return self._exporter
+    
+    @exporter.setter
+    def exporter(self, value: Optional[AIQASpanExporter]) -> None:
+        """Set the span exporter."""
+        self._exporter = value
+    
+    @property
+    def enabled(self) -> bool:
+        """Check if tracing is enabled."""
+        return self._enabled
+    
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        """Set the enabled state."""
+        self._enabled = value
+    
+    def set_enabled(self, enabled: bool) -> None:
+        """
+        Enable or disable AIQA tracing.
+        
+        When disabled:
+        - Tracing does not create spans
+        - Export does not send spans
+        
+        Args:
+            enabled: True to enable tracing, False to disable
+        """
+        self._enabled = enabled
+        if enabled:
+            logger.info("AIQA tracing enabled")
+        else:
+            logger.info("AIQA tracing disabled")
+    
+    def is_enabled(self) -> bool:
+        """Check if tracing is enabled."""
+        return self._enabled
+
+
+# Global singleton instance (for backward compatibility with direct access)
+client: AIQAClient = AIQAClient()
 
 # Component tag to add to all spans (can be set via AIQA_COMPONENT_TAG env var or programmatically)
 _component_tag: str = ""
@@ -52,14 +122,17 @@ def set_component_tag(tag: str | None) -> None:
 
 
 @lru_cache(maxsize=1)
-def get_aiqa_client():
+def get_aiqa_client() -> AIQAClient:
     """
-    Initialize and return the AIQA client.
+    Initialize and return the AIQA client singleton.
     
     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 client object manages the tracing system state. Tracing is done by the WithTracing 
+    decorator. Experiments are run by the ExperimentRunner class.
+    
     The function is idempotent - calling it multiple times is safe and will only
     initialize once.
     
@@ -67,7 +140,7 @@ def get_aiqa_client():
         from aiqa import get_aiqa_client, WithTracing
         
         # Initialize client (loads env vars)
-        get_aiqa_client()
+        client = get_aiqa_client()
         
         @WithTracing
         def my_function():
@@ -79,12 +152,32 @@ def get_aiqa_client():
     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."""
+    global client
+    if client._initialized:
+        return
+    
     try:
+        # Check for required environment variables
+        server_url = os.getenv("AIQA_SERVER_URL")
+        api_key = os.getenv("AIQA_API_KEY")
+        
+        if not server_url or not api_key:
+            client.enabled = False
+            missing_vars = []
+            if not server_url:
+                missing_vars.append("AIQA_SERVER_URL")
+            if not api_key:
+                missing_vars.append("AIQA_API_KEY")
+            logger.warning(
+                f"AIQA tracing is disabled: missing required environment variables: {', '.join(missing_vars)}"
+            )
+            client._initialized = True
+            return
+        
         # Initialize component tag from environment variable
         set_component_tag(os.getenv("AIQA_COMPONENT_TAG", None))
         
@@ -114,15 +207,15 @@ def _init_tracing():
 
         # Idempotently add your processor
         _attach_aiqa_processor(provider)
-        global client
-        client["provider"] = provider
+        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})")
+        client._initialized = True
         
     except Exception as e:
         logger.error(f"Error initializing AIQA tracing: {e}")
+        client._initialized = True  # Mark as initialized even on error to prevent retry loops
         raise
 
 def _attach_aiqa_processor(provider: TracerProvider):
@@ -140,7 +233,7 @@ def _attach_aiqa_processor(provider: TracerProvider):
         )
         provider.add_span_processor(BatchSpanProcessor(exporter))
         global client
-        client["exporter"] = exporter
+        client.exporter = exporter
         logger.debug("AIQA span processor attached successfully")
     except Exception as e:
         logger.error(f"Error attaching AIQA span processor: {e}")
@@ -148,6 +241,27 @@ def _attach_aiqa_processor(provider: TracerProvider):
         raise
 
 
+def set_enabled(enabled: bool) -> None:
+    """
+    Enable or disable AIQA tracing.
+    
+    When disabled:
+    - Tracing does not create spans
+    - Export does not send spans
+    
+    Args:
+        enabled: True to enable tracing, False to disable
+    
+    Example:
+        from aiqa import get_aiqa_client
+        
+        client = get_aiqa_client()
+        client.set_enabled(False)  # Disable tracing
+    """
+    client = get_aiqa_client()
+    client.set_enabled(enabled)
+
+
 def get_aiqa_tracer():
     """
     Get the AIQA tracer with version from __init__.py __version__.

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

@@ -29,10 +29,10 @@ async def flush_tracing() -> None:
     This flushes both the BatchSpanProcessor and the exporter buffer.
     """
     client = get_aiqa_client()
-    if client.get("provider"):
-        client["provider"].force_flush()  # Synchronous method
-    if client.get("exporter"):    
-        await client["exporter"].flush()
+    if client.provider:
+        client.provider.force_flush()  # Synchronous method
+    if client.exporter:    
+        await client.exporter.flush()
 
 
 async def shutdown_tracing() -> None:
@@ -42,10 +42,10 @@ async def shutdown_tracing() -> None:
     """
     try:
         client = get_aiqa_client()
-        if client.get("provider"):
-            client["provider"].shutdown()  # Synchronous method
-        if client.get("exporter"):
-            client["exporter"].shutdown()  # Synchronous method
+        if client.provider:
+            client.provider.shutdown()  # Synchronous method
+        if client.exporter:
+            client.exporter.shutdown()  # Synchronous method
     except Exception as e:
         logger.error(f"Error shutting down tracing: {e}")
 
@@ -55,7 +55,7 @@ async def shutdown_tracing() -> None:
 __all__ = [
     "get_provider", "get_exporter", "flush_tracing", "shutdown_tracing", "WithTracing",
     "set_span_attribute", "set_span_name", "get_active_span",
-    "get_trace_id", "get_span_id", "create_span_from_trace_id", "inject_trace_context", "extract_trace_context",
+    "get_active_trace_id", "get_span_id", "create_span_from_trace_id", "inject_trace_context", "extract_trace_context",
     "set_conversation_id", "set_component_tag", "set_token_usage", "set_provider_and_model", "get_span", "submit_feedback"
 ]
 
@@ -640,7 +640,10 @@ def WithTracing(
         def _execute_with_span_sync(executor: Callable[[], Any], input_data: Any) -> Any:
             """Execute sync function within span context, handling input/output and exceptions."""
             # Ensure tracer provider is initialized before creating spans
-            get_aiqa_client()
+            client = get_aiqa_client()
+            if not client.enabled:
+                return executor()
+            
             with tracer.start_as_current_span(fn_name) as span:
                 if not _setup_span(span, input_data):
                     return executor()
@@ -656,7 +659,10 @@ def WithTracing(
         async def _execute_with_span_async(executor: Callable[[], Any], input_data: Any) -> Any:
             """Execute async function within span context, handling input/output and exceptions."""
             # Ensure tracer provider is initialized before creating spans
-            get_aiqa_client()
+            client = get_aiqa_client()
+            if not client.enabled:
+                return await executor()
+            
             with tracer.start_as_current_span(fn_name) as span:
                 if not _setup_span(span, input_data):
                     return await executor()
@@ -675,7 +681,10 @@ def WithTracing(
         def _execute_generator_sync(executor: Callable[[], Any], input_data: Any) -> Any:
             """Execute sync generator function, returning a traced generator."""
             # Ensure tracer provider is initialized before creating spans
-            get_aiqa_client()
+            client = get_aiqa_client()
+            if not client.enabled:
+                return executor()
+            
             # Create span but don't use 'with' - span will be closed by TracedGenerator
             span = tracer.start_span(fn_name)
             token = trace.context_api.attach(trace.context_api.set_span_in_context(span))
@@ -698,7 +707,10 @@ def WithTracing(
         async def _execute_generator_async(executor: Callable[[], Any], input_data: Any) -> Any:
             """Execute async generator function, returning a traced async generator."""
             # Ensure tracer provider is initialized before creating spans
-            get_aiqa_client()
+            client = get_aiqa_client()
+            if not client.enabled:
+                return await executor()
+            
             # Create span but don't use 'with' - span will be closed by TracedAsyncGenerator
             span = tracer.start_span(fn_name)
             token = trace.context_api.attach(trace.context_api.set_span_in_context(span))
@@ -960,15 +972,15 @@ def set_component_tag(tag: str) -> None:
 def get_provider() -> Optional[TracerProvider]:
     """Get the tracer provider for advanced usage."""
     client = get_aiqa_client()
-    return client.get("provider")
+    return client.provider
 
 def get_exporter() -> Optional[AIQASpanExporter]:
     """Get the exporter for advanced usage."""
     client = get_aiqa_client()
-    return client.get("exporter")
+    return client.exporter
 
 
-def get_trace_id() -> Optional[str]:
+def get_active_trace_id() -> Optional[str]:
     """
     Get the current trace ID as a hexadecimal string (32 characters).
     
@@ -976,9 +988,10 @@ def get_trace_id() -> Optional[str]:
         The trace ID as a hex string, or None if no active span exists.
     
     Example:
-        trace_id = get_trace_id()
+        trace_id = get_active_trace_id()
         # Pass trace_id to another service/agent
         # e.g., include in HTTP headers, message queue metadata, etc.
+        # Within a single thread, OpenTelemetry normally does this for you.
     """
     span = trace.get_current_span()
     if span and span.get_span_context().is_valid:
@@ -1023,7 +1036,7 @@ def create_span_from_trace_id(
     
     Example:
         # In service A: get trace ID
-        trace_id = get_trace_id()
+        trace_id = get_active_trace_id()
         span_id = get_span_id()
         
         # Send to service B (e.g., via HTTP, message queue, etc.)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.3.4
+Version: 0.3.6
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -67,6 +67,9 @@ export AIQA_SERVER_URL="http://localhost:3000"
 export AIQA_API_KEY="your-api-key"
 ```
 
+**Note:** If `AIQA_SERVER_URL` or `AIQA_API_KEY` are not set, tracing will be automatically disabled. You'll see one warning message at the start, and your application will continue to run without tracing.
+You can check if tracing is enabled via `get_aiqa_client().enabled`.
+
 ## Usage
 
 ### Basic Usage
@@ -141,6 +144,30 @@ async def main():
 asyncio.run(main())
 ```
 
+### Enabling/Disabling Tracing
+
+You can programmatically enable or disable tracing:
+
+```python
+from aiqa import get_aiqa_client
+
+client = get_aiqa_client()
+
+# Disable tracing (spans won't be created or exported)
+client.set_enabled(False)
+
+# Re-enable tracing
+client.set_enabled(True)
+
+# Check if tracing is enabled
+if client.enabled:
+    print("Tracing is enabled")
+```
+
+When tracing is disabled:
+- Spans are not created (functions execute normally without tracing overhead)
+- Spans are not exported to the server
+
 ### Setting Span Attributes and Names
 
 ```python
@@ -176,10 +203,10 @@ To link traces across different services or agents, you can extract and propagat
 #### Getting Current Trace ID
 
 ```python
-from aiqa import get_trace_id, get_span_id
+from aiqa import get_active_trace_id, get_span_id
 
 # Get the current trace ID and span ID
-trace_id = get_trace_id()  # Returns hex string (32 chars) or None
+trace_id = get_active_trace_id()  # Returns hex string (32 chars) or None
 span_id = get_span_id()    # Returns hex string (16 chars) or None
 
 # Pass these to another service (e.g., in HTTP headers, message queue, etc.)

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

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