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

traccia/auto_instrumentation.py

@@ -1,74 +0,0 @@
-"""Optional auto-instrumentation for user-provided tool functions.
-
-The SDK supports explicit instrumentation via the `@observe` decorator. This
-module provides a best-effort utility for wrapping existing callables by dotted
-path strings.
-
-Accepted include formats:
-- "package.module:function"
-- "package.module.function"
-
-This is intentionally conservative: it mainly targets module-level functions.
-If a target can't be resolved or isn't callable, it's skipped.
-"""
-
-from __future__ import annotations
-
-import importlib
-from typing import Iterable, Optional, Tuple
-
-from traccia.instrumentation.decorator import observe
-from traccia import runtime_config
-
-
-def _split_target(spec: str) -> Optional[Tuple[str, str]]:
-    if not spec:
-        return None
-    if ":" in spec:
-        mod, attr = spec.split(":", 1)
-        return mod.strip(), attr.strip()
-    # Heuristic: last segment is the attribute name; rest is module
-    if "." not in spec:
-        return None
-    mod, attr = spec.rsplit(".", 1)
-    return mod.strip(), attr.strip()
-
-
-def instrument_functions(include: Iterable[str]) -> None:
-    """
-    Wrap and replace functions referenced by include specs.
-
-    This is best-effort and will silently skip invalid entries.
-    """
-    if not runtime_config.get_auto_instrument_tools():
-        return
-
-    for spec in include or []:
-        parsed = _split_target(str(spec))
-        if not parsed:
-            continue
-        module_name, attr_name = parsed
-        try:
-            mod = importlib.import_module(module_name)
-        except Exception:
-            continue
-
-        try:
-            target = getattr(mod, attr_name)
-        except Exception:
-            continue
-        if not callable(target):
-            continue
-
-        # Avoid double wrapping
-        if getattr(target, "_agent_trace_observed", False):
-            continue
-
-        wrapped = observe(name=f"{module_name}.{attr_name}", as_type="tool")(target)
-        setattr(wrapped, "_agent_trace_observed", True)
-        try:
-            setattr(mod, attr_name, wrapped)
-        except Exception:
-            continue
-
-

traccia/cli.py

