progress-observability 1.2.0__tar.gz → 1.4.1__tar.gz

progress_observability-1.4.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: progress-observability
+Version: 1.4.1
+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.53.2
+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
+
+Common options (for `Observability.instrument`):
+
+- `app_name` - Application name for telemetry
+- `endpoint` - OpenTelemetry collector endpoint
+- `api_key` - Authentication key
+- `debug` - Enable debug logging
+- `instruments` / `block_instruments` - Control what gets traced via `ObservabilityInstruments`
+- `trace_content` - when set to `False` will stop sending LLM prompt/responses as part of the telemetry data
+- `additional_tags` - custom tags (see below)
+
+Environment overrides (optional):
+
+- `OBSERVABILITY_APP_NAME` sets the application name (e.g. "my-app")
+- `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
+- `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
+- `OBSERVABILITY_TRACE_CONTENT` when set to `false` will stop sending LLM prompt/responses as part of the telemetry data
+
+Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
+
+## Custom Tags
+
+Tags are user-defined strings (max 200 characters each) attached to observations for filtering and grouping.
+
+**Global tags** — applied to every span:
+
+```python
+Observability.instrument(
+    app_name="my-app",
+    api_key="<your-api-key>",
+    additional_tags=["production", "release:2.4.1"],
+)
+```
+
+**Scoped tags** — applied to spans within a specific block via `propagate_attributes`:
+
+```python
+from progress.observability import propagate_attributes
+
+with propagate_attributes(tags=["tenant:acme", "experiment-v2"]):
+    # All spans created here inherit these tags
+    my_agent_function()
+```
+
+Nesting is supported — tags accumulate from outer to inner scopes.
+
+**Decorator tags** — applied to a single decorated function:
+
+```python
+from progress.observability import task
+
+@task(tags=["cohort-a"])
+def my_task():
+    ...
+```
+
+## 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
+├── exceptions.py               # Custom exception types
+├── genai_message_processor.py  # LLM span content normalization
+├── helpers.py                  # Helper functions
+├── model_fix_processor.py      # LLM span attribute repair
+├── tags.py                     # Tag propagation span processor
+```

progress_observability-1.4.1/README.md

@@ -0,0 +1,101 @@
+# 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
+
+Common options (for `Observability.instrument`):
+
+- `app_name` - Application name for telemetry
+- `endpoint` - OpenTelemetry collector endpoint
+- `api_key` - Authentication key
+- `debug` - Enable debug logging
+- `instruments` / `block_instruments` - Control what gets traced via `ObservabilityInstruments`
+- `trace_content` - when set to `False` will stop sending LLM prompt/responses as part of the telemetry data
+- `additional_tags` - custom tags (see below)
+
+Environment overrides (optional):
+
+- `OBSERVABILITY_APP_NAME` sets the application name (e.g. "my-app")
+- `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
+- `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
+- `OBSERVABILITY_TRACE_CONTENT` when set to `false` will stop sending LLM prompt/responses as part of the telemetry data
+
+Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
+
+## Custom Tags
+
+Tags are user-defined strings (max 200 characters each) attached to observations for filtering and grouping.
+
+**Global tags** — applied to every span:
+
+```python
+Observability.instrument(
+    app_name="my-app",
+    api_key="<your-api-key>",
+    additional_tags=["production", "release:2.4.1"],
+)
+```
+
+**Scoped tags** — applied to spans within a specific block via `propagate_attributes`:
+
+```python
+from progress.observability import propagate_attributes
+
+with propagate_attributes(tags=["tenant:acme", "experiment-v2"]):
+    # All spans created here inherit these tags
+    my_agent_function()
+```
+
+Nesting is supported — tags accumulate from outer to inner scopes.
+
+**Decorator tags** — applied to a single decorated function:
+
+```python
+from progress.observability import task
+
+@task(tags=["cohort-a"])
+def my_task():
+    ...
+```
+
+## 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
+├── exceptions.py               # Custom exception types
+├── genai_message_processor.py  # LLM span content normalization
+├── helpers.py                  # Helper functions
+├── model_fix_processor.py      # LLM span attribute repair
+├── tags.py                     # Tag propagation span processor
+```

