pisama-claude-code 0.3.7__tar.gz → 0.4.2__tar.gz

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-01-05
+
+### Added
+- **OpenTelemetry export** - Export traces to any OTEL-compatible backend
+  - `export-otel` command for direct export to OTEL collectors (Jaeger, Honeycomb, Datadog)
+  - `export --format otel` for OTEL JSON file export
+  - GenAI semantic conventions for token usage and model attributes
+  - Optional `[otel]` dependency: `pip install pisama-claude-code[otel]`
+
+### Changed
+- Updated description to reflect role in broader PISAMA platform
+
 ## [0.3.5] - 2025-01-05
 
 ### Fixed
@@ -91,7 +103,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for Bash, Read, Write, Edit, Grep, Glob tools
 - Local storage in `~/.claude/pisama/traces/`
 
-[Unreleased]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.3.5...HEAD
+[Unreleased]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.3.5...v0.4.0
 [0.3.5]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/tn-pisama/pisama-claude-code/compare/v0.3.2...v0.3.3

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pisama-claude-code
-Version: 0.3.7
+Version: 0.4.2
 Summary: Trace capture for Claude Code sessions - sync to PISAMA platform for analysis
 Project-URL: Homepage, https://pisama.dev
 Project-URL: Documentation, https://pisama.dev/docs/claude-code
@@ -36,6 +36,9 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: all
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
 Requires-Dist: pisama-core>=0.1.0; extra == 'all'
 Provides-Extra: core
 Requires-Dist: pisama-core>=0.1.0; extra == 'core'
@@ -43,6 +46,10 @@ Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
 Description-Content-Type: text/markdown
 
 # pisama-claude-code
@@ -163,10 +170,34 @@ pisama-cc export -o traces.jsonl
 # Export compressed
 pisama-cc export -o traces.jsonl.gz --compress
 
+# Export to OpenTelemetry format
+pisama-cc export --format otel -o traces-otel.json
+
 # Filter by date range
 pisama-cc traces --since 2025-01-01 --until 2025-01-04
 ```
 
+### OpenTelemetry Integration
+
+Export traces to any OTEL-compatible backend (Jaeger, Honeycomb, Datadog, etc.):
+
+```bash
+# Install OTEL support
+pip install pisama-claude-code[otel]
+
+# Export to local Jaeger
+pisama-cc export-otel -e http://localhost:4318/v1/traces
+
+# Export to Honeycomb
+pisama-cc export-otel -e https://api.honeycomb.io/v1/traces \
+    -H "x-honeycomb-team=YOUR_API_KEY"
+
+# Export to file in OTEL format
+pisama-cc export --format otel -o traces.json
+```
+
+OTEL export uses [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for token usage, costs, and model attributes.
+
 ## CLI Reference
 
 | Command | Description |
@@ -174,12 +205,14 @@ pisama-cc traces --since 2025-01-01 --until 2025-01-04
 | `pisama-cc install` | Install capture hooks to `~/.claude/hooks/` |
 | `pisama-cc uninstall` | Remove hooks |
 | `pisama-cc status` | Show status, token totals, and cost |
-| `pisama-cc traces` | View recent traces (`-v` for verbose) |
+| `pisama-cc traces` | View recent traces (`-v` for verbose, `-c` for content) |
 | `pisama-cc usage` | Token usage breakdown (`--by-model`, `--by-tool`) |
-| `pisama-cc export` | Export to JSONL (`-o FILE`, `--compress`) |
+| `pisama-cc export` | Export to JSONL or OTEL (`--format otel`, `--compress`) |
+| `pisama-cc export-otel` | Export to OpenTelemetry collector (`-e ENDPOINT`) |
 | `pisama-cc connect` | Connect to PISAMA platform (optional) |
 | `pisama-cc sync` | Upload traces to platform |
 | `pisama-cc analyze` | Run failure detection (requires platform) |
+| `pisama-cc vault status` | Show PII tokenization vault status |
 
 ## Model Pricing
 
@@ -240,6 +273,20 @@ Platform features:
 - Self-healing automation
 - Visual dashboard
 
+## Part of the PISAMA Platform
+
+`pisama-claude-code` is the Claude Code integration for the broader **PISAMA (Platform for Intelligent Self-healing AI Multi-Agent) Testing Platform**, which supports multiple agent frameworks:
+
+| Framework | Package | Status |
+|-----------|---------|--------|
+| Claude Code | `pisama-claude-code` | Stable |
+| LangChain/LangGraph | `mao-testing` SDK | Available |
+| CrewAI | `mao-testing` SDK | Available |
+| AutoGen | `mao-testing` SDK | Available |
+| n8n | `mao-testing` SDK | Available |
+
+For other frameworks, see the [mao-testing SDK](https://github.com/tn-pisama/mao-testing).
+
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/README.md

@@ -116,10 +116,34 @@ pisama-cc export -o traces.jsonl
 # Export compressed
 pisama-cc export -o traces.jsonl.gz --compress
 
+# Export to OpenTelemetry format
+pisama-cc export --format otel -o traces-otel.json
+
 # Filter by date range
 pisama-cc traces --since 2025-01-01 --until 2025-01-04
 ```
 
