Metadata-Version: 2.4
Name: progress-observability
Version: 1.4.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://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.59.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
```
