aiqa-client 0.1.2__tar.gz → 0.1.4__tar.gz

{aiqa_client-0.1.2/aiqa_client.egg-info → aiqa_client-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.1.2
+Version: 0.1.4
 Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
 Author-email: AIQA <info@aiqa.dev>
 License: MIT
@@ -72,15 +72,7 @@ export AIQA_API_KEY="your-api-key"
 ### 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()
+from aiqa import WithTracing
 
 @WithTracing
 def my_function(x, y):
@@ -116,12 +108,12 @@ def my_function(data):
 Spans are automatically flushed every 5 seconds. To flush immediately:
 
 ```python
-from aiqa import flush_tracing
+from aiqa import flush_spans
 import asyncio
 
 async def main():
     # Your code here
-    await flush_tracing()
+    await flush_spans()
 
 asyncio.run(main())
 ```
@@ -152,87 +144,6 @@ 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)
@@ -240,7 +151,6 @@ with tracer.start_as_current_span("operation", context=ctx):
 - 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.1.4/README.md

@@ -0,0 +1,120 @@
+# 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 aiqa import WithTracing
+
+@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_spans
+import asyncio
+
+async def main():
+    # Your code here
+    await flush_spans()
+
+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
+```
+
+## 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
+
+## Example
+
+See `example.py` for a complete working example.

aiqa_client-0.1.4/aiqa/__init__.py

@@ -0,0 +1,29 @@
+"""
+Python client for AIQA server - OpenTelemetry tracing decorators.
+"""
+
+from .tracing import (
+    WithTracing,
+    flush_spans,
+    shutdown_tracing,
+    set_span_attribute,
+    set_span_name,
+    get_active_span,
+    provider,
+    exporter,
+)
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "WithTracing",
+    "flush_spans",
+    "shutdown_tracing",
+    "set_span_attribute",
+    "set_span_name",
+    "get_active_span",
+    "provider",
+    "exporter",
+    "__version__",
+]
+

{aiqa_client-0.1.2 → aiqa_client-0.1.4}/aiqa/aiqa_exporter.py

@@ -8,12 +8,11 @@ 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("AIQA")
+logger = logging.getLogger(__name__)
 
 
 class AIQASpanExporter(SpanExporter):
@@ -40,7 +39,6 @@ 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
@@ -63,39 +61,21 @@ 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, deduplicating by (traceId, spanId)
+
+        # Serialize and add to buffer
         with self.buffer_lock:
-            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']}")
-            
+            serialized_spans = [self._serialize_span(span) for span in spans]
             self.buffer.extend(serialized_spans)
             buffer_size = len(self.buffer)
         
-        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}"
-            )
+        logger.debug(
+            f"export() added {len(spans)} span(s) to buffer. "
+            f"Total buffered: {buffer_size}"
+        )
 
         return SpanExportResult.SUCCESS
 
@@ -158,8 +138,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": self._get_instrumentation_name(),
-                "version": self._get_instrumentation_version(),
+                "name": span.instrumentation_info.name if hasattr(span, "instrumentation_info") else "",
+                "version": span.instrumentation_info.version if hasattr(span, "instrumentation_info") else None,
             },
         }
 
@@ -168,19 +148,6 @@ 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."""
@@ -210,38 +177,24 @@ 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. Rebuilds the span keys tracking set.
+        if sending fails.
         """
         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:
         """
@@ -265,8 +218,7 @@ 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)
+                # Spans already removed from buffer, nothing to clear
                 return
 
             logger.info(f"flush() sending {len(spans_to_flush)} span(s) to server")
@@ -274,8 +226,6 @@ 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:
@@ -287,12 +237,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}")
+                logger.error(f"Error flushing spans to server: {error}", exc_info=True)
                 # 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}")
+                logger.error(f"Error flushing spans to server: {error}", exc_info=True)
                 # Put spans back for retry
                 self._prepend_spans_to_buffer(spans_to_flush)
                 if self.shutdown_requested:
@@ -321,7 +271,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}")
+                    logger.error(f"Error in auto-flush cycle #{cycle_count}: {e}", exc_info=True)
                     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)
             
@@ -357,13 +307,9 @@ 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, data=data, headers=headers) as response:
+                async with session.post(url, json=spans, headers=headers) as response:
                     logger.debug(f"_send_spans() received response: status={response.status}")
                     if not response.ok:
                         error_text = await response.text()
@@ -382,10 +328,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}")
+            logger.error(f"_send_spans() RuntimeError: {type(e).__name__}: {e}", exc_info=True)
             raise
         except Exception as e:
-            logger.error(f"_send_spans() exception: {type(e).__name__}: {e}")
+            logger.error(f"_send_spans() exception: {type(e).__name__}: {e}", exc_info=True)
             raise
 
     def _send_spans_sync(self, spans: List[Dict[str, Any]]) -> None:
@@ -414,7 +360,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}")
+            logger.error(f"_send_spans_sync() exception: {type(e).__name__}: {e}", exc_info=True)
             raise
 
     def shutdown(self) -> None:
@@ -451,21 +397,17 @@ 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, clear their keys to free memory
-                    self._remove_span_keys_from_tracking(spans_to_flush)
+                    # Spans already removed from buffer
                 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}")
+                        logger.error(f"shutdown() failed to send spans: {e}", exc_info=True)
                         # 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")