feat: add W3C traceparent propagation for distributed tracing (#36)

* feat: add W3C traceparent propagation for distributed tracing

- Add _tracing.py module with traceparent generation helpers
- Cursor generates session trace_id, shared across new() children
- LouieClient._get_headers() injects traceparent into all HTTP requests
- Priority: OTel context > session trace > none
- Add opentelemetry-api to dev deps for type checking
- Add unit tests for tracing functionality

Closes #35

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add distributed tracing section to architecture docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: update changelog for v0.7.0 release

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: lmeyerov

.secrets.baseline

@@ -96,7 +96,7 @@
     },
     {
       "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
-      "min_level": 3
+      "min_level": 2
     },
     {
       "path": "detect_secrets.filters.heuristic.is_indirect_reference"
@@ -133,5 +133,5 @@
     }
   ],
   "results": {},
-  "generated_at": "2025-09-23T23:57:52Z"
+  "generated_at": "2026-01-16T23:24:34Z"
 }

CHANGELOG.md

@@ -13,6 +13,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - None.
 
+## [0.7.0] - 2026-01-16
+
+### Added
+- **Distributed tracing**: W3C `traceparent` propagation for correlating requests with OpenTelemetry
+  - Automatic OTel context propagation when available
+  - Session-level trace ID for correlation when OTel is not configured
+  - `Cursor.new()` children inherit parent trace ID for session-wide correlation
+  - Zero configuration required - works automatically
+
+### Changed
+- `LouieClient._get_headers()` now accepts `session_trace_id` and `traceparent` parameters
+- All HTTP methods (`add_cell`, `upload_*`, streaming) propagate trace context
+
 ## [0.6.2] - 2025-12-22
 
 ### Added

docs/developer/architecture.md

@@ -129,4 +129,31 @@ User Query → Agent Selection → LouieAI API → Agent Processing → Structur
 - IPython.display integration for rich output
 - Real-time streaming with progressive updates
 - Automatic dataframe and visualization rendering
-- History management with indexed access (`lui[-1]`, `lui[-2]`, etc.)
+- History management with indexed access (`lui[-1]`, `lui[-2]`, etc.)
+
+### Distributed Tracing (OpenTelemetry)
+
+LouieAI automatically propagates W3C `traceparent` headers for distributed tracing:
+
+**With OpenTelemetry configured:**
+```python
+# Your existing OTel span context is automatically propagated
+with tracer.start_as_current_span("my_analysis"):
+    lui("analyze data")  # Request includes your trace context
+```
+
+**Without OpenTelemetry:**
+```python
+# Session-level trace ID generated automatically for correlation
+lui = louieai.Cursor()
+lui("query 1")  # All requests share a session trace_id
+lui("query 2")  # Same trace_id, different span_id
+
+child = lui.new()
+child("query 3")  # Same session trace_id (inherited)
+```
+
+This enables:
+- Linking client requests to server-side traces in Tempo, Jaeger, etc.
+- Correlating all prompts within a Cursor session
+- No configuration required - works automatically

pyproject.toml

@@ -55,7 +55,8 @@ dev = [
   "mkdocs-jupyter>=0.24.0",
   "nbclient>=0.10.2",
   "python-dotenv>=1.0.0",
-  "ipython>=8.0.0"
+  "ipython>=8.0.0",
+  "opentelemetry-api>=1.0.0",  # For type checking OTel integration
 ]
 docs = [
   "mkdocs>=1.6.0",
@@ -143,6 +144,10 @@ ignore_missing_imports = true
 module = "IPython.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "opentelemetry.*"
+ignore_missing_imports = true
+
 # Ignore mypy issues in test files for complex mocking
 [[tool.mypy.overrides]]
 module = "tests.*"

src/louieai/_client.py

@@ -18,6 +18,7 @@
     collect_table_ai_kwargs,
     normalize_table_ai_overrides,
 )
+from ._tracing import get_traceparent
 from .auth import AuthManager, auto_retry_auth
 
 logger = logging.getLogger(__name__)