@@ -1,349 +0,0 @@
-"""CLI for traccia utilities."""
-
-from __future__ import annotations
-
-import argparse
-import os
-import sys
-import urllib.request
-from typing import Optional
-
-from traccia.config import validate_config, load_config, find_config_file, ENV_VAR_MAPPING
-from traccia.errors import ConfigError
-
-
-def _check(args) -> int:
-    """Check connectivity to the configured exporter endpoint."""
-    # Load config to get endpoint
-    try:
-        config = load_config(config_file=args.config if hasattr(args, 'config') else None)
-        endpoint = args.endpoint or config.tracing.endpoint
-        
-        if not endpoint:
-            print("❌ No endpoint configured.", file=sys.stderr)
-            print("   Set endpoint in traccia.toml or use --endpoint flag", file=sys.stderr)
-            return 1
-        
-        print(f"🔍 Checking connectivity to {endpoint}...")
-        sys.stdout.flush()  # Ensure output appears before any errors
-        
-        # Try HEAD request first
-        req = urllib.request.Request(endpoint, method="HEAD")
-        if args.api_key or config.tracing.api_key:
-            api_key = args.api_key or config.tracing.api_key
-            req.add_header("Authorization", f"Bearer {api_key}")
-        
-        try:
-            with urllib.request.urlopen(req, timeout=5) as resp:
-                code = resp.getcode()
-                print(f"✅ Endpoint is reachable (HTTP {code})")
-                print("💡 Connectivity test successful!")
-                return 0
-        except urllib.error.HTTPError as e:
-            # HTTP 405 (Method Not Allowed), 400 (Bad Request), or 401 (Unauthorized) 
-            # means the endpoint is reachable and responding - just doesn't like our test request
-            if e.code in [400, 401, 405]:
-                print(f"✅ Endpoint is reachable (HTTP {e.code})")
-                if e.code == 405:
-                    print("💡 Endpoint only accepts specific methods (expected for OTLP endpoints)")
-                elif e.code == 401:
-                    print("⚠️  Authentication required - check your API key")
-                elif e.code == 400:
-                    print("💡 Endpoint rejected test payload (expected for OTLP endpoints)")
-                print("✅ Connectivity test successful!")
-                return 0
-            else:
-                # Other HTTP errors (404, 500, etc.) are actual failures
-                print(f"❌ HTTP Error {e.code}: {e.reason}", file=sys.stderr)
-                return 1
-                
-    except ConfigError as exc:
-        print(f"❌ Configuration error: {exc}", file=sys.stderr)
-        return 1
-    except urllib.error.URLError as exc:
-        print(f"❌ Connection failed: {exc.reason}", file=sys.stderr)
-        print("   Make sure the endpoint is running and accessible", file=sys.stderr)
-        return 1
-    except Exception as exc:
-        print(f"❌ Unexpected error: {exc}", file=sys.stderr)
-        return 1
-
-
-def _config_init(args) -> int:
-    """Initialize traccia.toml config file in current directory."""
-    config_path = os.path.join(os.getcwd(), "traccia.toml")
-    
-    # Check if file already exists
-    if os.path.exists(config_path) and not args.force:
-        print(f"❌ Config file already exists at {config_path}", file=sys.stderr)
-        print("   Use --force to overwrite", file=sys.stderr)
-        return 1
-    
-    # Create config template with important parameters
-    config_template = """# Traccia SDK Configuration File
-# Documentation: https://github.com/traccia-ai/traccia
-
-[tracing]
-# API key for authentication (required for SaaS, optional for open-source)
-api_key = ""
-
-# Endpoint URL for trace ingestion
-# For local Tempo: endpoint = "http://localhost:4318/v1/traces"
-# For local Jaeger: endpoint = "http://localhost:4318/v1/traces"
-# endpoint = "http://localhost:4318/v1/traces"
-
-# Sampling rate (0.0 to 1.0) - controls what percentage of traces are sent
-sample_rate = 1.0
-
-# Auto-start a root trace on init (default: true)
-auto_start_trace = true
-
-# Name for the auto-started root trace
-auto_trace_name = "root"
-
-# Use OTLP exporter (default: true)
-# Set to false if using console or file exporter
-use_otlp = true
-
-# Service name (optional)
-# service_name = "my-app"
-
-[exporters]
-# IMPORTANT: Only enable ONE exporter at a time (console, file, or OTLP via use_otlp)
-
-# Enable console exporter for local debugging
-enable_console = false
-
-# Enable file exporter to write traces to local file
-enable_file = false
-
-# File path for file exporter (only used if enable_file = true)
-file_exporter_path = "traces.jsonl"
-
-# Reset/clear trace file on initialization
-reset_trace_file = false
-
-[instrumentation]
-# Auto-patch popular libraries (OpenAI, Anthropic, requests)
-enable_patching = true
-
-# Count tokens for LLM calls
-enable_token_counting = true
-
-# Calculate costs for LLM calls
-enable_costs = true
-
-# Auto-instrument tool calls (experimental)
-auto_instrument_tools = false
-
-# Maximum number of tool spans to create
-max_tool_spans = 100
-
-# Maximum depth of nested spans
-max_span_depth = 10
-
-[rate_limiting]
-# Maximum spans per second (uncomment to enable rate limiting)
-# max_spans_per_second = 100.0
-
-# Maximum queue size for buffered spans
-max_queue_size = 5000
-
-# Maximum milliseconds to block before dropping spans
-max_block_ms = 100
-
-# Maximum number of spans in a single export batch
-max_export_batch_size = 512
-
-# Delay in milliseconds between export batches
-schedule_delay_millis = 5000
-
-[runtime]
-# Runtime metadata (optional - can be set per-session)
-# session_id = ""
-# user_id = ""
-# tenant_id = ""
-# project_id = ""
-
-[logging]
-# Enable debug logging
-debug = false
-
-# Enable span-level logging
-enable_span_logging = false
-
-[advanced]
-# Maximum length for attribute values (uncomment to set limit)
-# attr_truncation_limit = 1000
-"""
-    
-    try:
-        with open(config_path, 'w', encoding='utf-8') as f:
-            f.write(config_template)
-        print(f"✅ Created config file at {config_path}")
-        print("\n📝 Next steps:")
-        print("   1. Edit the config file to add your API key and endpoint")
-        print("   2. Run `traccia doctor` to validate your configuration")
-        print("   3. Run `traccia check` to test connectivity")
-        return 0
-    except Exception as exc:
-        print(f"❌ Failed to create config file: {exc}", file=sys.stderr)
-        return 1
-
-
-def _doctor(args) -> int:
-    """Validate configuration and diagnose common issues."""
-    print("🩺 Running Traccia configuration diagnostics...\n")
-    
-    issues_found = 0
-    
-    # 1. Check for config file
-    config_file = None
-    if hasattr(args, 'config') and args.config:
-        config_file = args.config
-        if not os.path.exists(config_file):
-            print(f"❌ Specified config file not found: {config_file}")
-            issues_found += 1
-            return 1
-    else:
-        config_file = find_config_file()
-        if config_file:
-            print(f"✅ Found config file: {config_file}")
-        else:
-            print("⚠️  No config file found (checked ./traccia.toml and ~/.traccia/config.toml)")
-            print("   Run `traccia config init` to create one")
-            issues_found += 1
-    
-    # 2. Check environment variables
-    print("\n📋 Environment variables:")
-    found_env_vars = []
-    for config_key, env_vars in ENV_VAR_MAPPING.items():
-        for env_var in env_vars:
-            if os.getenv(env_var):
-                found_env_vars.append(env_var)
-                print(f"   ✅ {env_var} is set")
-    
-    if not found_env_vars:
-        print("   ℹ️  No Traccia environment variables set")
-    
-    # 3. Validate configuration
-    print("\n🔍 Validating configuration...")
-    is_valid, message, config = validate_config(config_file=config_file)
-    
-    if is_valid:
-        print(f"✅ {message}")
-        
-        # Print configuration summary
-        print("\n📊 Configuration summary:")
-        print(f"   • API Key: {'✅ Set' if config.tracing.api_key else '❌ Not set'}")
-        print(f"   • Endpoint: {config.tracing.endpoint or '❌ Not set'}")
-        print(f"   • Sample Rate: {config.tracing.sample_rate}")
-        print(f"   • OTLP Exporter: {'✅ Enabled' if config.tracing.use_otlp else '❌ Disabled'}")
-        print(f"   • Console Exporter: {'✅ Enabled' if config.exporters.enable_console else '❌ Disabled'}")
-        print(f"   • File Exporter: {'✅ Enabled' if config.exporters.enable_file else '❌ Disabled'}")
-        print(f"   • Auto-patching: {'✅ Enabled' if config.instrumentation.enable_patching else '❌ Disabled'}")
-        
-        # Check for potential issues
-        if config.tracing.use_otlp and not config.tracing.endpoint:
-            print("\n⚠️  Warning: OTLP exporter is enabled but no endpoint is configured")
-            issues_found += 1
-        
-        if not config.tracing.use_otlp and not config.exporters.enable_console and not config.exporters.enable_file:
-            print("\n❌ Error: No exporter is enabled! Traces won't be exported anywhere.")
-            issues_found += 1
-        
-        if config.rate_limiting.max_spans_per_second:
-            print(f"\n   ℹ️  Rate limiting enabled: {config.rate_limiting.max_spans_per_second} spans/sec")
-    else:
-        print(f"❌ {message}")
-        issues_found += 1
-    
-    # 4. Environment variable mapping reference
-    print("\n📖 Environment Variable Reference:")
-    print("   Common variables:")
-    print("   • TRACCIA_API_KEY or AGENT_DASHBOARD_API_KEY")
-    print("   • TRACCIA_ENDPOINT or AGENT_DASHBOARD_ENDPOINT")
-    print("   • TRACCIA_SAMPLE_RATE")
-    print("   • TRACCIA_DEBUG")
-    print("\n   For a complete list, see: ENV_VAR_MAPPING in traccia/config.py")
-    
-    # Summary
-    print("\n" + "="*60)
-    if issues_found == 0:
-        print("✅ No issues found! Your configuration looks good.")
-        print("\n💡 Tip: Run `traccia check` to test connectivity to your endpoint")
-        return 0
-    else:
-        print(f"⚠️  Found {issues_found} issue(s). Please review the messages above.")
-        return 1
-
-
-def main(argv=None) -> int:
-    """Main CLI entry point."""
-    parser = argparse.ArgumentParser(
-        prog="traccia",
-        description="Traccia SDK - Production-ready tracing for AI agents",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  traccia config init              Create a new config file
-  traccia doctor                   Validate configuration
-  traccia check                    Test connectivity to exporter
-  traccia check --endpoint URL     Test specific endpoint
-
-For more information, visit: https://github.com/traccia-ai/traccia
-        """
-    )
-    
-    # Global options
-    parser.add_argument(
-        "--config",
-        help="Path to config file (default: ./traccia.toml or ~/.traccia/config.toml)"
-    )
-    
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    # Check command
-    check = sub.add_parser(
-        "check",
-        help="Verify connectivity to ingest endpoint",
-        description="Test connectivity to the configured exporter endpoint"
-    )
-    check.add_argument("--endpoint", help="Override endpoint URL")
-    check.add_argument("--api-key", help="API key for authentication")
-    check.set_defaults(func=_check)
-
-    # Config command
-    config = sub.add_parser(
-        "config",
-        help="Configuration management",
-        description="Manage Traccia configuration files"
-    )
-    config_sub = config.add_subparsers(dest="config_command", required=True)
-    
-    config_init = config_sub.add_parser(
-        "init",
-        help="Create traccia.toml config file",
-        description="Initialize a new traccia.toml configuration file in the current directory"
-    )
-    config_init.add_argument(
-        "--force",
-        action="store_true",
-        help="Overwrite existing config file"
-    )
-    config_init.set_defaults(func=_config_init)
-    
-    # Doctor command
-    doctor = sub.add_parser(
-        "doctor",
-        help="Validate configuration and diagnose issues",
-        description="Run diagnostics on your Traccia configuration"
-    )
-    doctor.set_defaults(func=_doctor)
-
-    args = parser.parse_args(argv)
-    return args.func(args)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())