Skip to main content

A Python client for the AIQA server

OpenTelemetry-based client for tracing Python functions and sending traces to the AIQA server.

Installation

pip install aiqa-client

From source

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

Development Setup

For development, install with dev dependencies to run tests:

pip install -e ".[dev]"

Then run the unit tests:

pytest

See TESTING.md for detailed testing instructions.

Setup

Set the following environment variables:

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

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

@WithTracing(name="custom_span_name")
def my_function():
    pass

Input/Output Filtering

@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:

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:

from aiqa import flush_tracing
import asyncio

async def main():
    # Your code here
    await flush_tracing()

asyncio.run(main())

Enabling/Disabling Tracing

You can programmatically enable or disable tracing:

from aiqa import get_aiqa_client

client = get_aiqa_client()

# Disable tracing (spans won't be created or exported)
client.enabled = False

# Re-enable tracing
client.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

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:

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 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

from aiqa import get_active_trace_id, get_span_id

# Get the current trace ID and span ID
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.)

Continuing a Trace in Another Service

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

For HTTP requests, use the built-in context propagation:

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.

Metadata

Release files for aiqa-client 0.9.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiqa-client 0.9.2
File Size Uploaded Provenance Actions
aiqa_client-0.9.2.tar.gz 64.1 kB Without provenance Details for aiqa_client-0.9.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiqa-client 0.9.2
File Interpreter ABI Platform Actions
aiqa_client-0.9.2-py3-none-any.whl Python 3 none any Details for aiqa_client-0.9.2-py3-none-any.whl

Total release size: 109.8 kB

Release files / aiqa_client-0.9.2.tar.gz

Download URL aiqa_client-0.9.2.tar.gz
Size 64.1 kB
Tags Source
SHA-256 checksum
How to use checksums
dfeb4afbee1bc448b24145319c8c016026617edb5e39851e75428dbe727fae70
BLAKE2b-256 checksum
How to use checksums
4540e39b1791569948b9821026033e8d962036e3819414f4867a1d1b54a4eaf8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Release files / aiqa_client-0.9.2-py3-none-any.whl

Download URL aiqa_client-0.9.2-py3-none-any.whl
Size 45.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03e2c711d139da7481c2a06675bbcaeb6c74db668c3f8db87fd09bfe58fb51a6
BLAKE2b-256 checksum
How to use checksums
70a0a3df5e73133bec8cc3deba946c36567b857489d193b62a28e60694319c22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Security for aiqa-client 0.9.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page