Metadata-Version: 2.4
Name: progress-observability
Version: 1.5.3
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://www.telerik.com/ai-observability-platform/documentation/sdk/python
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: httpx==0.28.1
Requires-Dist: requests==2.34.2
Requires-Dist: traceloop-sdk==0.62.3
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` - Show sanitized OTLP trace-delivery failures on standard error (default: `False`)
- `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
- `OBSERVABILITY_DEBUG` enables sanitized trace-delivery errors when set to `1`, `true`, or `yes`

Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
Invalid endpoints and missing or empty API keys raise during initialization. Delivery failures do not terminate the application and remain silent unless debug logging is enabled. Debug messages never include API keys, authorization headers, or telemetry payloads.

## 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
```
