timetracer 1.1.0__py3-none-any.whl

timetracer/config.py

@@ -0,0 +1,297 @@
+"""
+TraceConfig - Central configuration for Timetracer.
+
+This is the main configuration object that controls all behavior.
+It can be created programmatically or loaded from environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+
+from timetracer.constants import (
+    CapturePolicy,
+    Defaults,
+    EnvVars,
+    TraceMode,
+)
+from timetracer.exceptions import ConfigurationError
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a boolean from environment variable."""
+    return value.lower() in ("true", "1", "yes", "on")
+
+
+def _parse_csv(value: str) -> list[str]:
+    """Parse a comma-separated list from environment variable."""
+    if not value.strip():
+        return []
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+@dataclass
+class TraceConfig:
+    """
+    Configuration for Timetracer.
+
+    This is the single source of truth for all runtime configuration.
+    Create via constructor or use from_env() to load from environment.
+
+    Priority order:
+    1. Explicit constructor arguments
+    2. Environment variables (via from_env())
+    3. Default values
+
+    Example:
+        # Explicit configuration
+        cfg = TraceConfig(mode=TraceMode.RECORD, cassette_dir="./recordings")
+
+        # Load from environment
+        cfg = TraceConfig.from_env()
+
+        # Mixed: defaults + env overrides
+        cfg = TraceConfig(service_name="my-api").with_env_overrides()
+    """
+
+    # Core settings
+    mode: TraceMode = Defaults.MODE
+    service_name: str = Defaults.SERVICE_NAME
+    env: str = Defaults.ENV
+
+    # Cassette storage
+    cassette_dir: str = Defaults.CASSETTE_DIR
+    cassette_path: str | None = None  # Specific cassette for replay
+
+    # Capture control
+    capture: list[str] = field(default_factory=lambda: ["http"])
+    sample_rate: float = Defaults.SAMPLE_RATE
+    errors_only: bool = Defaults.ERRORS_ONLY
+    exclude_paths: list[str] = field(default_factory=lambda: list(Defaults.EXCLUDE_PATHS))
+
+    # Body capture policies
+    max_body_kb: int = Defaults.MAX_BODY_KB
+    store_request_body: CapturePolicy = Defaults.STORE_REQUEST_BODY
+    store_response_body: CapturePolicy = Defaults.STORE_RESPONSE_BODY
+
+    # Replay settings
+    strict_replay: bool = Defaults.STRICT_REPLAY
+
+    # Hybrid replay - selective mocking
+    # If mock_plugins is empty, all plugins are mocked (default behavior)
+    # If mock_plugins is set, only those plugins are mocked
+    # Plugins in live_plugins are never mocked (kept live)
+    mock_plugins: list[str] = field(default_factory=list)
+    live_plugins: list[str] = field(default_factory=list)
+
+    # Logging
+    log_level: str = Defaults.LOG_LEVEL
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        # Convert string mode to enum if needed
+        if isinstance(self.mode, str):
+            try:
+                self.mode = TraceMode(self.mode.lower())
+            except ValueError:
+                raise ConfigurationError(
+                    f"Invalid mode: {self.mode}. Must be one of: {[m.value for m in TraceMode]}"
+                )
+
+        # Convert string policies to enum if needed
+        if isinstance(self.store_request_body, str):
+            try:
+                self.store_request_body = CapturePolicy(self.store_request_body.lower())
+            except ValueError:
+                raise ConfigurationError(
+                    f"Invalid store_request_body: {self.store_request_body}"
+                )
+
+        if isinstance(self.store_response_body, str):
+            try:
+                self.store_response_body = CapturePolicy(self.store_response_body.lower())
+            except ValueError:
+                raise ConfigurationError(
+                    f"Invalid store_response_body: {self.store_response_body}"
+                )
+
+        # Validate sample_rate
+        if not 0.0 <= self.sample_rate <= 1.0:
+            raise ConfigurationError(
+                f"sample_rate must be between 0.0 and 1.0, got {self.sample_rate}"
+            )
+
+        # Validate max_body_kb
+        if self.max_body_kb < 0:
+            raise ConfigurationError(
+                f"max_body_kb must be non-negative, got {self.max_body_kb}"
+            )
+
+    @classmethod
+    def from_env(cls) -> TraceConfig:
+        """
+        Create configuration from environment variables.
+
+        All TIMETRACER_* environment variables are read and used.
+        Missing variables use defaults.
+        """
+        kwargs: dict = {}
+
+        # Mode
+        if mode := os.environ.get(EnvVars.MODE):
+            kwargs["mode"] = mode
+
+        # Service/env
+        if service := os.environ.get(EnvVars.SERVICE):
+            kwargs["service_name"] = service
+        if env := os.environ.get(EnvVars.ENV):
+            kwargs["env"] = env
+
+        # Cassette paths
+        if cassette_dir := os.environ.get(EnvVars.DIR):
+            kwargs["cassette_dir"] = cassette_dir
+        if cassette_path := os.environ.get(EnvVars.CASSETTE):
+            kwargs["cassette_path"] = cassette_path
+
+        # Capture settings
+        if capture := os.environ.get(EnvVars.CAPTURE):
+            kwargs["capture"] = _parse_csv(capture)
+        if sample_rate := os.environ.get(EnvVars.SAMPLE_RATE):
+            try:
+                kwargs["sample_rate"] = float(sample_rate)
+            except ValueError:
+                raise ConfigurationError(f"Invalid TIMETRACER_SAMPLE_RATE: {sample_rate}")
+        if errors_only := os.environ.get(EnvVars.ERRORS_ONLY):
+            kwargs["errors_only"] = _parse_bool(errors_only)
+        if exclude_paths := os.environ.get(EnvVars.EXCLUDE_PATHS):
+            kwargs["exclude_paths"] = _parse_csv(exclude_paths)
+
+        # Body policies
+        if max_body := os.environ.get(EnvVars.MAX_BODY_KB):
+            try:
+                kwargs["max_body_kb"] = int(max_body)
+            except ValueError:
+                raise ConfigurationError(f"Invalid TIMETRACER_MAX_BODY_KB: {max_body}")
+        if store_req := os.environ.get(EnvVars.STORE_REQ_BODY):
+            kwargs["store_request_body"] = store_req
+        if store_res := os.environ.get(EnvVars.STORE_RES_BODY):
+            kwargs["store_response_body"] = store_res
+
+        # Replay
+        if strict := os.environ.get(EnvVars.STRICT_REPLAY):
+            kwargs["strict_replay"] = _parse_bool(strict)
+
+        # Logging
+        if log_level := os.environ.get(EnvVars.LOG_LEVEL):
+            kwargs["log_level"] = log_level.lower()
+
+        # Hybrid replay
+        if mock_plugins := os.environ.get(EnvVars.MOCK_PLUGINS):
+            kwargs["mock_plugins"] = _parse_csv(mock_plugins)
+        if live_plugins := os.environ.get(EnvVars.LIVE_PLUGINS):
+            kwargs["live_plugins"] = _parse_csv(live_plugins)
+
+        return cls(**kwargs)
+
+    def with_env_overrides(self) -> TraceConfig:
+        """
+        Return a new config with environment variables applied as overrides.
+
+        This allows setting base config in code and overriding via env.
+        """
+        env_config = TraceConfig.from_env()
+
+        # Create new config, preferring env values over current where set
+        return TraceConfig(
+            mode=env_config.mode if os.environ.get(EnvVars.MODE) else self.mode,
+            service_name=env_config.service_name if os.environ.get(EnvVars.SERVICE) else self.service_name,
+            env=env_config.env if os.environ.get(EnvVars.ENV) else self.env,
+            cassette_dir=env_config.cassette_dir if os.environ.get(EnvVars.DIR) else self.cassette_dir,
+            cassette_path=env_config.cassette_path if os.environ.get(EnvVars.CASSETTE) else self.cassette_path,
+            capture=env_config.capture if os.environ.get(EnvVars.CAPTURE) else self.capture,
+            sample_rate=env_config.sample_rate if os.environ.get(EnvVars.SAMPLE_RATE) else self.sample_rate,
+            errors_only=env_config.errors_only if os.environ.get(EnvVars.ERRORS_ONLY) else self.errors_only,
+            exclude_paths=env_config.exclude_paths if os.environ.get(EnvVars.EXCLUDE_PATHS) else self.exclude_paths,
+            max_body_kb=env_config.max_body_kb if os.environ.get(EnvVars.MAX_BODY_KB) else self.max_body_kb,
+            store_request_body=env_config.store_request_body if os.environ.get(EnvVars.STORE_REQ_BODY) else self.store_request_body,
+            store_response_body=env_config.store_response_body if os.environ.get(EnvVars.STORE_RES_BODY) else self.store_response_body,
+            strict_replay=env_config.strict_replay if os.environ.get(EnvVars.STRICT_REPLAY) else self.strict_replay,
+            log_level=env_config.log_level if os.environ.get(EnvVars.LOG_LEVEL) else self.log_level,
+            mock_plugins=env_config.mock_plugins if os.environ.get(EnvVars.MOCK_PLUGINS) else self.mock_plugins,
+            live_plugins=env_config.live_plugins if os.environ.get(EnvVars.LIVE_PLUGINS) else self.live_plugins,
+        )
+
+    def should_trace(self, path: str) -> bool:
+        """
+        Determine if a request path should be traced.
+
+        Returns False for excluded paths.
+        """
+        # Normalize path
+        path = path.split("?")[0]  # Remove query string
+
+        # Check exclusions
+        for excluded in self.exclude_paths:
+            if path == excluded or path.startswith(excluded + "/"):
+                return False
+
+        return True
+
+    def should_sample(self) -> bool:
+        """
+        Determine if this request should be sampled for recording.
+
+        Uses sample_rate for probabilistic sampling.
+        """
+        if self.sample_rate >= 1.0:
+            return True
+        if self.sample_rate <= 0.0:
+            return False
+
+        import random
+        return random.random() < self.sample_rate
+
+    @property
+    def is_record_mode(self) -> bool:
+        """Check if in record mode."""
+        return self.mode == TraceMode.RECORD
+
+    @property
+    def is_replay_mode(self) -> bool:
+        """Check if in replay mode."""
+        return self.mode == TraceMode.REPLAY
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if timetrace is enabled (not OFF)."""
+        return self.mode != TraceMode.OFF
+
+    def get_python_version(self) -> str:
+        """Get current Python version string."""
+        return f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+
+    def should_mock_plugin(self, plugin_name: str) -> bool:
+        """
+        Determine if a plugin should be mocked during replay.
+
+        This enables hybrid replay where some dependencies are mocked
+        and others are kept live (e.g., mock Stripe but keep DB live).
+
+        Args:
+            plugin_name: The name of the plugin (e.g., "http", "db", "redis")
+
+        Returns:
+            True if the plugin should be mocked, False if it should stay live.
+        """
+        # Live plugins are never mocked
+        if self.live_plugins and plugin_name in self.live_plugins:
+            return False
+
+        # If mock_plugins is specified, only those are mocked
+        if self.mock_plugins:
+            return plugin_name in self.mock_plugins
+
+        # Default: mock everything
+        return True

timetracer/constants.py

@@ -0,0 +1,129 @@
+"""
+Centralized constants for Timetracer.
+
+All magic strings, default values, and configuration constants live here.
+This ensures consistency and makes future changes easy.
+"""
+
+from enum import Enum
+from typing import Final
+
+# =============================================================================
+# SCHEMA VERSION - bump this when cassette format changes
+# =============================================================================
+SCHEMA_VERSION: Final[str] = "1.0"
+SUPPORTED_SCHEMA_VERSIONS: Final[tuple[str, ...]] = ("0.1", "1.0")
+
+# =============================================================================
+# MODE CONSTANTS
+# =============================================================================
+class TraceMode(str, Enum):
+    """Operating mode for Timetracer."""
+    OFF = "off"
+    RECORD = "record"
+    REPLAY = "replay"
+
+# =============================================================================
+# BODY CAPTURE POLICY
+# =============================================================================
+class CapturePolicy(str, Enum):
+    """When to capture request/response bodies."""
+    NEVER = "never"
+    ON_ERROR = "on_error"
+    ALWAYS = "always"
+
+# =============================================================================
+# EVENT TYPES - centralized so plugins use consistent naming
+# =============================================================================
+class EventType(str, Enum):
+    """Types of dependency events that can be captured."""
+    HTTP_CLIENT = "http.client"
+    DB_QUERY = "db.query"
+    REDIS = "redis"
+    CUSTOM = "custom"
+
+# =============================================================================
+# DEFAULT VALUES - single source of truth
+# =============================================================================
+class Defaults:
+    """Default configuration values."""
+    MODE: TraceMode = TraceMode.OFF
+    SERVICE_NAME: str = "timetracer-service"
+    ENV: str = "local"
+    CASSETTE_DIR: str = "./cassettes"
+    SAMPLE_RATE: float = 1.0
+    ERRORS_ONLY: bool = False
+    MAX_BODY_KB: int = 64
+    STORE_REQUEST_BODY: CapturePolicy = CapturePolicy.ON_ERROR
+    STORE_RESPONSE_BODY: CapturePolicy = CapturePolicy.ON_ERROR
+    STRICT_REPLAY: bool = True
+    LOG_LEVEL: str = "info"
+    EXCLUDE_PATHS: tuple[str, ...] = ("/health", "/metrics", "/docs", "/openapi.json")
+
+# =============================================================================
+# REDACTION CONSTANTS - headers to always remove
+# =============================================================================
+class Redaction:
+    """Redaction rules."""
+    # Headers that are ALWAYS removed (case-insensitive matching)
+    SENSITIVE_HEADERS: frozenset[str] = frozenset({
+        "authorization",
+        "cookie",
+        "set-cookie",
+        "x-api-key",
+        "x-auth-token",
+        "x-access-token",
+    })
+
+    # Body keys that should be masked (case-insensitive substring matching)
+    SENSITIVE_BODY_KEYS: frozenset[str] = frozenset({
+        "password",
+        "secret",
+        "token",
+        "api_key",
+        "apikey",
+        "access_token",
+        "refresh_token",
+        "private_key",
+        "credit_card",
+        "ssn",
+    })
+
+    # Replacement for redacted values
+    REDACTED_VALUE: str = "[REDACTED]"
+
+# =============================================================================
+# ENVIRONMENT VARIABLE NAMES - consistent prefix
+# =============================================================================
+class EnvVars:
+    """Environment variable names."""
+    PREFIX: str = "TIMETRACER_"
+
+    MODE: str = "TIMETRACER_MODE"
+    SERVICE: str = "TIMETRACER_SERVICE"
+    ENV: str = "TIMETRACER_ENV"
+    DIR: str = "TIMETRACER_DIR"
+    CASSETTE: str = "TIMETRACER_CASSETTE"
+    CAPTURE: str = "TIMETRACER_CAPTURE"
+    SAMPLE_RATE: str = "TIMETRACER_SAMPLE_RATE"
+    ERRORS_ONLY: str = "TIMETRACER_ERRORS_ONLY"
+    EXCLUDE_PATHS: str = "TIMETRACER_EXCLUDE_PATHS"
+    MAX_BODY_KB: str = "TIMETRACER_MAX_BODY_KB"
+    STORE_REQ_BODY: str = "TIMETRACER_STORE_REQ_BODY"
+    STORE_RES_BODY: str = "TIMETRACER_STORE_RES_BODY"
+    STRICT_REPLAY: str = "TIMETRACER_STRICT_REPLAY"
+    LOG_LEVEL: str = "TIMETRACER_LOG_LEVEL"
+    MOCK_PLUGINS: str = "TIMETRACER_MOCK_PLUGINS"
+    LIVE_PLUGINS: str = "TIMETRACER_LIVE_PLUGINS"
+
+# =============================================================================
+# ALLOWED HEADERS - headers we keep (allow-list approach for outbound)
+# =============================================================================
+ALLOWED_HEADERS: frozenset[str] = frozenset({
+    "content-type",
+    "content-length",
+    "accept",
+    "user-agent",
+    "x-request-id",
+    "x-correlation-id",
+})

timetracer/context.py

@@ -0,0 +1,93 @@
+"""
+Context management for Timetracer.
+
+Uses contextvars to provide async-safe, per-request session isolation.
+This ensures concurrent requests don't mix their captured events.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from timetracer.session import BaseSession
+
+
+# The central context variable holding the current session
+# This is the ONLY place where session state is stored
+_current_session: ContextVar[BaseSession | None] = ContextVar(
+    "timetracer_current_session",
+    default=None
+)
+
+
+def get_current_session() -> BaseSession | None:
+    """
+    Get the current trace session, if any.
+
+    Returns None if no session is active (timetrace disabled or outside request).
+    """
+    return _current_session.get()
+
+
+def set_session(session: BaseSession) -> Token[BaseSession | None]:
+    """
+    Set the current trace session.
+
+    Returns a token that must be used to reset the session later.
+    This pattern ensures proper cleanup even with exceptions.
+
+    Usage:
+        token = set_session(my_session)
+        try:
+            # ... do work ...
+        finally:
+            reset_session(token)
+    """
+    return _current_session.set(session)
+
+
+def reset_session(token: Token[BaseSession | None]) -> None:
+    """
+    Reset the session to its previous value using the token.
+
+    This should be called in a finally block to ensure cleanup.
+    """
+    _current_session.reset(token)
+
+
+def clear_session() -> None:
+    """
+    Clear the current session (set to None).
+
+    This is a convenience method; prefer reset_session(token) when possible.
+    """
+    _current_session.set(None)
+
+
+def require_session() -> BaseSession:
+    """
+    Get the current session, raising if none exists.
+
+    Use this in plugins that must have an active session.
+
+    Raises:
+        RuntimeError: If no session is active.
+    """
+    session = _current_session.get()
+    if session is None:
+        raise RuntimeError(
+            "No active Timetracer session. "
+            "Ensure you're inside a traced request and timetrace is enabled."
+        )
+    return session
+
+
+def has_active_session() -> bool:
+    """
+    Check if there's an active trace session.
+
+    Useful for plugins to decide whether to capture events.
+    """
+    return _current_session.get() is not None

timetracer/dashboard/__init__.py

@@ -0,0 +1,14 @@
+"""
+Dashboard module for Timetracer.
+
+Generates an HTML dashboard to browse and filter cassettes.
+"""
+
+from timetracer.dashboard.generator import DashboardData, generate_dashboard
+from timetracer.dashboard.template import render_dashboard_html
+
+__all__ = [
+    "DashboardData",
+    "generate_dashboard",
+    "render_dashboard_html",
+]