aiqa-client 0.1.0__tar.gz

aiqa_client-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 AIQA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

aiqa_client-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include aiqa *.py
+recursive-include aiqa py.typed
+

aiqa_client-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aiqa-client
+Version: 0.1.0
+Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
+Author-email: AIQA <info@aiqa.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/winterstein/aiqa
+Project-URL: Documentation, https://github.com/winterstein/aiqa/tree/main/client-python
+Project-URL: Repository, https://github.com/winterstein/aiqa
+Project-URL: Issues, https://github.com/winterstein/aiqa/issues
+Keywords: opentelemetry,tracing,observability,aiqa,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.40b0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# 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.0/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.0/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.0"
+
+__all__ = [
+    "WithTracing",
+    "flush_spans",
+    "shutdown_tracing",
+    "set_span_attribute",
+    "set_span_name",
+    "get_active_span",
+    "provider",
+    "exporter",
+    "__version__",
+]
+

aiqa_client-0.1.0/aiqa/aiqa_exporter.py

@@ -0,0 +1,248 @@
+"""
+OpenTelemetry span exporter that sends spans to the AIQA server API.
+Buffers spans and flushes them periodically or on shutdown. Thread-safe.
+"""
+
+import os
+import json
+import logging
+import threading
+import time
+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__)
+
+
+class AIQASpanExporter(SpanExporter):
+    """
+    Exports spans to AIQA server. Buffers spans and auto-flushes every flush_interval_seconds.
+    Call shutdown() before process exit to flush remaining spans.
+    """
+
+    def __init__(
+        self,
+        server_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        flush_interval_seconds: float = 5.0,
+    ):
+        """
+        Initialize the AIQA span exporter.
+
+        Args:
+            server_url: URL of the AIQA server (defaults to AIQA_SERVER_URL env var)
+            api_key: API key for authentication (defaults to AIQA_API_KEY env var)
+            flush_interval_seconds: How often to flush spans to the server
+        """
+        self._server_url = server_url
+        self._api_key = api_key
+        self.flush_interval_ms = flush_interval_seconds * 1000
+        self.buffer: List[Dict[str, Any]] = []
+        self.buffer_lock = threading.Lock()
+        self.flush_lock = threading.Lock()
+        self.shutdown_requested = False
+        self.flush_timer: Optional[threading.Thread] = None
+        self._start_auto_flush()
+
+    @property
+    def server_url(self) -> str:         
+        return self._server_url or os.getenv("AIQA_SERVER_URL", "").rstrip("/")
+
+    @property
+    def api_key(self) -> str:
+        return self._api_key or os.getenv("AIQA_API_KEY", "")
+
+    def export(self, spans: List[ReadableSpan]) -> SpanExportResult:
+        """
+        Export spans to the AIQA server. Adds spans to buffer for async flushing.
+        """
+        if not spans:
+            return SpanExportResult.SUCCESS
+
+        # Serialize and add to buffer
+        with self.buffer_lock:
+            serialized_spans = [self._serialize_span(span) for span in spans]
+            self.buffer.extend(serialized_spans)
+
+        return SpanExportResult.SUCCESS
+
+    def _serialize_span(self, span: ReadableSpan) -> Dict[str, Any]:
+        """Convert ReadableSpan to a serializable format."""
+        span_context = span.get_span_context()
+        
+        # Get parent span ID
+        parent_span_id = None
+        if hasattr(span, "parent") and span.parent:
+            parent_span_id = format(span.parent.span_id, "016x")
+        elif hasattr(span, "parent_span_id") and span.parent_span_id:
+            parent_span_id = format(span.parent_span_id, "016x")
+        
+        # Get span kind (handle both enum and int)
+        span_kind = span.kind
+        if hasattr(span_kind, "value"):
+            span_kind = span_kind.value
+        
+        # Get status code (handle both enum and int)
+        status_code = span.status.status_code
+        if hasattr(status_code, "value"):
+            status_code = status_code.value
+        
+        return {
+            "name": span.name,
+            "kind": span_kind,
+            "parentSpanId": parent_span_id,
+            "startTime": self._time_to_tuple(span.start_time),
+            "endTime": self._time_to_tuple(span.end_time) if span.end_time else None,
+            "status": {
+                "code": status_code,
+                "message": getattr(span.status, "description", None),
+            },
+            "attributes": dict(span.attributes) if span.attributes else {},
+            "links": [
+                {
+                    "context": {
+                        "traceId": format(link.context.trace_id, "032x"),
+                        "spanId": format(link.context.span_id, "016x"),
+                    },
+                    "attributes": dict(link.attributes) if link.attributes else {},
+                }
+                for link in (span.links or [])
+            ],
+            "events": [
+                {
+                    "name": event.name,
+                    "time": self._time_to_tuple(event.timestamp),
+                    "attributes": dict(event.attributes) if event.attributes else {},
+                }
+                for event in (span.events or [])
+            ],
+            "resource": {
+                "attributes": dict(span.resource.attributes) if span.resource.attributes else {},
+            },
+            "traceId": format(span_context.trace_id, "032x"),
+            "spanId": format(span_context.span_id, "016x"),
+            "traceFlags": span_context.trace_flags,
+            "duration": self._time_to_tuple(span.end_time - span.start_time) if span.end_time else None,
+            "ended": span.end_time is not None,
+            "instrumentationLibrary": {
+                "name": span.instrumentation_info.name if hasattr(span, "instrumentation_info") else "",
+                "version": span.instrumentation_info.version if hasattr(span, "instrumentation_info") else None,
+            },
+        }
+
+    def _time_to_tuple(self, nanoseconds: int) -> tuple:
+        """Convert nanoseconds to (seconds, nanoseconds) tuple."""
+        seconds = int(nanoseconds // 1_000_000_000)
+        nanos = int(nanoseconds % 1_000_000_000)
+        return (seconds, nanos)
+
+    async def flush(self) -> None:
+        """
+        Flush buffered spans to the server. Thread-safe: ensures only one flush operation runs at a time.
+        """
+        with self.flush_lock:
+            # Get current buffer and clear it atomically
+            with self.buffer_lock:
+                spans_to_flush = self.buffer[:]
+                self.buffer.clear()
+
+            if not spans_to_flush:
+                return
+
+            # Skip sending if server URL is not configured
+            if not self.server_url:
+                logger.warning(
+                    f"Skipping flush: AIQA_SERVER_URL is not set. {len(spans_to_flush)} span(s) will not be sent."
+                )
+                return
+
+            try:
+                await self._send_spans(spans_to_flush)
+            except Exception as error:
+                logger.error(f"Error flushing spans to server: {error}")
+                if self.shutdown_requested:
+                    raise
+
+    def _start_auto_flush(self) -> None:
+        """Start the auto-flush timer."""
+        if self.shutdown_requested:
+            return
+
+        def flush_worker():
+            import asyncio
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            
+            while not self.shutdown_requested:
+                try:
+                    loop.run_until_complete(self.flush())
+                    time.sleep(self.flush_interval_ms / 1000.0)
+                except Exception as e:
+                    logger.error(f"Error in auto-flush: {e}")
+                    time.sleep(self.flush_interval_ms / 1000.0)
+            
+            # Final flush on shutdown
+            if self.shutdown_requested:
+                try:
+                    loop.run_until_complete(self.flush())
+                except Exception as e:
+                    logger.error(f"Error in final flush: {e}")
+                finally:
+                    loop.close()
+
+        flush_thread = threading.Thread(target=flush_worker, daemon=True)
+        flush_thread.start()
+        self.flush_timer = flush_thread
+
+    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.")
+
+        import aiohttp
+
+        logger.debug(f"Sending {len(spans)} spans to server: {self.server_url}")
+
+        headers = {
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"ApiKey {self.api_key}"
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                f"{self.server_url}/span",
+                json=spans,
+                headers=headers,
+            ) as response:
+                if not response.ok:
+                    error_text = await response.text()
+                    raise Exception(
+                        f"Failed to send spans: {response.status} {response.reason} - {error_text}"
+                    )
+
+    def shutdown(self) -> None:
+        """Shutdown the exporter, flushing any remaining spans. Call before process exit."""
+        self.shutdown_requested = True
+
+        # Wait for flush thread to finish (it will do final flush)
+        if self.flush_timer and self.flush_timer.is_alive():
+            self.flush_timer.join(timeout=10.0)
+
+        # Final flush attempt (synchronous)
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # 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)
+            else:
+                loop.run_until_complete(self.flush())
+        except RuntimeError:
+            # No event loop, create one
+            asyncio.run(self.flush())
+

aiqa_client-0.1.0/aiqa/tracing.py

@@ -0,0 +1,307 @@
+"""
+OpenTelemetry tracing setup and utilities. Initializes tracer provider on import.
+Provides WithTracing decorator to automatically trace function calls.
+"""
+
+import os
+import json
+import logging
+import inspect
+from typing import Any, Callable, Optional, Dict
+from functools import wraps
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.semconv.resource import ResourceAttributes
+from opentelemetry.trace import Status, StatusCode
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from .aiqa_exporter import AIQASpanExporter
+
+logger = logging.getLogger(__name__)
+
+# Load environment variables
+exporter = AIQASpanExporter()
+
+# Initialize OpenTelemetry
+provider = TracerProvider(
+    resource=Resource.create(
+        {
+            ResourceAttributes.SERVICE_NAME: os.getenv("OTEL_SERVICE_NAME", "aiqa-service"),
+        }
+    )
+)
+
+provider.add_span_processor(BatchSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+
+# Get a tracer instance
+tracer = trace.get_tracer("aiqa-tracer")
+
+
+async def flush_spans() -> None:
+    """
+    Flush all pending spans to the server.
+    Flushes also happen automatically every few seconds. So you only need to call this function
+    if you want to flush immediately, e.g. before exiting a process.
+
+    This flushes both the BatchSpanProcessor and the exporter buffer.
+    """
+    provider.force_flush()  # Synchronous method
+    await exporter.flush()
+
+
+async def shutdown_tracing() -> None:
+    """
+    Shutdown the tracer provider and exporter.
+    It is not necessary to call this function.
+    """
+    provider.shutdown()  # Synchronous method
+    await exporter.shutdown()
+
+
+# Export provider and exporter for advanced usage
+__all__ = ["provider", "exporter", "flush_spans", "shutdown_tracing", "WithTracing", "set_span_attribute", "set_span_name", "get_active_span"]
+
+
+class TracingOptions:
+    """Options for WithTracing decorator"""
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        ignore_input: Optional[Any] = None,
+        ignore_output: Optional[Any] = None,
+        filter_input: Optional[Callable[[Any], Any]] = None,
+        filter_output: Optional[Callable[[Any], Any]] = None,
+    ):
+        self.name = name
+        self.ignore_input = ignore_input
+        self.ignore_output = ignore_output
+        self.filter_input = filter_input
+        self.filter_output = filter_output
+
+
+def _serialize_for_span(value: Any) -> Any:
+    """
+    Serialize a value for span attributes.
+    OpenTelemetry only accepts primitives (bool, str, bytes, int, float) or sequences of those.
+    Complex types (dicts, lists, objects) are converted to JSON strings.
+    """
+    # Keep primitives as is (including None)
+    if value is None or isinstance(value, (str, int, float, bool, bytes)):
+        return value
+    
+    # For sequences, check if all elements are primitives
+    if isinstance(value, (list, tuple)):
+        # If all elements are primitives, return as list
+        if all(isinstance(item, (str, int, float, bool, bytes, type(None))) for item in value):
+            return list(value)
+        # Otherwise serialize to JSON string
+        try:
+            return json.dumps(value)
+        except (TypeError, ValueError):
+            return str(value)
+    
+    # For dicts and other complex types, serialize to JSON string
+    try:
+        return json.dumps(value)
+    except (TypeError, ValueError):
+        # If JSON serialization fails, convert to string
+        return str(value)
+
+
+def _prepare_input(args: tuple, kwargs: dict) -> Any:
+    """Prepare input for span attributes."""
+    if not args and not kwargs:
+        return None
+    if len(args) == 1 and not kwargs:
+        return _serialize_for_span(args[0])
+    # Multiple args or kwargs - combine into dict
+    result = {}
+    if args:
+        result["args"] = [_serialize_for_span(arg) for arg in args]
+    if kwargs:
+        result["kwargs"] = {k: _serialize_for_span(v) for k, v in kwargs.items()}
+    return result
+
+
+def WithTracing(
+    func: Optional[Callable] = None,
+    *,
+    name: Optional[str] = None,
+    ignore_input: Optional[Any] = None,
+    ignore_output: Optional[Any] = None,
+    filter_input: Optional[Callable[[Any], Any]] = None,
+    filter_output: Optional[Callable[[Any], Any]] = None,
+):
+    """
+    Decorator to automatically create spans for function calls.
+    Records input/output as span attributes. Spans are automatically linked via OpenTelemetry context.
+    
+    Works with both synchronous and asynchronous functions.
+    
+    Args:
+        func: The function to trace (when used as @WithTracing)
+        name: Optional custom name for the span (defaults to function name)
+        ignore_input: Fields to ignore in input (not yet implemented)
+        ignore_output: Fields to ignore in output (not yet implemented)
+        filter_input: Function to filter/transform input before recording
+        filter_output: Function to filter/transform output before recording
+    
+    Example:
+        @WithTracing
+        def my_function(x, y):
+            return x + y
+        
+        @WithTracing
+        async def my_async_function(x, y):
+            return x + y
+        
+        @WithTracing(name="custom_name")
+        def another_function():
+            pass
+    """
+    def decorator(fn: Callable) -> Callable:
+        fn_name = name or fn.__name__ or "_"
+        
+        # Check if already traced
+        if hasattr(fn, "_is_traced"):
+            logger.warning(f"Function {fn_name} is already traced, skipping tracing again")
+            return fn
+        
+        is_async = inspect.iscoroutinefunction(fn)
+        
+        if is_async:
+            @wraps(fn)
+            async def async_traced_fn(*args, **kwargs):
+                span = tracer.start_span(fn_name)
+                
+                # Prepare input
+                input_data = _prepare_input(args, kwargs)
+                if filter_input:
+                    input_data = filter_input(input_data)
+                if ignore_input and isinstance(input_data, dict):
+                    # TODO: implement ignore_input logic
+                    pass
+                
+                if input_data is not None:
+                    # Serialize for span attributes (OpenTelemetry only accepts primitives or JSON strings)
+                    serialized_input = _serialize_for_span(input_data)
+                    span.set_attribute("input", serialized_input)
+                
+                try:
+                    # Call the function within the span context
+                    trace_id = format(span.get_span_context().trace_id, "032x")
+                    logger.debug(f"do traceable stuff {fn_name} {trace_id}")
+                    
+                    with trace.use_span(span, end_on_exit=False):
+                        result = await fn(*args, **kwargs)
+                    
+                    # Prepare output
+                    output_data = result
+                    if filter_output:
+                        output_data = filter_output(output_data)
+                    if ignore_output and isinstance(output_data, dict):
+                        # TODO: implement ignore_output logic
+                        pass
+                    
+                    span.set_attribute("output", _serialize_for_span(output_data))
+                    span.set_status(Status(StatusCode.OK))
+                    
+                    return result
+                except Exception as exception:
+                    error = exception if isinstance(exception, Exception) else Exception(str(exception))
+                    span.record_exception(error)
+                    span.set_status(Status(StatusCode.ERROR, str(error)))
+                    raise
+                finally:
+                    span.end()
+            
+            async_traced_fn._is_traced = True
+            logger.debug(f"Function {fn_name} is now traced (async)")
+            return async_traced_fn
+        else:
+            @wraps(fn)
+            def sync_traced_fn(*args, **kwargs):
+                span = tracer.start_span(fn_name)
+                
+                # Prepare input
+                input_data = _prepare_input(args, kwargs)
+                if filter_input:
+                    input_data = filter_input(input_data)
+                if ignore_input and isinstance(input_data, dict):
+                    # TODO: implement ignore_input logic
+                    pass
+                
+                if input_data is not None:
+                    # Serialize for span attributes (OpenTelemetry only accepts primitives or JSON strings)
+                    serialized_input = _serialize_for_span(input_data)
+                    span.set_attribute("input", serialized_input)
+                
+                try:
+                    # Call the function within the span context
+                    trace_id = format(span.get_span_context().trace_id, "032x")
+                    logger.debug(f"do traceable stuff {fn_name} {trace_id}")
+                    
+                    with trace.use_span(span, end_on_exit=False):
+                        result = fn(*args, **kwargs)
+                    
+                    # Prepare output
+                    output_data = result
+                    if filter_output:
+                        output_data = filter_output(output_data)
+                    if ignore_output and isinstance(output_data, dict):
+                        # TODO: implement ignore_output logic
+                        pass
+                    
+                    span.set_attribute("output", _serialize_for_span(output_data))
+                    span.set_status(Status(StatusCode.OK))
+                    
+                    return result
+                except Exception as exception:
+                    error = exception if isinstance(exception, Exception) else Exception(str(exception))
+                    span.record_exception(error)
+                    span.set_status(Status(StatusCode.ERROR, str(error)))
+                    raise
+                finally:
+                    span.end()
+            
+            sync_traced_fn._is_traced = True
+            logger.debug(f"Function {fn_name} is now traced (sync)")
+            return sync_traced_fn
+    
+    # Support both @WithTracing and @WithTracing(...) syntax
+    if func is None:
+        return decorator
+    else:
+        return decorator(func)
+
+
+def set_span_attribute(attribute_name: str, attribute_value: Any) -> bool:
+    """
+    Set an attribute on the active span.
+    
+    Returns:
+        True if attribute was set, False if no active span found
+    """
+    span = trace.get_current_span()
+    if span and span.is_recording():
+        span.set_attribute(attribute_name, _serialize_for_span(attribute_value))
+        return True
+    return False
+
+def set_span_name(span_name: str) -> bool:
+    """
+    Set the name of the active span.
+    """
+    span = trace.get_current_span()
+    if span and span.is_recording():
+        span.set_name(span_name)
+        return True
+    return False
+
+def get_active_span() -> Optional[trace.Span]:
+    """Get the currently active span."""
+    return trace.get_current_span()
+

aiqa_client-0.1.0/aiqa_client.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aiqa-client
+Version: 0.1.0
+Summary: OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server
+Author-email: AIQA <info@aiqa.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/winterstein/aiqa
+Project-URL: Documentation, https://github.com/winterstein/aiqa/tree/main/client-python
+Project-URL: Repository, https://github.com/winterstein/aiqa
+Project-URL: Issues, https://github.com/winterstein/aiqa/issues
+Keywords: opentelemetry,tracing,observability,aiqa,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.40b0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# 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.0/aiqa_client.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+aiqa/__init__.py
+aiqa/aiqa_exporter.py
+aiqa/py.typed
+aiqa/tracing.py
+aiqa_client.egg-info/PKG-INFO
+aiqa_client.egg-info/SOURCES.txt
+aiqa_client.egg-info/dependency_links.txt
+aiqa_client.egg-info/requires.txt
+aiqa_client.egg-info/top_level.txt

aiqa_client-0.1.0/aiqa_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aiqa_client-0.1.0/aiqa_client.egg-info/requires.txt

@@ -0,0 +1,10 @@
+opentelemetry-api>=1.24.0
+opentelemetry-sdk>=1.24.0
+opentelemetry-semantic-conventions>=0.40b0
+aiohttp>=3.9.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+black>=23.0.0
+ruff>=0.1.0

aiqa_client-0.1.0/aiqa_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+aiqa

aiqa_client-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiqa-client"
+version = "0.1.0"
+description = "OpenTelemetry-based Python client for tracing functions and sending traces to the AIQA server"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "AIQA", email = "info@aiqa.dev"}
+]
+keywords = ["opentelemetry", "tracing", "observability", "aiqa", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "opentelemetry-api>=1.24.0",
+    "opentelemetry-sdk>=1.24.0",
+    "opentelemetry-semantic-conventions>=0.40b0",
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/winterstein/aiqa"
+Documentation = "https://github.com/winterstein/aiqa/tree/main/client-python"
+Repository = "https://github.com/winterstein/aiqa"
+Issues = "https://github.com/winterstein/aiqa/issues"
+
+[tool.setuptools]
+packages = ["aiqa"]
+
+[tool.setuptools.package-data]
+aiqa = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+

aiqa_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiqa_client-0.1.0/setup.py

@@ -0,0 +1,9 @@
+"""
+Setup script for aiqa-client (kept for compatibility).
+Use pyproject.toml for modern builds.
+"""
+
+from setuptools import setup
+
+setup()
+