{progress_observability-1.2.0 → progress_observability-1.4.1}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "progress-observability"
-version = "1.2.0"
+version = "1.4.1"
 description = "Progress Observability instrumentation for Python agents"
 readme = "README.md"
 license = { text = "MIT" }
 license-files = ["LICENSE", "notices.txt"]
 requires-python = ">=3.10.0,<4.0.0"
 dependencies = [
-    "traceloop-sdk==0.49.5",
+    "traceloop-sdk==0.53.2",
 ]
 [project.urls]
 Homepage = "https://github.com/telerik/agentclarity"

{progress_observability-1.2.0 → progress_observability-1.4.1}/src/progress/observability/__init__.py

@@ -10,6 +10,7 @@ from .decorators import task, workflow, agent, tool
 from .enums import ObservabilityInstruments
 from .constants import OBSERVABILITY_ENV_VARS
 from .helpers import clear_sdk_env_vars
+from .tags import propagate_attributes, validate_tags, get_context_tags
 
 __all__ = [
     'Observability',
@@ -19,4 +20,7 @@ __all__ = [
     'workflow',
     'agent',
     'tool',
-]
+    'propagate_attributes',
+    'validate_tags',
+    'get_context_tags',
+]

{progress_observability-1.2.0 → progress_observability-1.4.1}/src/progress/observability/constants.py

@@ -29,3 +29,7 @@ OBSERVABILITY_ENV_VARS = [
 DEFAULTS = {
     "ENDPOINT": "https://collector.observability.progress.com:443"
 }
+
+# Tag constants
+TAGS_ATTRIBUTE_KEY = "observability.tags"
+TAG_MAX_LENGTH = 200

progress_observability-1.4.1/src/progress/observability/decorators.py

@@ -0,0 +1,205 @@
+"""
+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 Any, Awaitable, Callable, Dict, List, Optional, TypeVar, Union
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from .constants import TAGS_ATTRIBUTE_KEY
+from .tags import validate_tags
+
+
+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,
+    tags: Optional[List[str]] = 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
+        tags: Optional list of string tags to attach to the span (max 200 chars each)
+
+    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)
+
+    # Validate and include decorator-level tags as span attributes
+    validated_tags = validate_tags(tags, warn_on_drop=True) if tags else []
+    if validated_tags:
+        base_attributes[TAGS_ATTRIBUTE_KEY] = validated_tags
+
+    # 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 _make_decorator(
+    span_kind: str,
+) -> Callable[..., Callable[[F], F]]:
+    """
+    Factory that creates a telemetry decorator for a given span kind.
+
+    Each generated decorator accepts (name, version, attributes, tags)
+    and wraps the target function with an OpenTelemetry span whose
+    ``observability.span.kind`` is set to *span_kind*.
+
+    Args:
+        span_kind: The observability span kind value (e.g. "task", "workflow").
+
+    Returns:
+        A decorator factory with the standard (name, version, attributes, tags) signature.
+    """
+    def decorator_factory(
+        name: Optional[str] = None,
+        version: Optional[int] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Callable[[F], F]:
+        def decorator(func: F) -> F:
+            return _create_span_wrapper(
+                func,
+                name,
+                span_kind,
+                version,
+                attributes,
+                tags,
+            )
+        return decorator
+    return decorator_factory
+
+
+# Shared docstring template for all telemetry decorators
+_DECORATOR_DOCSTRING = """Decorator for instrumenting {kind} 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 "{kind}"
+
+Args:
+    name: Optional name override for the span
+    version: Optional version number
+    attributes: Optional additional attributes to add to the span
+    tags: Optional list of string tags to attach (max 200 chars each)
+
+Examples::
+
+    @{kind}()
+    def my_function():
+        pass
+
+    @{kind}(name="custom_name", version=1, tags=["production"])
+    async def async_function():
+        pass
+"""
+
+# Create the four public decorators
+task: Callable[..., Callable[[F], F]] = _make_decorator(ObservabilitySpanKind.TASK)
+task.__doc__ = _DECORATOR_DOCSTRING.format(kind="task")
+
+workflow: Callable[..., Callable[[F], F]] = _make_decorator(ObservabilitySpanKind.WORKFLOW)
+workflow.__doc__ = _DECORATOR_DOCSTRING.format(kind="workflow")
+
+agent: Callable[..., Callable[[F], F]] = _make_decorator(ObservabilitySpanKind.AGENT)
+agent.__doc__ = _DECORATOR_DOCSTRING.format(kind="agent")
+
+tool: Callable[..., Callable[[F], F]] = _make_decorator(ObservabilitySpanKind.TOOL)
+tool.__doc__ = _DECORATOR_DOCSTRING.format(kind="tool")