progress-observability 1.1.4__py3-none-any.whl

progress/observability/__init__.py

@@ -0,0 +1,22 @@
+"""
+Progress Observability - Zero-intrusion AI agent telemetry
+
+Provides granular control over AI agent tracing with zero code changes required
+to existing agent implementations.
+"""
+
+from .sdk import Observability
+from .decorators import task, workflow, agent, tool
+from .enums import ObservabilityInstruments
+from .constants import OBSERVABILITY_ENV_VARS
+from .helpers import clear_sdk_env_vars
+
+__all__ = [
+    'Observability',
+    'ObservabilityInstruments',
+    'OBSERVABILITY_ENV_VARS',
+    'task', 
+    'workflow',
+    'agent',
+    'tool',
+]

progress/observability/constants.py

@@ -0,0 +1,31 @@
+"""
+Constants for Progress Observability Instrumentation
+
+Contains environment variables and configuration constants used by the
+Progress Observability instrumentation system.
+"""
+
+# Traceloop SDK environment variables that should be cleared to prevent conflicts
+SDK_ENV_VARS = [
+    "TRACELOOP_TELEMETRY",
+    "TRACELOOP_BASE_URL", 
+    "TRACELOOP_API_KEY",
+    "TRACELOOP_HEADERS",
+    "TRACELOOP_METRICS_ENDPOINT",
+    "TRACELOOP_METRICS_HEADERS",
+    "TRACELOOP_LOGGING_ENDPOINT", 
+    "TRACELOOP_LOGGING_HEADERS"
+]
+
+# Observability environment variables
+OBSERVABILITY_ENV_VARS = [
+    "OBSERVABILITY_API_KEY",
+    "OBSERVABILITY_ENDPOINT",
+    "OBSERVABILITY_APP_NAME",
+    "OBSERVABILITY_TRACE_CONTENT"
+]
+
+# Default configuration values
+DEFAULTS = {
+    "ENDPOINT": "https://collector.observability.progress.com:443"
+}

progress/observability/decorators.py

