traccia 0.1.2__py3-none-any.whl → 0.1.6__py3-none-any.whl

traccia/utils/__init__.py

@@ -0,0 +1,19 @@
+"""Utility functions for Traccia SDK."""
+
+from traccia.utils.helpers import (
+    get_duration_ns,
+    get_parent_span_id,
+    format_trace_id,
+    format_span_id,
+    parse_trace_id,
+    parse_span_id,
+)
+
+__all__ = [
+    "get_duration_ns",
+    "get_parent_span_id",
+    "format_trace_id",
+    "format_span_id",
+    "parse_trace_id",
+    "parse_span_id",
+]

traccia/utils/helpers.py

@@ -0,0 +1,95 @@
+"""Helper functions for OpenTelemetry compatibility."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from opentelemetry.trace import Span as OTelSpan
+
+
+def get_duration_ns(span: OTelSpan) -> Optional[int]:
+    """
+    Get span duration in nanoseconds.
+    
+    Args:
+        span: OpenTelemetry Span instance
+    
+    Returns:
+        Duration in nanoseconds, or None if span hasn't ended
+    """
+    if span.end_time is None:
+        return None
+    return span.end_time - span.start_time
+
+
+def get_parent_span_id(span: OTelSpan) -> Optional[int]:
+    """
+    Get parent span ID from span context.
+    
+    Args:
+        span: OpenTelemetry Span instance
+    
+    Returns:
+        Parent span ID (int64), or None if no parent
+    """
+    # OTel doesn't expose parent_span_id directly
+    # We need to get it from the span's parent context if available
+    # For now, return None - parent relationship is maintained via context
+    # This can be enhanced if needed by tracking parent during span creation
+    return None
+
+
+def format_trace_id(trace_id: int) -> str:
+    """
+    Format OTel trace_id (int64) to hex string.
+    
+    Args:
+        trace_id: OTel trace_id as int64
+    
+    Returns:
+        32-character hex string
+    """
+    return format(trace_id, '032x')
+
+
+def format_span_id(span_id: int) -> str:
+    """
+    Format OTel span_id (int64) to hex string.
+    
+    Args:
+        span_id: OTel span_id as int64
+    
+    Returns:
+        16-character hex string
+    """
+    return format(span_id, '016x')
+
+
+def parse_trace_id(hex_string: str) -> int:
+    """
+    Parse hex string trace_id to OTel int64.
+    
+    Args:
+        hex_string: 32-character hex string
+    
+    Returns:
+        OTel trace_id as int64
+    """
+    if not hex_string:
+        return 0
+    return int(hex_string, 16)
+
+
+def parse_span_id(hex_string: str) -> int:
+    """
+    Parse hex string span_id to OTel int64.
+    
+    Args:
+        hex_string: 16-character hex string
+    
+    Returns:
+        OTel span_id as int64
+    """
+    if not hex_string:
+        return 0
+    return int(hex_string, 16)

{traccia-0.1.2.dist-info → traccia-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traccia
-Version: 0.1.2
+Version: 0.1.6
 Summary: Production-ready distributed tracing SDK for AI agents and LLM applications
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/traccia-ai/traccia
@@ -32,6 +32,8 @@ Requires-Dist: opentelemetry-semantic-conventions>=0.40b0
 Requires-Dist: tomli>=2.0.0; python_version < "3.11"
 Requires-Dist: toml>=0.10.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
 Dynamic: license-file
 
 # Traccia
@@ -43,6 +45,7 @@ Traccia is a lightweight, high-performance Python SDK for observability and trac
 ## ✨ Features
 
 - **🔍 Automatic Instrumentation**: Auto-patch OpenAI, Anthropic, requests, and HTTP libraries
+- **🤖 Framework Integrations**: Support for LangChain and OpenAI Agents SDK
 - **📊 LLM-Aware Tracing**: Track tokens, costs, prompts, and completions automatically
 - **⚡ Zero-Config Start**: Simple `init()` call with automatic config discovery
 - **🎯 Decorator-Based**: Trace any function with `@observe` decorator
@@ -101,6 +104,59 @@ def generate_text(prompt: str) -> str:
 text = generate_text("Write a haiku about Python")
 ```
 
+### LangChain
+
+Create a callback handler and pass it to `config={"callbacks": [traccia_handler]}`. Install the optional extra: `pip install traccia[langchain]`.
+
+```python
+from traccia import init
+from traccia.integrations.langchain import CallbackHandler  # or TracciaCallbackHandler
+from langchain_openai import ChatOpenAI
+
+init()
+
+# Create Traccia handler (no args)
+traccia_handler = CallbackHandler()
+
+# Use with any LangChain runnable
+llm = ChatOpenAI(model="gpt-4o-mini")
+result = llm.invoke(
+    "Tell me a joke",
+    config={"callbacks": [traccia_handler]}
+)
+```
+
+Spans for LLM/chat model runs are created automatically with the same attributes as direct OpenAI instrumentation (model, prompt, usage, cost).
+
+**Note:** `pip install traccia[langchain]` installs traccia plus `langchain-core`; you need this extra to use the callback handler. If you already have `langchain-core` (e.g. from `langchain` or `langchain-openai`), base `pip install traccia` may be enough at runtime, but `traccia[langchain]` is the supported way to get a compatible dependency.
+
+### OpenAI Agents SDK
+
+Traccia **automatically** detects and instruments the OpenAI Agents SDK when installed. No extra code needed:
+
+```python
+from traccia import init
+from agents import Agent, Runner
+
+init()  # Automatically enables Agents SDK tracing
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant"
+)
+result = Runner.run_sync(agent, "Write a haiku about recursion")
+```
+
+**Configuration**: Auto-enabled by default when `openai-agents` is installed. To disable:
+
+```python
+init(openai_agents=False)  # Explicit parameter
+# OR set environment variable: TRACCIA_OPENAI_AGENTS=false
+# OR in traccia.toml under [instrumentation]: openai_agents = false
+```
+
+**Compatibility**: If you have `openai-agents` installed but don't use it (e.g., using LangChain or pure OpenAI instead), the integration is registered but never invoked—no overhead or extra spans.
+
 ---
 
 ## 📖 Configuration
@@ -141,6 +197,7 @@ reset_trace_file = false      # Reset file on initialization
 enable_patching = true          # Auto-patch libraries (OpenAI, Anthropic, requests)
 enable_token_counting = true    # Count tokens for LLM calls
 enable_costs = true             # Calculate costs
+openai_agents = true            # Auto-enable OpenAI Agents SDK integration
 auto_instrument_tools = false   # Auto-instrument tool calls (experimental)
 max_tool_spans = 100            # Max tool spans to create
 max_span_depth = 10             # Max nested span depth
@@ -470,18 +527,6 @@ init(debug=True)
 - Increase `max_queue_size` if spans are queued
 - Check `traccia doctor` output
 
-#### **Import errors after upgrade**
-
-If you're migrating from `traccia_sdk`:
-
-```python
-# OLD (will raise helpful error)
-from traccia_sdk import init  # ❌ ImportError with migration guide
-
-# NEW
-from traccia import init  # ✅ Correct
-```
-
 ---
 
 ## 📚 API Reference
@@ -537,13 +582,14 @@ Create a span context manager.
 
 ### Decorator
 
-#### `@observe(name=None, *, attributes=None, as_type="span", skip_args=None, skip_result=False)`
+#### `@observe(name=None, *, attributes=None, tags=None, as_type="span", skip_args=None, skip_result=False)`
 
 Decorate a function to create spans automatically.
 
 **Parameters**:
 - `name` (str, optional): Span name (default: function name)
 - `attributes` (dict, optional): Initial attributes
+- `tags` (list[str], optional): User-defined identifiers for the observed method
 - `as_type` (str): Span type (`"span"`, `"llm"`, `"tool"`)
 - `skip_args` (list, optional): Arguments to skip capturing
 - `skip_result` (bool): Skip capturing return value
@@ -590,6 +636,17 @@ Application Code (@observe)
    Backend (Grafana Tempo / Jaeger / Zipkin / etc.)
 ```
 
+### Instrumentation vs Integrations
+
+- **`traccia.instrumentation.*`**: Infrastructure and vendor instrumentation.
+  - HTTP client/server helpers (including FastAPI middleware).
+  - Vendor SDK hooks and monkey patching (e.g., OpenAI, Anthropic, `requests`).
+  - Decorators and utilities used for auto-instrumenting arbitrary functions.
+
+- **`traccia.integrations.*`**: AI/agent framework integrations.
+  - Adapters that plug into higher-level frameworks via their official extension points (e.g., LangChain callbacks).
+  - Work at the level of chains, tools, agents, and workflows rather than raw HTTP or SDK calls.
+
 ---
 
 ## 🤝 Contributing
@@ -649,7 +706,7 @@ pytest traccia/tests/ --cov=traccia --cov-report=html
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details
+Apache License 2.0 - see [LICENSE](LICENSE) for full terms and conditions.
 
 ---
 

traccia-0.1.6.dist-info/RECORD

@@ -0,0 +1,55 @@
+traccia/__init__.py,sha256=O2Hs3GFVcFsmeBlJwJhqPvFH9kB-pAJarEfB9G4xLZU,1998
+traccia/auto.py,sha256=zr4zTMIPEn7epm1KO8APzpdzuaYroeW_ZKB8L41AFXk,26302
+traccia/auto_instrumentation.py,sha256=e2Gzt2AtGSXbv6BSZpAApAtMcTlEwc08dgZgQMfrREU,2107
+traccia/cli.py,sha256=lQJU-dAxxcWyOew7OCBi2u7RbMXcwOxtLyfzFwlZ4f0,12362
+traccia/config.py,sha256=BByH9VOjjXKHLeJlWXXEA2Vlq3k9AqriNggdrlUrff0,24798
+traccia/errors.py,sha256=CMIS01M3pnr3oRhtzQkyKYkDgYkJNlGd6D9Zg2AohA0,1158
+traccia/pricing_config.py,sha256=ZTccshJbAySWJw9Rdvpj2SMaHkEio325t8NkfJfNzfY,1732
+traccia/runtime_config.py,sha256=c6Cto1pQjKy4Jb6pSClQrgzQRv8flZrePNpK1wxbx3s,2735
+traccia/context/__init__.py,sha256=_tNDOoVZ3GgbYtw9I3F8YSKuPovQBa0orjtd7CtfI1w,738
+traccia/context/context.py,sha256=hBvsrYV_-2cHCC7jTH5iGKHzxZRGpMH2vc0oTW2cqAY,1967
+traccia/context/propagators.py,sha256=Tq3O-JYEBqkshrrhGYn-j_2V718gfLiFDaVzsDdVmms,8747
+traccia/exporter/__init__.py,sha256=4Gh7X6XoccGpiIErIZGvDPpT8qzl91wwqJzDhc9gi3Q,360
+traccia/exporter/console_exporter.py,sha256=IKR9S_DJbOqB7aRaDHGtl7GlDiV3GLHTh7I9Anmj7Ao,873
+traccia/exporter/file_exporter.py,sha256=4TcHvhCs6yGCfU-HKVtA8oKjnlzlSfGiI0TMTdVvdsc,6922
+traccia/exporter/http_exporter.py,sha256=kLcDn0WoFbSc6pAawj_-MNqOASGMEiFKki-Y3FeieKU,8039
+traccia/exporter/otlp_exporter.py,sha256=sy74xOgKyLofG_S9QHTuQo4HB4LaKnVVWKYv1cHRZx0,7692
+traccia/instrumentation/__init__.py,sha256=kOs72xJCraJknhDAtbxgiVNUgwI-efAGGFB3tXJsRhI,967
+traccia/instrumentation/anthropic.py,sha256=R4vL1plLHgt0TXkDwt1Priic9HppIp2Oyt11IJZZ9Ug,3444
+traccia/instrumentation/decorator.py,sha256=BTZvtFpNA2MVuNkoMbbZtgVK_c_su1M3V1OIuBoTEl0,10049
+traccia/instrumentation/fastapi.py,sha256=LpenJ5aIrcTTWZb6_6GsQ_6cXrVMDjdfeyfQeGvDUTs,1271
+traccia/instrumentation/http_client.py,sha256=fBZx2RNcMxH73cmTrDjlQVYxerBUKQnw8OANyfak5HE,586
+traccia/instrumentation/http_server.py,sha256=RTMklczBEam8PE-pPVMUWBo8YtU7_ISa6-G0Zqjbptk,913
+traccia/instrumentation/openai.py,sha256=nItQnjpq3GXNfM1VE3DIt2YIHRlg5e495KtvpQjFjFs,14862
+traccia/instrumentation/requests.py,sha256=I7Oc_px9RDtliQ2ktQVymPUc2Zkaz1NdepxWQygMb24,2267
+traccia/integrations/__init__.py,sha256=bkLPf2DyX7c6-_p12aKgdgsM9EOyF2EZ7y2-jNjxDzw,1150
+traccia/integrations/langchain/__init__.py,sha256=98umBkI8DePI4eUJBZtBUgjMsmaUNF2EfMPK2bWH3iM,524
+traccia/integrations/langchain/callback.py,sha256=xwHVMKRa6TduLm2bU4NNuDvK2AySQsmnQWWqA8whYOQ,14771
+traccia/integrations/langchain/utils.py,sha256=TjkEUKprTL2CfkSjVG4jSO0fLk_n3wvTgxv5NN_wHeI,4258
+traccia/integrations/openai_agents/__init__.py,sha256=bFxSf5rvnKzl87Ux8MkFylUYY0vagil3cTTrb0HeNeg,2028
+traccia/integrations/openai_agents/processor.py,sha256=DpwSISq9R3dUiS0so95T7bSCLwcRnG8IcsiXCsRg_fY,10450
+traccia/processors/__init__.py,sha256=-hwG9SXM6JbGJaIol2KnS3aWwr9P_TVbJ4AZtGTe2zY,1192
+traccia/processors/agent_enricher.py,sha256=Ur1QvqXSCWT9RgZQw6s53P6URfGmH0KsC7WRJlCYRew,6434
+traccia/processors/batch_processor.py,sha256=JTZzWQs5jXlIiqI7PqukfrHil3V81ZC4tRsqeGYv_v8,4832
+traccia/processors/cost_engine.py,sha256=nMbGwRqWdsOEyIYGdjsX_Srww8f3rxMMDmdUlLqBZn8,2391
+traccia/processors/cost_processor.py,sha256=pJO4NOhWwEOCfSS5zYAR-5qufBjfLcnINObhzkjgdZw,2469
+traccia/processors/drop_policy.py,sha256=dxRiLt79ox4_7DFVMxt_Y0zOIOEV8AQirl8vq_jaVU0,1164
+traccia/processors/logging_processor.py,sha256=2BzTz7_jGF3uVOWc_B-BM3Ab8nyU3crLOt5pcXshgSg,921
+traccia/processors/rate_limiter.py,sha256=PycOYVyiVA4xFEXewOgqiw-rxzFhXu4b9Zw0RdywXck,7878
+traccia/processors/sampler.py,sha256=_jKSRVlt94Bg317j8rfRtt5sdLuCaoI8v9IkgpaEiVs,548
+traccia/processors/token_counter.py,sha256=o91y9nFVFnfRNKcTywNshcEuh8FzXPVH3WOd3Kzpgbs,7676
+traccia/tracer/__init__.py,sha256=VI-EQcz5NtPWV07BJbqPi-DSL-1f81G3y22ngdLidjA,375
+traccia/tracer/otel_adapter.py,sha256=X-1DEeyeHnCJNNqGOldLEpHosz-rjs3jsg49AVTOskw,21006
+traccia/tracer/otel_utils.py,sha256=94HZV1GgeC07w7qWhK3Vu5uzAqiL3LV8yZHOsd5CACM,807
+traccia/tracer/provider.py,sha256=MlQUt_sk0hHEyKBVmv-g9XG9GIEWnwvtGoFBsQcTmxA,5180
+traccia/tracer/span.py,sha256=6SFZDa9HM0SIAznpdIoC9ym_naSPCkipQgthsfSJYLU,9446
+traccia/tracer/span_context.py,sha256=Y6J5Rr6bu-WG2-K2tyncLyyjdAK74b3fbSpIkLOQorg,356
+traccia/tracer/tracer.py,sha256=oxXJnkR95-UnQeVhdtOOW7q0iAqWf_M9YmvCEcvRhkg,9496
+traccia/utils/__init__.py,sha256=JelSlN-M6Sv8y_MLpYAz_kBUguBnxFSuzvhg4eFIdpg,357
+traccia/utils/helpers.py,sha256=yhihp2Jw2TLTPxffGee5nE8nRcZ5C2aWgyLHKZek3Cc,2107
+traccia-0.1.6.dist-info/licenses/LICENSE,sha256=HNl57LOj88EfKh-IWmeqWxsDRh_FF6lj0l-E2A4Hr8w,10757
+traccia-0.1.6.dist-info/METADATA,sha256=IJnHGuC2bOBkvx0YdRIpwNWndQOg7x8AgJS2afj1Aj0,20676
+traccia-0.1.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+traccia-0.1.6.dist-info/entry_points.txt,sha256=SG7gacPRmFzLw2HYTblUZsmC_TO3n14-dNi28SL-C2k,45
+traccia-0.1.6.dist-info/top_level.txt,sha256=Kc56JudupqSkzJPOnuQ6mPHJmhtike7pssNX0u_p59w,8
+traccia-0.1.6.dist-info/RECORD,,

traccia-0.1.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+traccia

traccia-0.1.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-traccia-0.1.2.dist-info/licenses/LICENSE,sha256=HNl57LOj88EfKh-IWmeqWxsDRh_FF6lj0l-E2A4Hr8w,10757
-traccia-0.1.2.dist-info/METADATA,sha256=LNuwcEuYE5OCjPFHV-VvLzoND4KR5_BNYbBuDD6jI_k,17986
-traccia-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-traccia-0.1.2.dist-info/entry_points.txt,sha256=SG7gacPRmFzLw2HYTblUZsmC_TO3n14-dNi28SL-C2k,45
-traccia-0.1.2.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-traccia-0.1.2.dist-info/RECORD,,

traccia-0.1.2.dist-info/top_level.txt

@@ -1 +0,0 @@
-