+### OpenTelemetry Integration
+
+Export traces to any OTEL-compatible backend (Jaeger, Honeycomb, Datadog, etc.):
+
+```bash
+# Install OTEL support
+pip install pisama-claude-code[otel]
+
+# Export to local Jaeger
+pisama-cc export-otel -e http://localhost:4318/v1/traces
+
+# Export to Honeycomb
+pisama-cc export-otel -e https://api.honeycomb.io/v1/traces \
+    -H "x-honeycomb-team=YOUR_API_KEY"
+
+# Export to file in OTEL format
+pisama-cc export --format otel -o traces.json
+```
+
+OTEL export uses [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for token usage, costs, and model attributes.
+
 ## CLI Reference
 
 | Command | Description |
@@ -127,12 +151,14 @@ pisama-cc traces --since 2025-01-01 --until 2025-01-04
 | `pisama-cc install` | Install capture hooks to `~/.claude/hooks/` |
 | `pisama-cc uninstall` | Remove hooks |
 | `pisama-cc status` | Show status, token totals, and cost |
-| `pisama-cc traces` | View recent traces (`-v` for verbose) |
+| `pisama-cc traces` | View recent traces (`-v` for verbose, `-c` for content) |
 | `pisama-cc usage` | Token usage breakdown (`--by-model`, `--by-tool`) |
-| `pisama-cc export` | Export to JSONL (`-o FILE`, `--compress`) |
+| `pisama-cc export` | Export to JSONL or OTEL (`--format otel`, `--compress`) |
+| `pisama-cc export-otel` | Export to OpenTelemetry collector (`-e ENDPOINT`) |
 | `pisama-cc connect` | Connect to PISAMA platform (optional) |
 | `pisama-cc sync` | Upload traces to platform |
 | `pisama-cc analyze` | Run failure detection (requires platform) |
+| `pisama-cc vault status` | Show PII tokenization vault status |
 
 ## Model Pricing
 
@@ -193,6 +219,20 @@ Platform features:
 - Self-healing automation
 - Visual dashboard
 
+## Part of the PISAMA Platform
+
+`pisama-claude-code` is the Claude Code integration for the broader **PISAMA (Platform for Intelligent Self-healing AI Multi-Agent) Testing Platform**, which supports multiple agent frameworks:
+
+| Framework | Package | Status |
+|-----------|---------|--------|
+| Claude Code | `pisama-claude-code` | Stable |
+| LangChain/LangGraph | `mao-testing` SDK | Available |
+| CrewAI | `mao-testing` SDK | Available |
+| AutoGen | `mao-testing` SDK | Available |
+| n8n | `mao-testing` SDK | Available |
+
+For other frameworks, see the [mao-testing SDK](https://github.com/tn-pisama/mao-testing).
+
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pisama-claude-code"
-version = "0.3.7"
+version = "0.4.2"
 description = "Trace capture for Claude Code sessions - sync to PISAMA platform for analysis"
 readme = "README.md"
 license = "MIT"
@@ -62,13 +62,18 @@ dependencies = [
 core = [
     "pisama-core>=0.1.0",
 ]
+otel = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
 ]
 all = [
-    "pisama-claude-code[core]",
+    "pisama-claude-code[core,otel]",
 ]
 
 [project.scripts]

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/src/pisama_claude_code/__init__.py

@@ -1,6 +1,6 @@
 """PISAMA Claude Code Integration - Trace capture, failure detection, and self-healing."""
 
-__version__ = "0.3.5"
+__version__ = "0.4.0"
 
 # Lazy imports to avoid loading everything at startup
 def install(force: bool = False):

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/src/pisama_claude_code/cli.py

@@ -4,15 +4,20 @@ Command-line interface for capturing Claude Code traces and syncing
 to the PISAMA platform for analysis and self-healing.
 
 Usage:
-    pisama-cc install     Install hooks to ~/.claude/
-    pisama-cc uninstall   Remove hooks
-    pisama-cc status      Show current status (incl. token/cost totals)
-    pisama-cc traces      View recent traces (-v for token usage)
-    pisama-cc usage       Show token usage and cost breakdown
-    pisama-cc export      Export traces to file
-    pisama-cc connect     Connect to PISAMA platform
-    pisama-cc sync        Sync traces to platform
-    pisama-cc analyze     Analyze traces (requires platform)
+    pisama-cc install      Install hooks to ~/.claude/
+    pisama-cc uninstall    Remove hooks
+    pisama-cc status       Show current status (incl. token/cost totals)
+    pisama-cc traces       View recent traces (-v for token usage)
+    pisama-cc usage        Show token usage and cost breakdown
+    pisama-cc export       Export traces to file (JSONL or OTEL format)
+    pisama-cc export-otel  Export traces to OpenTelemetry collector
+    pisama-cc connect      Connect to PISAMA platform
+    pisama-cc sync         Sync traces to platform
+    pisama-cc analyze      Analyze traces (requires platform)
+
+OTEL Export:
+    pisama-cc export --format otel -o traces.json
+    pisama-cc export-otel -e http://localhost:4318/v1/traces
 """
 
 import click
@@ -53,7 +58,7 @@ def save_config(config: dict):
 
 
 @click.group()
-@click.version_option(version="0.3.6")
+@click.version_option(version="0.4.0")
 def main():
     """PISAMA Claude Code - Trace capture and sync."""
     pass
@@ -69,13 +74,6 @@ def install(force: bool):
     from pisama_claude_code.install import install as do_install
     do_install(force=force)
 
-    # Star reminder after install
-    click.echo("")
-    click.echo("=" * 50)
-    click.echo("If pisama-claude-code is useful, please star us!")
-    click.echo(f"   {GITHUB_URL}")
-    click.echo("=" * 50)
-
 
 @main.command()
 def uninstall():
@@ -515,15 +513,29 @@ def usage(last: int, by_model: bool, by_tool: bool):
 @click.option("--last", default=50, help="Number of traces to export")
 @click.option("--output", "-o", default="traces-export.jsonl", help="Output file")
 @click.option("--compress", is_flag=True, help="Gzip compress output")
-def export(last: int, output: str, compress: bool):
-    """Export traces to a file."""
+@click.option("--format", "fmt", type=click.Choice(["jsonl", "otel"]), default="jsonl", help="Export format")
+def export(last: int, output: str, compress: bool, fmt: str):
+    """Export traces to a file (JSONL or OTEL format)."""
     traces_list = load_recent_traces(last)
 
     if not traces_list:
         click.echo("No traces to export")
         return
 
-    # Prepare export (redact sensitive data)
+    # Handle OTEL format
+    if fmt == "otel":
+        from pisama_claude_code.otel_export import export_to_otel_file
+
+        # Adjust default output for OTEL
+        if output == "traces-export.jsonl":
+            output = "traces-export-otel.json"
+
+        result = export_to_otel_file(traces_list, output)
+        click.echo(f"✅ Exported {result['spans_created']} spans to {output} (OTEL format)")
+        click.echo(f"   Sessions: {result['sessions_exported']}")
+        return
+
+    # Prepare JSONL export (redact sensitive data)
     export_data = []
     for t in traces_list:
         clean = {
@@ -572,6 +584,69 @@ def export(last: int, output: str, compress: bool):
     click.echo(f"✅ Exported {len(export_data)} traces to {output_path} ({size_kb} KB)")
 
 
+@main.command("export-otel")
+@click.option("--last", default=50, help="Number of traces to export")
+@click.option("--endpoint", "-e", required=True, help="OTEL collector endpoint (e.g., http://localhost:4318/v1/traces)")
+@click.option("--service-name", "-s", default="claude-code", help="Service name for spans")
+@click.option("--header", "-H", multiple=True, help="Header in 'key=value' format (can be repeated)")
+def export_otel(last: int, endpoint: str, service_name: str, header: tuple):
+    """Export traces to an OpenTelemetry collector.
+
+    Examples:
+
+      # Local Jaeger
+      pisama-cc export-otel -e http://localhost:4318/v1/traces
+
+      # Honeycomb
+      pisama-cc export-otel -e https://api.honeycomb.io/v1/traces \\
+          -H "x-honeycomb-team=YOUR_API_KEY"
+
+      # Datadog (via OTEL collector)
+      pisama-cc export-otel -e http://localhost:4318/v1/traces \\
+          -s my-claude-agent
+    """
+    from pisama_claude_code.otel_export import is_otel_available, export_traces_to_otel
+
+    if not is_otel_available():
+        click.echo("❌ OpenTelemetry not installed")
+        click.echo("   Run: pip install pisama-claude-code[otel]")
+        return
+
+    traces_list = load_recent_traces(last)
+
+    if not traces_list:
+        click.echo("No traces to export")
+        return
+
+    # Parse headers
+    headers = {}
+    for h in header:
+        if "=" in h:
+            key, value = h.split("=", 1)
+            headers[key.strip()] = value.strip()
+
+    click.echo(f"📤 Exporting {len(traces_list)} traces to OTEL collector...")
+    click.echo(f"   Endpoint: {endpoint}")
+    click.echo(f"   Service: {service_name}")
+
+    try:
+        result = export_traces_to_otel(
+            traces=traces_list,
+            endpoint=endpoint,
+            service_name=service_name,
+            headers=headers if headers else None,
+        )
+
+        if result["success"]:
+            click.echo(f"✅ Exported {result['spans_created']} spans")
+            click.echo(f"   Sessions: {result['sessions_exported']}")
+            click.echo(f"   Traces: {result['traces_processed']}")
+        else:
+            click.echo("❌ Export failed")
+    except Exception as e:
+        click.echo(f"❌ Export failed: {e}")
+
+
 # Helper functions
 
 def normalize_trace(t: dict) -> dict:

{pisama_claude_code-0.3.7 → pisama_claude_code-0.4.2}/src/pisama_claude_code/install.py

@@ -74,6 +74,9 @@ def install(force: bool = False):
     print("\nNext steps:")
     print("  1. Add hooks to settings.local.json (see above)")
     print("  2. Run 'pisama-cc connect --api-key <key>' to enable analysis")
+    print("\n" + "─" * 50)
+    print("⭐ If this tool saves you time/money, consider starring:")
+    print("   https://github.com/tn-pisama/pisama-claude-code")
 
 
 def _install_shell_hooks(hooks_dir: Path, force: bool):

pisama_claude_code-0.4.2/src/pisama_claude_code/otel_export.py

@@ -0,0 +1,287 @@
+"""OpenTelemetry export for pisama-claude-code traces.
+
+Converts Claude Code traces to OpenTelemetry spans and exports them
+to any OTEL-compatible backend (Jaeger, Honeycomb, Datadog, etc.).
+"""
+
+from __future__ import annotations
+import json
+import time
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+# Lazy imports for OTEL
+_otel_available = None
+
+
+def is_otel_available() -> bool:
+    """Check if OpenTelemetry is installed."""
+    global _otel_available
+    if _otel_available is None:
+        try:
+            import opentelemetry  # noqa: F401
+            _otel_available = True
+        except ImportError:
+            _otel_available = False
+    return _otel_available
+
+
+def export_traces_to_otel(
+    traces: List[Dict[str, Any]],
+    endpoint: str,
+    service_name: str = "claude-code",
+    headers: Optional[Dict[str, str]] = None,
+) -> Dict[str, Any]:
+    """Export traces to an OTEL endpoint.
+
+    Args:
+        traces: List of normalized trace dicts from pisama-claude-code
+        endpoint: OTEL collector endpoint (e.g., http://localhost:4318/v1/traces)
+        service_name: Service name for the spans
+        headers: Optional headers (e.g., for authentication)
+
+    Returns:
+        Dict with export status and statistics
+    """
+    if not is_otel_available():
+        raise ImportError(
+            "OpenTelemetry not installed. Run: pip install pisama-claude-code[otel]"
+        )
+
+    from opentelemetry import trace as otel_trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.trace import SpanKind, Status, StatusCode
+
+    # Set up resource
+    resource = Resource.create({
+        "service.name": service_name,
+        "service.version": "0.3.7",
+        "telemetry.sdk.name": "pisama-claude-code",
+    })
+
+    # Create provider and exporter
+    provider = TracerProvider(resource=resource)
+    exporter = OTLPSpanExporter(
+        endpoint=endpoint,
+        headers=headers or {},
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    otel_trace.set_tracer_provider(provider)
+
+    tracer = otel_trace.get_tracer("pisama-claude-code")
+
+    # Group traces by session
+    sessions: Dict[str, List[Dict]] = {}
+    for t in traces:
+        session_id = t.get("session_id", "unknown")
+        if session_id not in sessions:
+            sessions[session_id] = []
+        sessions[session_id].append(t)
+
+    spans_created = 0
+
+    # Create spans for each session
+    for session_id, session_traces in sessions.items():
+        # Sort by timestamp
+        session_traces.sort(key=lambda x: x.get("timestamp", ""))
+
+        # Create parent span for session
+        session_start = _parse_timestamp(session_traces[0].get("timestamp"))
+        session_end = _parse_timestamp(session_traces[-1].get("timestamp"))
+
+        with tracer.start_span(
+            name=f"claude-code-session:{session_id}",
+            kind=SpanKind.INTERNAL,
+            start_time=session_start,
+        ) as session_span:
+            session_span.set_attribute("session.id", session_id)
+            session_span.set_attribute("session.trace_count", len(session_traces))
+
+            # Calculate session totals
+            total_input = sum(t.get("input_tokens", 0) for t in session_traces)
+            total_output = sum(t.get("output_tokens", 0) for t in session_traces)
+            total_cost = sum(t.get("cost_usd", 0) for t in session_traces)
+
+            session_span.set_attribute("session.input_tokens", total_input)
+            session_span.set_attribute("session.output_tokens", total_output)
+            session_span.set_attribute("session.cost_usd", total_cost)
+
+            spans_created += 1
+
+            # Create child spans for each tool call
+            for t in session_traces:
+                span_start = _parse_timestamp(t.get("timestamp"))
+                tool_name = t.get("tool_name", "unknown")
+                hook_type = t.get("hook_type", "")
+
+                with tracer.start_span(
+                    name=f"{tool_name}:{hook_type}",
+                    kind=SpanKind.INTERNAL,
+                    start_time=span_start,
+                ) as span:
+                    # Standard attributes
+                    span.set_attribute("tool.name", tool_name)
+                    span.set_attribute("hook.type", hook_type)
+                    span.set_attribute("session.id", session_id)
+
+                    # Model and token usage (GenAI semantic conventions)
+                    if t.get("model"):
+                        span.set_attribute("gen_ai.system", "anthropic")
+                        span.set_attribute("gen_ai.request.model", t["model"])
+
+                    if t.get("input_tokens"):
+                        span.set_attribute("gen_ai.usage.input_tokens", t["input_tokens"])
+                    if t.get("output_tokens"):
+                        span.set_attribute("gen_ai.usage.output_tokens", t["output_tokens"])
+                    if t.get("cache_read_tokens"):
+                        span.set_attribute("gen_ai.usage.cache_read_tokens", t["cache_read_tokens"])
+                    if t.get("cost_usd"):
+                        span.set_attribute("gen_ai.usage.cost_usd", t["cost_usd"])
+
+                    # Content attributes (if captured)
+                    if t.get("user_input"):
+                        span.set_attribute("gen_ai.prompt", _truncate(t["user_input"], 4096))
+                    if t.get("reasoning"):
+                        span.set_attribute("gen_ai.reasoning", _truncate(t["reasoning"], 4096))
+                    if t.get("ai_output"):
+                        span.set_attribute("gen_ai.completion", _truncate(t["ai_output"], 4096))
+
+                    # Tool input (sanitized)
+                    tool_input = t.get("tool_input")
+                    if tool_input:
+                        try:
+                            span.set_attribute("tool.input", json.dumps(tool_input)[:2048])
+                        except (TypeError, ValueError):
+                            pass
+
+                    # Working directory
+                    if t.get("working_dir"):
+                        span.set_attribute("tool.working_dir", t["working_dir"])
+
+                    spans_created += 1
+
+    # Force flush and shutdown
+    provider.force_flush()
+    provider.shutdown()
+
+    return {
+        "success": True,
+        "endpoint": endpoint,
+        "service_name": service_name,
+        "sessions_exported": len(sessions),
+        "spans_created": spans_created,
+        "traces_processed": len(traces),
+    }
+
+
+def convert_trace_to_otel_dict(trace: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert a single trace to OTEL span format (dict).
+
+    Useful for exporting to file in OTEL-compatible format.
+    """
+    timestamp_ns = _parse_timestamp(trace.get("timestamp"))
+
+    return {
+        "name": f"{trace.get('tool_name', 'unknown')}:{trace.get('hook_type', '')}",
+        "kind": "SPAN_KIND_INTERNAL",
+        "startTimeUnixNano": timestamp_ns,
+        "endTimeUnixNano": timestamp_ns + 1_000_000,  # +1ms
+        "attributes": [
+            {"key": "tool.name", "value": {"stringValue": trace.get("tool_name", "")}},
+            {"key": "hook.type", "value": {"stringValue": trace.get("hook_type", "")}},
+            {"key": "session.id", "value": {"stringValue": trace.get("session_id", "")}},
+            {"key": "gen_ai.system", "value": {"stringValue": "anthropic"}},
+            {"key": "gen_ai.request.model", "value": {"stringValue": trace.get("model", "")}},
+            {"key": "gen_ai.usage.input_tokens", "value": {"intValue": trace.get("input_tokens", 0)}},
+            {"key": "gen_ai.usage.output_tokens", "value": {"intValue": trace.get("output_tokens", 0)}},
+        ],
+        "traceId": _generate_trace_id(trace.get("session_id", "")),
+        "spanId": _generate_span_id(trace.get("timestamp", "")),
+    }
+
+
+def export_to_otel_file(
+    traces: List[Dict[str, Any]],
+    output_path: str,
+    service_name: str = "claude-code",
+) -> Dict[str, Any]:
+    """Export traces to an OTEL-compatible JSON file.
+
+    The output format follows the OTLP JSON schema.
+    """
+    resource_spans = []
+
+    # Group by session
+    sessions: Dict[str, List[Dict]] = {}
+    for t in traces:
+        session_id = t.get("session_id", "unknown")
+        if session_id not in sessions:
+            sessions[session_id] = []
+        sessions[session_id].append(t)
+
+    for session_id, session_traces in sessions.items():
+        spans = [convert_trace_to_otel_dict(t) for t in session_traces]
+
+        resource_spans.append({
+            "resource": {
+                "attributes": [
+                    {"key": "service.name", "value": {"stringValue": service_name}},
+                    {"key": "session.id", "value": {"stringValue": session_id}},
+                ]
+            },
+            "scopeSpans": [
+                {
+                    "scope": {"name": "pisama-claude-code"},
+                    "spans": spans,
+                }
+            ]
+        })
+
+    otel_payload = {"resourceSpans": resource_spans}
+
+    with open(output_path, "w") as f:
+        json.dump(otel_payload, f, indent=2)
+
+    return {
+        "success": True,
+        "output_path": output_path,
+        "sessions_exported": len(sessions),
+        "spans_created": sum(len(s) for s in sessions.values()),
+    }
+
+
+def _parse_timestamp(ts: Optional[str]) -> int:
+    """Parse timestamp string to nanoseconds since epoch."""
+    if not ts:
+        return time.time_ns()
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        return int(dt.timestamp() * 1_000_000_000)
+    except (ValueError, TypeError):
+        return time.time_ns()
+
+
+def _truncate(text: str, max_len: int) -> str:
+    """Truncate text to max length."""
+    if not text:
+        return ""
+    if len(text) > max_len:
+        return text[:max_len - 3] + "..."
+    return text
+
+
+def _generate_trace_id(session_id: str) -> str:
+    """Generate a 32-char hex trace ID from session ID."""
+    import hashlib
+    h = hashlib.sha256(session_id.encode()).hexdigest()
+    return h[:32]
+
+
+def _generate_span_id(identifier: str) -> str:
+    """Generate a 16-char hex span ID."""
+    import hashlib
+    h = hashlib.sha256(identifier.encode()).hexdigest()
+    return h[:16]