aiqa-client 0.2.1__py3-none-any.whl → 0.3.4__py3-none-any.whl

{aiqa_client-0.2.1.dist-info → aiqa_client-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiqa-client
-Version: 0.2.1
+Version: 0.3.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,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.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+aiqa/__init__.py,sha256=FhkrSi0tVGWTz_KbKCrzEw68qm8Ji6txwOAo6cFZPgE,1563
+aiqa/aiqa_exporter.py,sha256=ZfkIwh8H1mgBZ7fJtM_RhuancCAgcnNuEWsADib4rsc,26806
+aiqa/client.py,sha256=wE6EsypbTfp3Cz39IhEycEVT0IZGdJz7yQvtZ15qKJo,6364
+aiqa/experiment_runner.py,sha256=ZEDwECstAv4lWXpcdB9WSxfDQj43iqkGzB_YzoY933M,12053
+aiqa/object_serialiser.py,sha256=pgcBVw5sZH8f7N6n3-qOvEcbNhuPS5yq7qdhaNT6Sks,15236
+aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiqa/test_experiment_runner.py,sha256=LM8BuCrzBZL0Wyu_ierK0tNLsOUxxMTAHbAGW2G0qp0,5562
+aiqa/test_tracing.py,sha256=mSVrhRQ6Dz5djlSUkCt097sIr84562w6E0BnuQDpMrI,8347
+aiqa/tracing.py,sha256=akilXthvAz8NfJKl3293cHsdJU_P3z4kpdTDfwHipZ0,50014
+aiqa_client-0.3.4.dist-info/licenses/LICENSE,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
+aiqa_client-0.3.4.dist-info/METADATA,sha256=wgrAvEjqMucY0OWU_vK0EI2HYD01uoTicSe4SkeKdqI,6712
+aiqa_client-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aiqa_client-0.3.4.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
+aiqa_client-0.3.4.dist-info/RECORD,,

aiqa_client-0.2.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-aiqa/__init__.py,sha256=Co9t4kYAXI4WKhnTlIhIcQTeJJgFF0mzgmj0yhaS6p4,539
-aiqa/aiqa_exporter.py,sha256=aEXMfdUL2OILt9H4CRkpoi9EgOqr1UthyQFrimZoDFk,19200
-aiqa/client.py,sha256=1QSZhPdpRJilASuS7YtYlzcTNARY0O6lnQB7m2Jm-jA,1421
-aiqa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aiqa/tracing.py,sha256=rtMXbcU13nQYepV-KAP5Sugui8Ox-eQCgksRp3VlwpM,20367
-aiqa_client-0.2.1.dist-info/licenses/LICENSE,sha256=kIzkzLuzG0HHaWYm4F4W5FeJ1Yxut3Ec6bhLWyw798A,1062
-aiqa_client-0.2.1.dist-info/METADATA,sha256=WgHjtG5pmyViDill6UnD3DjzE3mLl_ZLE-rE7x2ECak,3772
-aiqa_client-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aiqa_client-0.2.1.dist-info/top_level.txt,sha256=nwcsuVVSuWu27iLxZd4n1evVzv1W6FVTrSnCXCc-NQs,5
-aiqa_client-0.2.1.dist-info/RECORD,,