@@ -0,0 +1,288 @@
+"""
+Progress Observability Decorators - Unified telemetry decorators for AI agents
+
+Provides convenient decorators for instrumenting agent functions, workflows,
+tasks, and tools with Progress Observability telemetry.
+"""
+
+import functools
+import inspect
+from typing import Optional, TypeVar, Callable, Awaitable, Union, Dict, Any
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+
+class ObservabilitySpanKind:
+    """
+    Observability span kind values for distinguishing different operation types.
+
+    These custom span kinds complement OpenTelemetry standard semantic conventions
+    to provide domain-specific categorization for AI agent operations.
+    """
+    TASK = "task"
+    WORKFLOW = "workflow"
+    AGENT = "agent"
+    TOOL = "tool"
+
+
+R = TypeVar("R")
+F = TypeVar("F", bound=Callable[..., Union[R, Awaitable[R]]])
+
+# Get tracer instance
+tracer = trace.get_tracer("progress.observability")
+
+
+def _create_span_wrapper(
+    func: F,
+    span_name: Optional[str],
+    span_kind: str,
+    version: Optional[int],
+    additional_attributes: Optional[Dict[str, Any]] = None,
+) -> F:
+    """
+    Create a span wrapper for a function with OpenTelemetry standard semantic conventions.
+
+    Args:
+        func: Function to wrap
+        span_name: Name for the span (if None, derived from function)
+        span_kind: Observability span kind value
+        version: Optional version number
+        additional_attributes: Optional additional attributes to add
+
+    Returns:
+        Wrapped function with telemetry
+    """
+    # Get function name and namespace
+    func_name = func.__name__
+    namespace = None
+
+    # Try to get class name if this is a method
+    if hasattr(func, '__qualname__') and '.' in func.__qualname__:
+        parts = func.__qualname__.rsplit('.', 1)
+        if len(parts) == 2:
+            namespace = parts[0]
+
+    # Determine span name
+    if span_name is None:
+        span_name = f"{namespace}.{func_name}" if namespace else func_name
+
+    # Build base attributes using OpenTelemetry standard semantic conventions
+    base_attributes = {
+        'code.function': func_name,
+        'observability.span.kind': span_kind,
+    }
+
+    if namespace:
+        base_attributes['code.namespace'] = namespace
+
+    if version is not None:
+        base_attributes['service.version'] = str(version)
+
+    if additional_attributes:
+        base_attributes.update(additional_attributes)
+
+    # Handle async functions
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            with tracer.start_as_current_span(
+                span_name,
+                kind=SpanKind.INTERNAL,
+                attributes=base_attributes,
+            ) as span:
+                try:
+                    result = await func(*args, **kwargs)
+                    span.set_status(Status(StatusCode.OK))
+                    return result
+                except Exception as e:
+                    span.set_status(Status(StatusCode.ERROR, str(e)))
+                    span.record_exception(e)
+                    raise
+        return async_wrapper  # type: ignore
+
+    # Handle sync functions
+    @functools.wraps(func)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        with tracer.start_as_current_span(
+            span_name,
+            kind=SpanKind.INTERNAL,
+            attributes=base_attributes,
+        ) as span:
+            try:
+                result = func(*args, **kwargs)
+                span.set_status(Status(StatusCode.OK))
+                return result
+            except Exception as e:
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                span.record_exception(e)
+                raise
+    return sync_wrapper  # type: ignore
+
+
+def task(
+    name: Optional[str] = None,
+    version: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for instrumenting task functions with Progress Observability telemetry.
+
+    Uses OpenTelemetry standard semantic conventions for attributes:
+    - code.function: Function name
+    - code.namespace: Class name (if method)
+    - service.version: Version number
+    - observability.span.kind: Set to "task"
+
+    Args:
+        name: Optional name override for the task span
+        version: Optional version number for the task
+        attributes: Optional additional attributes to add to the span
+
+    Returns:
+        Decorated function with telemetry instrumentation
+
+    Examples:
+        @task()
+        def my_task():
+            pass
+
+        @task(name="custom_task", version=1)
+        async def async_task():
+            pass
+    """
+    def decorator(func: F) -> F:
+        return _create_span_wrapper(
+            func,
+            name,
+            ObservabilitySpanKind.TASK,
+            version,
+            attributes,
+        )
+    return decorator
+
+
+def workflow(
+    name: Optional[str] = None,
+    version: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for instrumenting workflow functions with Progress Observability telemetry.
+
+    Uses OpenTelemetry standard semantic conventions for attributes:
+    - code.function: Function name
+    - code.namespace: Class name (if method)
+    - service.version: Version number
+    - observability.span.kind: Set to "workflow"
+
+    Args:
+        name: Optional name override for the workflow span
+        version: Optional version number for the workflow
+        attributes: Optional additional attributes to add to the span
+
+    Returns:
+        Decorated function with telemetry instrumentation
+
+    Examples:
+        @workflow()
+        def my_workflow():
+            pass
+
+        @workflow(name="data_processing", version=2)
+        async def process_data():
+            pass
+    """
+    def decorator(func: F) -> F:
+        return _create_span_wrapper(
+            func,
+            name,
+            ObservabilitySpanKind.WORKFLOW,
+            version,
+            attributes,
+        )
+    return decorator
+
+
+def agent(
+    name: Optional[str] = None,
+    version: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for instrumenting agent functions with Progress Observability telemetry.
+
+    Uses OpenTelemetry standard semantic conventions for attributes:
+    - code.function: Function name
+    - code.namespace: Class name (if method)
+    - service.version: Version number
+    - observability.span.kind: Set to "agent"
+
+    Args:
+        name: Optional name override for the agent span
+        version: Optional version number for the agent
+        attributes: Optional additional attributes to add to the span
+
+    Returns:
+        Decorated function with telemetry instrumentation
+
+    Examples:
+        @agent()
+        def my_agent():
+            pass
+
+        @agent(name="chat_agent", version=1)
+        async def chat_with_user():
+            pass
+    """
+    def decorator(func: F) -> F:
+        return _create_span_wrapper(
+            func,
+            name,
+            ObservabilitySpanKind.AGENT,
+            version,
+            attributes,
+        )
+    return decorator
+
+
+def tool(
+    name: Optional[str] = None,
+    version: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for instrumenting tool functions with Progress Observability telemetry.
+
+    Uses OpenTelemetry standard semantic conventions for attributes:
+    - code.function: Function name
+    - code.namespace: Class name (if method)
+    - service.version: Version number
+    - observability.span.kind: Set to "tool"
+
+    Args:
+        name: Optional name override for the tool span
+        version: Optional version number for the tool
+        attributes: Optional additional attributes to add to the span
+
+    Returns:
+        Decorated function with telemetry instrumentation
+
+    Examples:
+        @tool()
+        def my_tool():
+            pass
+
+        @tool(name="web_search", version=1)
+        async def search_web(query: str):
+            pass
+    """
+    def decorator(func: F) -> F:
+        return _create_span_wrapper(
+            func,
+            name,
+            ObservabilitySpanKind.TOOL,
+            version,
+            attributes,
+        )
+    return decorator

progress/observability/enums.py

@@ -0,0 +1,51 @@
+"""
+Enums for Progress Observability Instrumentation
+
+Provides granular control over AI agent tracing.
+"""
+
+from enum import Enum
+from traceloop.sdk.instruments import Instruments
+
+
+class ObservabilityInstruments(Enum):
+    """Progress Observability instruments enum that maps to Traceloop instruments"""
+    # LLM Providers
+    OPENAI = Instruments.OPENAI
+    ANTHROPIC = Instruments.ANTHROPIC
+    COHERE = Instruments.COHERE
+    BEDROCK = Instruments.BEDROCK
+    VERTEXAI = Instruments.VERTEXAI
+    SAGEMAKER = Instruments.SAGEMAKER
+    OLLAMA = Instruments.OLLAMA
+    GROQ = Instruments.GROQ
+    MISTRAL = Instruments.MISTRAL
+    TOGETHER = Instruments.TOGETHER
+    REPLICATE = Instruments.REPLICATE
+    ALEPHALPHA = Instruments.ALEPHALPHA
+    GOOGLE_GENERATIVEAI = Instruments.GOOGLE_GENERATIVEAI
+    TRANSFORMERS = Instruments.TRANSFORMERS
+    WATSONX = Instruments.WATSONX
+    
+    # Agent and Chain Frameworks
+    LANGCHAIN = Instruments.LANGCHAIN
+    LLAMA_INDEX = Instruments.LLAMA_INDEX
+    CREW = Instruments.CREW
+    HAYSTACK = Instruments.HAYSTACK
+    OPENAI_AGENTS = Instruments.OPENAI_AGENTS
+    MCP = Instruments.MCP
+    
+    # Vector Databases
+    PINECONE = Instruments.PINECONE
+    CHROMA = Instruments.CHROMA
+    WEAVIATE = Instruments.WEAVIATE
+    QDRANT = Instruments.QDRANT
+    MILVUS = Instruments.MILVUS
+    LANCEDB = Instruments.LANCEDB
+    MARQO = Instruments.MARQO
+    REDIS = Instruments.REDIS
+    PYMYSQL = Instruments.PYMYSQL
+    
+    # Tools and Infrastructure
+    REQUESTS = Instruments.REQUESTS
+    URLLIB3 = Instruments.URLLIB3

progress/observability/exceptions.py

@@ -0,0 +1,61 @@
+"""
+Observability custom exceptions for validation and error handling.
+"""
+
+
+class ObservabilityError(Exception):
+    """Base exception class for Progress Observability instrumentation errors."""
+    pass
+
+
+class EndpointValidationError(ObservabilityError):
+    """Raised when an invalid endpoint is provided."""
+    pass
+
+
+class InvalidPortError(EndpointValidationError):
+    """Raised when an invalid port number is provided in the endpoint."""
+    def __init__(self, port: str, message: str = None):
+        if message is None:
+            message = f"Invalid port number '{port}'. Port must be between 1 and 65535."
+        super().__init__(message)
+
+
+class MissingHostError(EndpointValidationError):
+    """Raised when the host is missing from the endpoint URL."""
+    def __init__(self, endpoint: str, message: str = None):
+        if message is None:
+            message = f"Missing host in endpoint '{endpoint}'. Expected format: http://hostname:port"
+        super().__init__(message)
+
+
+class MissingPortError(EndpointValidationError):
+    """Raised when the port is missing from the endpoint URL."""
+    def __init__(self, endpoint: str, message: str = None):
+        if message is None:
+            message = f"Missing port in endpoint '{endpoint}'. Expected format: http://hostname:port"
+        super().__init__(message)
+
+
+class NonNumericPortError(EndpointValidationError):
+    """Raised when the port is not a valid numeric value."""
+    def __init__(self, port: str, message: str = None):
+        if message is None:
+            message = f"Port '{port}' must be a numeric value between 1 and 65535."
+        super().__init__(message)
+
+
+class UnsupportedSchemeError(EndpointValidationError):
+    """Raised when an unsupported URL scheme is used (only http/https are supported)."""
+    def __init__(self, scheme: str, message: str = None):
+        if message is None:
+            message = f"Unsupported URL scheme '{scheme}'. Only 'http' and 'https' are supported."
+        super().__init__(message)
+
+
+class InvalidHostError(EndpointValidationError):
+    """Raised when the host contains invalid characters (e.g., spaces)."""
+    def __init__(self, host: str, message: str = None):
+        if message is None:
+            message = f"Invalid host '{host}'. Host cannot contain spaces or invalid characters."
+        super().__init__(message)

progress/observability/helpers.py

@@ -0,0 +1,143 @@
+"""
+Helper functions for Progress Observability instrumentation
+"""
+
+import os
+import sys
+from typing import Optional, Dict, Any
+from .constants import SDK_ENV_VARS
+
+class ObservabilityTelemetry:
+    """Helper class for Progress Observability"""
+    
+    def __new__(cls):
+        if not hasattr(cls, "instance"):
+            cls.instance = super(ObservabilityTelemetry, cls).__new__(cls)
+        return cls.instance
+    
+    def __init__(self):
+        self._telemetry_enabled = False
+        self._posthog = None
+        self._curr_anon_id = None
+    
+    def _anon_id(self) -> str:
+        return "disabled"
+    
+    def _context(self) -> Dict[str, Any]:
+        return {}
+    
+    def capture(self, event: str, event_properties: Dict[str, Any] = {}) -> None:
+        pass
+    
+    def log_exception(self, exception: Exception) -> None:
+        pass
+    
+    def feature_enabled(self, key: str) -> bool:
+        return False
+
+
+def patch_traceloop_modules() -> None:
+    """Patch Traceloop modules with Observability implementations"""
+    sys.modules['traceloop.sdk.telemetry'] = type(sys)('telemetry')
+    sys.modules['traceloop.sdk.telemetry'].Telemetry = ObservabilityTelemetry
+
+    # Patch Traceloop with Progress Observability's default span processor
+    from traceloop.sdk import Traceloop
+    Traceloop.get_default_span_processor = staticmethod(observability_get_default_span_processor)
+
+
+def clear_sdk_env_vars() -> None:
+    """Clear all sdk* environment variables to prevent conflicts"""
+    for var in SDK_ENV_VARS:
+        if var in os.environ:
+            del os.environ[var]
+
+
+def is_http_endpoint(endpoint: Optional[str]) -> bool:
+    """Check if endpoint is HTTP/HTTPS (vs gRPC)"""
+    return bool(endpoint) and (
+        endpoint.startswith("http://") or endpoint.startswith("https://")
+    )
+
+
+def observability_get_default_span_processor(
+    disable_batch: bool = False,
+    api_endpoint: Optional[str] = None,
+    api_key: Optional[str] = None,
+    headers: Optional[Dict[str, Any]] = None,
+    exporter: Optional[Any] = None
+) -> Any:
+    """Observability version of get_default_span_processor with dual auth headers"""
+    from traceloop.sdk.tracing.tracing import get_default_span_processor
+    
+    if headers is None:
+        if api_key is None:
+            api_key = os.getenv("OBSERVABILITY_API_KEY")
+
+        # Only add headers for HTTP endpoints
+        if is_http_endpoint(api_endpoint):
+            headers = {
+                "Authorization": f"Bearer {api_key}",
+                "X-Api-Key": api_key
+            }
+        else:
+            headers = {}  # No headers for gRPC endpoints
+    
+    if api_endpoint is None:
+        api_endpoint = os.getenv("OBSERVABILITY_ENDPOINT")
+    
+    return get_default_span_processor(api_key, disable_batch, api_endpoint, headers, exporter)
+
+
+def init_environment(app_name: str, endpoint: Optional[str], api_key: Optional[str], trace_content: Optional[bool]) -> tuple[str, Optional[str], Optional[str]]:
+    """Initialize environment variables with Observability overrides"""
+    endpoint = os.getenv("OBSERVABILITY_ENDPOINT") or endpoint
+    api_key = os.getenv("OBSERVABILITY_API_KEY") or api_key
+    app_name = os.getenv("OBSERVABILITY_APP_NAME") or app_name
+    
+    # Handle trace_content from environment variable or parameter
+    env_trace_content = os.getenv("OBSERVABILITY_TRACE_CONTENT")
+    if env_trace_content is not None:
+        trace_content_value = env_trace_content.lower() in ('true', '1', 'yes')
+    elif trace_content is not None:
+        trace_content_value = trace_content
+    else:
+        trace_content_value = True
+    
+    # Set TRACELOOP_TRACE_CONTENT for the underlying SDK only if false (default is true)
+    if not trace_content_value:
+        os.environ['TRACELOOP_TRACE_CONTENT'] = 'false'
+    
+    import logging
+
+    # Disable metrics exporter - OBSERVABILITY focuses on spans/traces only
+    if 'OTEL_METRICS_EXPORTER' not in os.environ:
+        os.environ['OTEL_METRICS_EXPORTER'] = 'none'
+
+    # Suppress metrics exporter 404 errors (underlying SDK doesn't fully respect the env var)
+    logger = logging.getLogger("opentelemetry.exporter.otlp.proto.http.metric_exporter")
+    logger.disabled = True
+
+    # Validate endpoint format if provided
+    if endpoint and not (endpoint.startswith("http://") or endpoint.startswith("https://") or ":" in endpoint):
+        raise ValueError(f"Invalid endpoint format: {endpoint}")
+        
+    return app_name, endpoint, api_key
+def setup_api_key_headers(api_key: str, endpoint: Optional[str], init_kwargs: Dict[str, Any], kwargs: Dict[str, Any]) -> None:
+    """Setup API key validation and authentication headers"""
+    # Validate API key format
+    if not isinstance(api_key, str) or not api_key.strip():
+        raise ValueError("API key must be a non-empty string")
+    
+    # Only add headers for HTTP endpoints
+    if is_http_endpoint(endpoint):
+        headers = kwargs.get("headers", {})
+        if isinstance(headers, dict):
+            headers["Authorization"] = f"Bearer {api_key}"
+            headers["X-Api-Key"] = api_key
+        else:
+            headers = {
+                "Authorization": f"Bearer {api_key}",
+                "X-Api-Key": api_key
+            }
+        init_kwargs["headers"] = headers