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

pip install progress-observability

Or from wheel file:

pip install progress_observability-x.y.z-py3-none-any.whl

Quick Start

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:

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:

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:

from progress.observability import task

@task(tags=["cohort-a"])
def my_task():
    ...

Package Structure

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