aiqa-client 0.2.0__tar.gz → 0.3.1__tar.gz

{aiqa_client-0.2.0/aiqa_client.egg-info → aiqa_client-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.2.0
+Version: 0.3.1
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -72,7 +72,15 @@ export AIQA_API_KEY="your-api-key"
 ### Basic Usage
 
 ```python
-from aiqa import WithTracing
+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)
+# This loads environment variables and initializes the tracing system
+get_aiqa_client()
 
 @WithTracing
 def my_function(x, y):
@@ -108,12 +116,12 @@ def my_function(data):
 Spans are automatically flushed every 5 seconds. To flush immediately:
 
 ```python
-from aiqa import flush_spans
+from aiqa import flush_tracing
 import asyncio
 
 async def main():
     # Your code here
-    await flush_spans()
+    await flush_tracing()
 
 asyncio.run(main())
 ```
@@ -144,6 +152,87 @@ def my_function():
     # ... rest of function
 ```
 
+### Grouping Traces by Conversation
+
+To group multiple traces together that are part of the same conversation or session:
+
+```python
+from aiqa import WithTracing, set_conversation_id
+
+@WithTracing
+def handle_user_request(user_id: str, session_id: str):
+    # Set conversation ID to group all traces for this user session
+    set_conversation_id(f"user_{user_id}_session_{session_id}")
+    # All spans created in this function and its children will have this gen_ai.conversation.id
+    # ... rest of function
+```
+
+The `gen_ai.conversation.id` attribute allows you to filter and group traces in the AIQA server by conversation, making it easier to analyze multi-step interactions or user sessions. See the [OpenTelemetry GenAI Events specification](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/) for more details.
+
+### Trace ID Propagation Across Services/Agents
+
+To link traces across different services or agents, you can extract and propagate trace IDs:
+
+#### Getting Current Trace ID
+
+```python
+from aiqa import get_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
+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.)
+```
+
+#### Continuing a Trace in Another Service
+
+```python
+from aiqa import create_span_from_trace_id
+
+# Continue a trace from another service/agent
+# trace_id and parent_span_id come from the other service
+with create_span_from_trace_id(
+    trace_id="abc123...", 
+    parent_span_id="def456...",
+    span_name="service_b_operation"
+):
+    # Your code here - this span will be linked to the original trace
+    pass
+```
+
+#### Using OpenTelemetry Context Propagation (Recommended)
+
+For HTTP requests, use the built-in context propagation:
+
+```python
+from aiqa import inject_trace_context, extract_trace_context
+import requests
+from opentelemetry.trace import use_span
+
+# In the sending service:
+headers = {}
+inject_trace_context(headers)  # Adds trace context to headers
+response = requests.get("http://other-service/api", headers=headers)
+
+# In the receiving service:
+# Extract context from incoming request headers
+ctx = extract_trace_context(request.headers)
+
+# Use the context to create a span
+from opentelemetry.trace import use_span
+with use_span(ctx):
+    # Your code here
+    pass
+
+# Or create a span with the context
+from opentelemetry import trace
+tracer = trace.get_tracer("aiqa-tracer")
+with tracer.start_as_current_span("operation", context=ctx):
+    # Your code here
+    pass
+```
+
 ## Features
 
 - Automatic tracing of function calls (sync and async)
@@ -151,6 +240,7 @@ def my_function():
 - Automatic error tracking and exception recording
 - Thread-safe span buffering and auto-flushing
 - OpenTelemetry context propagation for nested spans
+- Trace ID propagation utilities for distributed tracing
 
 ## Example
 

aiqa_client-0.3.1/README.md

@@ -0,0 +1,210 @@
+# A Python client for the AIQA server
+
+OpenTelemetry-based client for tracing Python functions and sending traces to the AIQA server.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install aiqa-client
+```
+
+### From source
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+See [TESTING.md](TESTING.md) for detailed testing instructions.
+
+## Setup
+
+Set the following environment variables:
+
+```bash
+export AIQA_SERVER_URL="http://localhost:3000"
+export AIQA_API_KEY="your-api-key"
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+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)
+# This loads environment variables and initializes the tracing system
+get_aiqa_client()
+
+@WithTracing
+def my_function(x, y):
+    return x + y
+
+@WithTracing
+async def my_async_function(x, y):
+    await asyncio.sleep(0.1)
+    return x * y
+```
+
+### Custom Span Name
+
+```python
+@WithTracing(name="custom_span_name")
+def my_function():
+    pass
+```
+
+### Input/Output Filtering
+
+```python
+@WithTracing(
+    filter_input=lambda x: {"filtered": str(x)},
+    filter_output=lambda x: {"result": x}
+)
+def my_function(data):
+    return {"processed": data}
+```
+
+### Flushing Spans
+
+Spans are automatically flushed every 5 seconds. To flush immediately:
+
+```python
+from aiqa import flush_tracing
+import asyncio
+
+async def main():
+    # Your code here
+    await flush_tracing()
+
+asyncio.run(main())
+```
+
+### Shutting Down
+
+To ensure all spans are sent before process exit:
+
+```python
+from aiqa import shutdown_tracing
+import asyncio
+
+async def main():
+    # Your code here
+    await shutdown_tracing()
+
+asyncio.run(main())
+```
+
+### Setting Span Attributes and Names
+
+```python
+from aiqa import set_span_attribute, set_span_name
+
+def my_function():
+    set_span_attribute("custom.attribute", "value")
+    set_span_name("custom_span_name")
+    # ... rest of function
+```
+
+### Grouping Traces by Conversation
+
+To group multiple traces together that are part of the same conversation or session:
+
+```python
+from aiqa import WithTracing, set_conversation_id
+
+@WithTracing
+def handle_user_request(user_id: str, session_id: str):
+    # Set conversation ID to group all traces for this user session
+    set_conversation_id(f"user_{user_id}_session_{session_id}")
+    # All spans created in this function and its children will have this gen_ai.conversation.id
+    # ... rest of function
+```
+
+The `gen_ai.conversation.id` attribute allows you to filter and group traces in the AIQA server by conversation, making it easier to analyze multi-step interactions or user sessions. See the [OpenTelemetry GenAI Events specification](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/) for more details.
+
+### Trace ID Propagation Across Services/Agents
+
+To link traces across different services or agents, you can extract and propagate trace IDs:
+
+#### Getting Current Trace ID
+
+```python
+from aiqa import get_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
+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.)
+```
+
+#### Continuing a Trace in Another Service
+
+```python
+from aiqa import create_span_from_trace_id
+
+# Continue a trace from another service/agent
+# trace_id and parent_span_id come from the other service
+with create_span_from_trace_id(
+    trace_id="abc123...", 
+    parent_span_id="def456...",
+    span_name="service_b_operation"
+):
+    # Your code here - this span will be linked to the original trace
+    pass
+```
+
+#### Using OpenTelemetry Context Propagation (Recommended)
+
+For HTTP requests, use the built-in context propagation:
+
+```python
+from aiqa import inject_trace_context, extract_trace_context
+import requests
+from opentelemetry.trace import use_span
+
+# In the sending service:
+headers = {}
+inject_trace_context(headers)  # Adds trace context to headers
+response = requests.get("http://other-service/api", headers=headers)
+
+# In the receiving service:
+# Extract context from incoming request headers
+ctx = extract_trace_context(request.headers)
+
+# Use the context to create a span
+from opentelemetry.trace import use_span
+with use_span(ctx):
+    # Your code here
+    pass
+
+# Or create a span with the context
+from opentelemetry import trace
+tracer = trace.get_tracer("aiqa-tracer")
+with tracer.start_as_current_span("operation", context=ctx):
+    # Your code here
+    pass
+```
+
+## Features
+
+- Automatic tracing of function calls (sync and async)
+- Records function inputs and outputs as span attributes
+- Automatic error tracking and exception recording
+- Thread-safe span buffering and auto-flushing
+- OpenTelemetry context propagation for nested spans
+- Trace ID propagation utilities for distributed tracing
+
+## Example
+
+See `example.py` for a complete working example.

aiqa_client-0.3.1/aiqa/__init__.py

@@ -0,0 +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_tracing,
+    shutdown_tracing,
+    set_span_attribute,
+    set_span_name,
+    get_active_span,
+    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.3.1"
+
+__all__ = [
+    "WithTracing",
+    "flush_tracing",
+    "shutdown_tracing",
+    "set_span_attribute",
+    "set_span_name",
+    "get_active_span",
+    "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_client-0.2.0 → aiqa_client-0.3.1}/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
         logger.debug(f"AIQA export() called with {len(spans)} spans")
-        # Serialize and add to buffer
+        # 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,6 +168,19 @@ 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."""
@@ -177,24 +210,38 @@ class AIQASpanExporter(SpanExporter):
         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.
+        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:
         """
@@ -218,7 +265,8 @@ 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, nothing to clear
+                # 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")
@@ -226,6 +274,8 @@ class AIQASpanExporter(SpanExporter):
                 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:
@@ -237,12 +287,12 @@ class AIQASpanExporter(SpanExporter):
                         # Put spans back for retry
                         self._prepend_spans_to_buffer(spans_to_flush)
                     raise
-                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)
                 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:
@@ -271,7 +321,7 @@ 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)
             
@@ -307,9 +357,13 @@ class AIQASpanExporter(SpanExporter):
             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()
@@ -328,10 +382,10 @@ class AIQASpanExporter(SpanExporter):
                 else:
                     logger.warning(f"_send_spans() interrupted by interpreter shutdown: {e}")
                 raise
-            logger.error(f"_send_spans() RuntimeError: {type(e).__name__}: {e}", exc_info=True)
+            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:
@@ -360,7 +414,7 @@ class AIQASpanExporter(SpanExporter):
                 )
             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}", exc_info=True)
+            logger.error(f"_send_spans_sync() exception: {type(e).__name__}: {e}")
             raise
 
     def shutdown(self) -> None:
@@ -397,17 +451,21 @@ class AIQASpanExporter(SpanExporter):
                         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
+                    # 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}", exc_info=True)
+                        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() no spans to flush")