@@ -368,8 +369,21 @@ def _fetch_dataframe_arrow(
             logger.debug("Full error details: ", exc_info=True)
             return None
 
-    def _get_headers(self) -> dict[str, str]:
-        """Get authorization headers using auth manager."""
+    def _get_headers(
+        self, session_trace_id: str | None = None, traceparent: str | None = None
+    ) -> dict[str, str]:
+        """Get authorization headers using auth manager.
+
+        Args:
+            session_trace_id: Optional session trace ID for correlation when
+                OTel is not available. Used to generate traceparent if no
+                explicit traceparent is provided and OTel is not active.
+            traceparent: Optional explicit traceparent header value. If provided,
+                takes precedence over auto-generated values.
+
+        Returns:
+            Headers dict with Authorization and optionally traceparent.
+        """
         token = self._auth_manager.get_token()
         headers = {"Authorization": f"Bearer {token}"}
 
@@ -383,6 +397,15 @@ def _get_headers(self) -> dict[str, str]:
                 org_slug = self._to_slug(str(org_name))
                 headers["X-Graphistry-Org"] = org_slug
 
+        # Add traceparent for distributed tracing
+        # Priority: explicit traceparent > OTel context > session trace
+        if traceparent:
+            headers["traceparent"] = traceparent
+        else:
+            tp = get_traceparent(session_trace_id)
+            if tp:
+                headers["traceparent"] = tp
+
         return headers
 
     def _to_slug(self, text: str) -> str:
@@ -619,6 +642,7 @@ def add_cell(
         share_mode: str = "Private",
         table_ai_overrides: TableAIOverrides | Mapping[str, Any] | None = None,
         use_batch: bool | None = None,
+        session_trace_id: str | None = None,
         **legacy_overrides: Any,
     ) -> Response:
         """Add a cell (query) to a thread and get response.
@@ -634,13 +658,15 @@ def add_cell(
             table_ai_overrides: Structured overrides via dataclass or mapping.
             use_batch: Force singleshot (`True`) or streaming (`False`); defaults to
                 singleshot when overrides are provided.
+            session_trace_id: Optional session trace ID for distributed tracing
+                correlation when OpenTelemetry is not available.
             **legacy_overrides: Backwards-compatible Table AI keyword arguments like
                 ``table_ai_semantic_mode``. Prefer `table_ai_overrides`.
 
         Returns:
             Response object containing thread_id and all elements
         """
-        headers = self._get_headers()
+        headers = self._get_headers(session_trace_id=session_trace_id)
 
         # Build query parameters
         params: dict[str, Any] = {
@@ -940,6 +966,7 @@ def upload_dataframe(
         name: str | None = None,
         folder: str | None = None,
         parsing_options: dict[str, Any] | None = None,
+        session_trace_id: str | None = None,
     ) -> Response:
         """Upload a DataFrame with a natural language query for AI analysis.
 
@@ -954,6 +981,8 @@ def upload_dataframe(
             name: Optional thread name
             folder: Optional folder path for the thread (server support required)
             parsing_options: Format-specific parsing options
+            session_trace_id: Optional session trace ID for distributed tracing
+                correlation when OpenTelemetry is not available.
 
         Returns:
             Response object with analysis results
@@ -975,6 +1004,7 @@ def upload_dataframe(
             name=name,
             folder=folder,
             parsing_options=parsing_options,
+            session_trace_id=session_trace_id,
         )
 
     def upload_image(
@@ -988,6 +1018,7 @@ def upload_image(
         share_mode: str = "Private",
         name: str | None = None,
         folder: str | None = None,
+        session_trace_id: str | None = None,
     ) -> Response:
         """Upload an image with a natural language query for analysis.
 
@@ -1000,6 +1031,8 @@ def upload_image(
             share_mode: Visibility setting
             name: Optional thread name
             folder: Optional folder path for the thread (server support required)
+            session_trace_id: Optional session trace ID for distributed tracing
+                correlation when OpenTelemetry is not available.
 
         Returns:
             Response object with analysis results
@@ -1018,6 +1051,7 @@ def upload_image(
             share_mode=share_mode,
             name=name,
             folder=folder,
+            session_trace_id=session_trace_id,
         )
 
     def upload_binary(
@@ -1032,6 +1066,7 @@ def upload_binary(
         name: str | None = None,
         folder: str | None = None,
         filename: str | None = None,
+        session_trace_id: str | None = None,
     ) -> Response:
         """Upload a binary file with a natural language query for analysis.
 
@@ -1045,6 +1080,8 @@ def upload_binary(
             name: Optional thread name
             folder: Optional folder path for the thread (server support required)
             filename: Optional filename to use
+            session_trace_id: Optional session trace ID for distributed tracing
+                correlation when OpenTelemetry is not available.
 
         Returns:
             Response object with analysis results
@@ -1064,6 +1101,7 @@ def upload_binary(
             name=name,
             folder=folder,
             filename=filename,
+            session_trace_id=session_trace_id,
         )
 
     def __enter__(self):

src/louieai/_tracing.py

@@ -0,0 +1,100 @@
+"""W3C Traceparent propagation for distributed tracing.
+
+This module provides traceparent header generation for correlating
+louie-py requests with distributed traces. It supports:
+
+1. OpenTelemetry integration: If OTel is configured with an active span,
+   the current trace context is automatically propagated.
+
+2. Session-level correlation: When OTel is not available, a session
+   trace_id is used to correlate all requests from a Cursor instance.
+
+The traceparent header follows the W3C Trace Context specification:
+https://www.w3.org/TR/trace-context/
+"""
+
+from __future__ import annotations
+
+import secrets
+
+
+def generate_trace_id() -> str:
+    """Generate a random 32-character hex trace ID."""
+    return secrets.token_hex(16)
+
+
+def generate_span_id() -> str:
+    """Generate a random 16-character hex span ID."""
+    return secrets.token_hex(8)
+
+
+def build_traceparent(trace_id: str, span_id: str, sampled: bool = True) -> str:
+    """Build a W3C traceparent header value.
+
+    Format: {version}-{trace_id}-{span_id}-{trace_flags}
+    Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+
+    Args:
+        trace_id: 32-character hex trace ID
+        span_id: 16-character hex span ID
+        sampled: Whether the trace is sampled (default True)
+
+    Returns:
+        W3C traceparent header value
+    """
+    flags = "01" if sampled else "00"
+    return f"00-{trace_id}-{span_id}-{flags}"
+
+
+def inject_otel_traceparent(headers: dict[str, str]) -> bool:
+    """Inject traceparent from OpenTelemetry context if available.
+
+    Uses the standard OTel propagate.inject() mechanism which handles
+    W3C Trace Context, baggage, and any configured propagators.
+
+    Args:
+        headers: Dict to inject traceparent into (modified in place)
+
+    Returns:
+        True if OTel context was injected, False otherwise
+    """
+    try:
+        from opentelemetry.propagate import inject
+        from opentelemetry.trace import INVALID_SPAN, get_current_span
+
+        span = get_current_span()
+        if span == INVALID_SPAN or not span.is_recording():
+            return False
+
+        inject(headers)
+        return True
+    except ImportError:
+        return False
+
+
+def get_traceparent(session_trace_id: str | None = None) -> str | None:
+    """Get traceparent header value for an outgoing request.
+
+    Priority:
+    1. Active OTel span context (if available)
+    2. Session trace_id with new span_id (if provided)
+    3. None (no tracing)
+
+    Args:
+        session_trace_id: Optional session-level trace ID for correlation
+            when OTel is not available
+
+    Returns:
+        traceparent header value or None
+    """
+    # Try OTel first
+    headers: dict[str, str] = {}
+    if inject_otel_traceparent(headers):
+        return headers.get("traceparent")
+
+    # Fallback to session trace
+    if session_trace_id:
+        span_id = generate_span_id()
+        return build_traceparent(session_trace_id, span_id)
+
+    return None

src/louieai/_upload.py

@@ -50,6 +50,7 @@ def upload_dataframe(
         folder: str | None = None,
         parsing_options: dict[str, Any] | None = None,
         table_ai_overrides: TableAIOverrides | Mapping[str, Any] | None = None,
+        session_trace_id: str | None = None,
         **legacy_overrides: Any,
     ) -> Response:
         """Upload a DataFrame with a natural language query for analysis.
@@ -106,8 +107,8 @@ def upload_dataframe(
             ...     thread_id=response.thread_id
             ... )
         """
-        # Get headers with auth
-        headers = self._client._get_headers()
+        # Get headers with auth and tracing
+        headers = self._client._get_headers(session_trace_id=session_trace_id)
 
         # Serialize DataFrame to specified format
         file_data, filename, content_type = self._serialize_dataframe(df, format)
@@ -334,6 +335,7 @@ def upload_image(
         share_mode: str = "Private",
         name: str | None = None,
         folder: str | None = None,
+        session_trace_id: str | None = None,
     ) -> Response:
         """Upload an image with a natural language query for analysis.
 
@@ -375,8 +377,8 @@ def upload_image(
             ...     img_bytes = f.read()
             >>> response = client.upload_image("Extract text", img_bytes)
         """
-        # Get headers with auth
-        headers = self._client._get_headers()
+        # Get headers with auth and tracing
+        headers = self._client._get_headers(session_trace_id=session_trace_id)
 
         # Serialize image
         file_data, filename, content_type = self._serialize_image(image)
@@ -601,6 +603,7 @@ def upload_binary(
         name: str | None = None,
         folder: str | None = None,
         filename: str | None = None,
+        session_trace_id: str | None = None,
     ) -> Response:
         """Upload a binary file with a natural language query for analysis.
 
@@ -641,8 +644,8 @@ def upload_binary(
             ...     file_bytes = f.read()
             >>> response = client.upload_binary("Key points from this doc", file_bytes)
         """
-        # Get headers with auth
-        headers = self._client._get_headers()
+        # Get headers with auth and tracing
+        headers = self._client._get_headers(session_trace_id=session_trace_id)
 
         # Serialize binary file
         file_data, file_name, content_type = self._serialize_binary(file, filename)