progress-observability 1.1.4__py3-none-any.whl

progress/observability/sdk.py

@@ -0,0 +1,296 @@
+"""
+Progress Observability - Zero-intrusion AI agent telemetry
+
+Provides granular control over AI agent tracing with zero code changes required
+to existing agent implementations. Simply add one line at the beginning of your
+agent code to enable comprehensive telemetry.
+
+Quick Start:
+    
+    from progress.observability.instrumentation import Observability
+    
+    # Basic initialization
+    Observability.instrument(
+        app_name="my-agent-app",
+        endpoint='https://collector.observability.progress.com:443',
+        api_key="<YOUR_API_KEY>",
+    )
+
+
+"""
+
+import sys
+from contextlib import redirect_stdout, redirect_stderr
+from io import StringIO
+from typing import Any, Dict, Optional, Set
+from urllib.parse import urlparse
+
+from .enums import ObservabilityInstruments
+from .helpers import init_environment, setup_api_key_headers, patch_traceloop_modules, clear_sdk_env_vars
+from .model_fix_processor import ModelFixProcessor
+from .exceptions import (
+    EndpointValidationError,
+    InvalidPortError,
+    MissingHostError,
+    MissingPortError,
+    NonNumericPortError,
+    UnsupportedSchemeError,
+    InvalidHostError,
+)
+
+patch_traceloop_modules()
+clear_sdk_env_vars()
+
+from traceloop.sdk import Traceloop
+
+
+class Observability:
+    """
+    Progress Observability - Zero-intrusion AI agent telemetry
+
+    Provides granular control over AI agent tracing with zero code changes required
+    to existing agent implementations. Simply add one line at the beginning of your
+    agent code to enable comprehensive telemetry.
+    """
+
+    _initialized = False
+    _model_fix_processor = None  # Store for debugging access
+    SDK = Traceloop
+
+    @staticmethod
+    def _validate_endpoint(endpoint: Optional[str]) -> None:
+        """
+        Validate the endpoint URL format and components.
+        
+        Args:
+            endpoint: The endpoint URL to validate
+            
+        Raises:
+            EndpointValidationError: If the endpoint is invalid
+        """
+        if endpoint is None or endpoint == "":
+            # Empty string and None are allowed (will use defaults)
+            return
+            
+        try:
+            parsed = urlparse(endpoint)
+        except Exception as e:
+            raise EndpointValidationError(f"Failed to parse endpoint '{endpoint}': {e}")
+        
+        # Check scheme
+        if parsed.scheme not in ("http", "https"):
+            raise UnsupportedSchemeError(parsed.scheme or "missing")
+        
+        # Check host
+        if not parsed.hostname:
+            raise MissingHostError(endpoint)
+        
+        # Check for spaces in hostname
+        if " " in parsed.hostname:
+            raise InvalidHostError(parsed.hostname)
+        
+        # Check port
+        try:
+            port = parsed.port
+        except ValueError as ve:
+            # Handle port out of range or non-numeric port
+            msg = str(ve)
+            if "out of range" in msg:
+                # Extract port from netloc
+                port_part = parsed.netloc.split(":")[-1]
+                raise InvalidPortError(port_part)
+            else:
+                port_part = parsed.netloc.split(":")[-1]
+                raise NonNumericPortError(port_part)
+
+        if port is None:
+            # Check if there's a colon without a port number
+            if ":" in parsed.netloc and not parsed.netloc.endswith(":"):
+                port_part = parsed.netloc.split(":")[-1]
+                if port_part and not port_part.isdigit():
+                    raise NonNumericPortError(port_part)
+            elif parsed.netloc.endswith(":"):
+                raise MissingPortError(endpoint)
+        else:
+            if port < 1 or port > 65535:
+                raise InvalidPortError(str(port))
+
+    @staticmethod
+    def _build_init_kwargs(
+        *,
+        app_name: Optional[str],
+        api_key: Optional[str],
+        endpoint: Optional[str],
+        instruments: Optional[Set[ObservabilityInstruments]],
+        block_instruments: Optional[Set[ObservabilityInstruments]],
+        disable_batch: bool,
+        resource_attributes: Optional[Dict[str, Any]],
+        extra_kwargs: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Build keyword arguments for the underlying SDK.init call.
+
+        Converts Observability enums to Traceloop values, applies batching and
+        resource attributes, configures API key headers when provided, and
+        merges any additional kwargs.
+        
+        Args:
+            app_name: Application name for telemetry identification
+            api_key: Optional API key for authentication
+            endpoint: Optional collector endpoint URL
+            instruments: Optional set of instruments to enable
+            block_instruments: Optional set of instruments to block
+            disable_batch: Whether to disable batching (default True)
+            resource_attributes: Optional additional resource attributes
+            extra_kwargs: Additional kwargs from caller (highest precedence)
+            
+        Returns:
+            Dictionary of keyword arguments ready for SDK.init()
+        """
+
+        # Convert ObservabilityInstruments to Traceloop instruments
+        traceloop_instruments = (
+            {instrument.value for instrument in instruments}
+            if instruments
+            else None
+        )
+        traceloop_block_instruments = (
+            {instrument.value for instrument in block_instruments}
+            if block_instruments
+            else None
+        )
+
+        init_kwargs: Dict[str, Any] = {
+            "app_name": app_name,
+            "disable_batch": disable_batch,
+            "telemetry_enabled": False
+        }
+        
+        if api_key:
+            init_kwargs["api_key"] = api_key
+        if endpoint:
+            init_kwargs["api_endpoint"] = endpoint
+            
+        if traceloop_instruments:
+            init_kwargs["instruments"] = traceloop_instruments
+        if traceloop_block_instruments:
+            init_kwargs["block_instruments"] = traceloop_block_instruments
+
+        if api_key:
+            # configure headers for exporters if api_key is provided
+            setup_api_key_headers(api_key, endpoint, init_kwargs, extra_kwargs)
+
+        if resource_attributes:
+            init_kwargs["resource_attributes"] = dict(resource_attributes)
+
+        # Merge additional kwargs last so callers can override defaults
+        init_kwargs.update(extra_kwargs)
+        return init_kwargs
+
+    @classmethod
+    def instrument(
+        cls,
+        app_name: str = sys.argv[0],
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        instruments: Optional[Set[ObservabilityInstruments]] = None,
+        block_instruments: Optional[Set[ObservabilityInstruments]] = None,
+        disable_batch: bool = True,
+        trace_content: Optional[bool] = None,
+        resource_attributes: Optional[Dict[str, Any]] = None,
+        debug: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize Observability with granular control over what gets traced.
+
+        Args:
+            app_name: Application name for telemetry identification
+            endpoint: Collector endpoint URL
+            api_key: Collector API key for authentication
+            instruments: Set of ObservabilityInstruments to enable for tracing
+            block_instruments: Set of ObservabilityInstruments to exclude from tracing
+            disable_batch: Send traces immediately vs batching
+            trace_content: Whether to log prompts/completions (default True, can also use OBSERVABILITY_TRACE_CONTENT env var)
+            resource_attributes: Additional resource attributes for traces
+            debug: Enable verbose debugging output (can also use OBSERVABILITY_DEBUG env var)
+            **kwargs: Additional parameters passed to underlying SDK
+        """
+
+        # Always allow re-initialization to support different instrument configurations
+        # The underlying traceloop SDK will handle duplicate initialization safely
+
+        # Validate endpoint before processing
+        cls._validate_endpoint(endpoint)
+
+        app_name, endpoint, api_key = init_environment(app_name, endpoint, api_key, trace_content)
+
+        # Create the model fix processor with debug mode
+        model_fix_processor = ModelFixProcessor(debug=debug)
+        cls._model_fix_processor = model_fix_processor
+
+        # Just pass the method directly - you can set breakpoints inside on_end()
+        if 'span_postprocess_callback' not in kwargs:
+            kwargs['span_postprocess_callback'] = model_fix_processor.on_end
+                
+        init_kwargs = cls._build_init_kwargs(
+            app_name=app_name,
+            api_key=api_key,
+            endpoint=endpoint,
+            instruments=instruments,
+            block_instruments=block_instruments,
+            disable_batch=disable_batch,
+            resource_attributes=resource_attributes,
+            extra_kwargs=kwargs,
+        )
+
+        # Suppress SDK init output to keep user console clean
+        with redirect_stdout(StringIO()), redirect_stderr(StringIO()):
+            cls.SDK.init(**init_kwargs)
+
+        cls._initialized = True
+
+    @classmethod
+    def shutdown(cls, timeout_millis: int = 30000) -> bool:
+        """
+        Shutdown Progress Observability instrumentation and clean up resources.
+
+        This method performs a shutdown of the tracing infrastructure:
+        - Shuts down the TracerProvider and all associated span processors
+        - Ensures all pending spans are exported before shutdown
+        - Prevents further telemetry collection
+        - Resets initialization state
+
+        Args:
+            timeout_millis: Maximum time to wait for shutdown completion in milliseconds.
+                          Defaults to 30000ms (30 seconds) as per OpenTelemetry spec.
+
+        Returns:
+            bool: True if shutdown completed successfully within timeout,
+                  False if shutdown failed or timed out.
+
+        Note:
+            This method should be called only once per Observability instance.
+            After shutdown, subsequent calls to instrument() will reinitialize
+            the instrumentation.
+        """
+        if not cls._initialized:
+            return True
+
+        try:
+            from opentelemetry import trace
+            from opentelemetry.sdk.trace import TracerProvider
+
+            tracer_provider = trace.get_tracer_provider()
+
+            if isinstance(tracer_provider, TracerProvider):
+                tracer_provider.shutdown()
+                cls._initialized = False
+                return True
+            else:
+                cls._initialized = False
+                return True
+        except Exception as e:
+            print(f"Error during Observability shutdown: {e}", file=sys.stderr)
+            cls._initialized = False
+            return False
+ 

progress_observability-1.1.4.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: progress-observability
+Version: 1.1.4
+Summary: Progress Observability instrumentation for Python agents
+Project-URL: Homepage, https://github.com/telerik/agentclarity
+Project-URL: Repository, https://github.com/telerik/agentclarity
+Project-URL: Documentation, https://docs.telerik.com/agentclarity
+Project-URL: Bug Reports, https://github.com/telerik/agentclarity/issues
+License: MIT
+License-File: LICENSE
+License-File: notices.txt
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: traceloop-sdk==0.49.5
+Provides-Extra: dev
+Requires-Dist: autopep8>=2.3.1; extra == 'dev'
+Requires-Dist: flake8>=7.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Progress Observability Instrumentation (Python)
+
+Zero-intrusion telemetry for AI agents and LLM apps. Built on Traceloop SDK and OpenTelemetry with a simple one-line init and optional decorators.
+
+## Installation
+
+```bash
+pip install progress-observability
+```
+
+Or from wheel file:
+
+```bash
+pip install progress_observability-x.y.z-py3-none-any.whl
+```
+
+## Quick Start
+
+```python
+from progress.observability import Observability, ObservabilityInstruments
+
+# Initialize once at process start
+Observability.instrument(
+    app_name="my-app",
+    api_key="<your-api-key>",
+    # endpoint="https://collector.observability.progress.com:443"  # Optional: has default
+)
+```
+
+## Configuration
+
+Environment overrides (optional):
+
+- `OBSERVABILITY_APP_NAME`
+- `OBSERVABILITY_ENDPOINT`
+- `OBSERVABILITY_API_KEY`
+
+Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
+
+## Package Structure
+
+```text
+src/progress/observability/
+├── __init__.py        # Package entry point
+├── sdk.py             # Main Observability SDK
+├── decorators.py      # @task, @workflow, @agent, @tool decorators
+├── constants.py       # Environment variables and constants
+├── enums.py           # ObservabilityInstruments enum
+└── helpers.py         # Helper functions
+```

progress_observability-1.1.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+progress/observability/__init__.py,sha256=bAO7njeq-xtQmt9RhLGUqSYvP7E3b7dLADodyhJIKEI,548
+progress/observability/constants.py,sha256=TBndnOlR7BPMRdKLowVUozncXvyJ08zUZjhoD4N_l88,825
+progress/observability/decorators.py,sha256=ImshbMQ1R9sjITTw2JvkE9MFWA-EmaJFImegUQUhmVA,8422
+progress/observability/enums.py,sha256=0rFPZp2hU0HMQrEF_6jMtpAH1YYdT-8pQ_igozCJvx0,1563
+progress/observability/exceptions.py,sha256=97GkeIhC1U2yE43QgRD5pSY3sGNCZvTCYQNTJNJjKeE,2358
+progress/observability/helpers.py,sha256=Iskmj5xxBsnyAP9jDkq3n5AjL1-zQrRb40cNQx0lqFE,5275
+progress/observability/model_fix_processor.py,sha256=xbvxlnCk5P-6L1uObafFMU5J57-9FSvspKaOLzJSAL8,38248
+progress/observability/sdk.py,sha256=zf71hUUkDJOUrafSuXZ_aKNmTmLEyZ2H9KZYMXKdkVI,10876
+progress_observability-1.1.4.dist-info/METADATA,sha256=INFTAWBHWQ6vBBMZNM4jf0FCG_p54y3KcVC0owfmpL8,1990
+progress_observability-1.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+progress_observability-1.1.4.dist-info/licenses/LICENSE,sha256=z0eiep_n9zMQKnqS8v3WlGZnYdMAMjV0PHSEwluAM9o,1081
+progress_observability-1.1.4.dist-info/licenses/notices.txt,sha256=YAMFoLYOZuPhLkcgl4E_o42Iwy3wpm8d15jcZbGuCuE,72182
+progress_observability-1.1.4.dist-info/RECORD,,

progress_observability-1.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

progress_observability-1.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Progress Software Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.