openadapt-telemetry

Unified telemetry and error tracking for OpenAdapt packages.

Features

• Unified Error Tracking: Consistent error reporting across all OpenAdapt packages
• Usage Counters (PostHog): Lightweight product usage events for adoption metrics
• Privacy-First Design: Automatic PII scrubbing and path sanitization
• Configurable Opt-Out: Respects DO_NOT_TRACK and custom environment variables
• Internal Usage Tagging: Explicit flags + CI detection with optional git heuristic
• GlitchTip/Sentry Compatible: Uses the Sentry SDK for maximum compatibility
• Failure recurrence without customer evidence: Closed categorical failure signatures omit application, tenant, workflow, step, text, input, screenshot, origin, and exception details

Installation

pip install openadapt-telemetry

Or with development dependencies:

pip install openadapt-telemetry[dev]

Quick Start

Initialize Telemetry

from openadapt_telemetry import get_telemetry

# Initialize once at package startup
get_telemetry().initialize(
    dsn="https://xxx@app.glitchtip.com/XXXX",
    package_name="openadapt-mypackage",
    package_version="0.1.0",
)

Capture Exceptions

from openadapt_telemetry import get_telemetry

try:
    risky_operation()
except Exception as e:
    get_telemetry().capture_exception(e)
    raise

Capture Usage Events (PostHog)

from openadapt_telemetry import capture_usage_event

capture_usage_event(
    "agent_run",
    properties={"entrypoint": "oa evals run", "mode": "live"},
    package_name="openadapt-evals",
)

Capture an automation failure safely

Use the closed-schema failure API rather than sending an exception message or run report as analytics. Its grouping key is derived only from categorical runtime facts; it is not an installation or tenant identifier.

from openadapt_telemetry import (
    ActionKind, AutomationFailureSignal, DeliveryState, ExecutionOutcome,
    FailureKind, RiskClass, Substrate, capture_automation_failure,
)

capture_automation_failure(AutomationFailureSignal(
    failure_kind=FailureKind.DELIVERY_UNCERTAIN,
    substrate=Substrate.CITRIX,
    action_kind=ActionKind.CLICK,
    risk_class=RiskClass.CONSEQUENTIAL,
    delivery_state=DeliveryState.UNCERTAIN,
    outcome=ExecutionOutcome.HALTED,
))

This signal supports aggregate discovery only. Full evidence remains local, and no signal can authorize or promote a repair.

Using Decorators

from openadapt_telemetry import track_errors, track_performance, track_feature

@track_errors()
def process_data(data):
    """Exceptions are automatically captured."""
    return transform(data)

@track_performance("indexing.build_faiss")
def build_index(vectors):
    """Execution time is automatically tracked."""
    return create_index(vectors)

@track_feature("retrieval.add_demo")
def add_demo(demo_id, task):
    """Feature usage is tracked for analytics."""
    save_demo(demo_id, task)

Span Context Manager

from openadapt_telemetry import TelemetrySpan

with TelemetrySpan("indexing", "build_faiss_index") as span:
    span.set_tag("num_vectors", 1000)
    # ... indexing operations ...

Configuration

Environment Variables

Configuration File

Create ~/.config/openadapt/telemetry.json:

{
  "enabled": true,
  "internal": false,
  "dsn": "https://xxx@app.glitchtip.com/XXXX",
  "environment": "production",
  "sample_rate": 1.0,
  "traces_sample_rate": 0.01
}

Priority Order

1. Environment variables (highest priority)
2. Configuration file
3. Package defaults (lowest priority)

Opt-Out

To disable telemetry, set either:

# Universal standard
export DO_NOT_TRACK=1

# Or package-specific
export OPENADAPT_TELEMETRY_ENABLED=false

Privacy

What We Collect

What We Never Collect

• Screenshots or images
• Text content or file contents
• Personal information (names, emails, IPs)
• API keys or passwords
• Full file paths with usernames

Automatic Scrubbing

• File paths have usernames replaced with <user>
• Sensitive fields (password, token, api_key, etc.) are redacted
• Email addresses and phone numbers are scrubbed from messages
• Top-level event messages/logentry strings are scrubbed
• Tag keys are validated, sensitive/invalid keys are dropped, and values are scrubbed before upload
• User IDs are HMAC-anonymized before upload (anon:v2:<hash>)
• send_default_pii is enforced to false by the client
• PostHog events set $geoip_disable: true to suppress IP geolocation enrichment

Internal Usage Tagging

Internal/developer usage is automatically detected via:

1. OPENADAPT_INTERNAL=true environment variable
2. OPENADAPT_DEV=true environment variable
3. CI environment detected (GitHub Actions, GitLab CI, etc.)
4. Optional git repository heuristic when OPENADAPT_INTERNAL_FROM_GIT=true

Filter in GlitchTip:

tag:internal IS false  # External users only
tag:internal IS true   # Internal users only

Development

# Clone and install
git clone https://github.com/OpenAdaptAI/openadapt-telemetry
cd openadapt-telemetry
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=openadapt_telemetry

License

MIT License - see LICENSE for details.

Links

• Documentation
• Issues
• GlitchTip
• Sentry SDK