Docs-Builder

# Telemetry API Surface

Version: 1.1.1
Last Updated: January 23, 2026

This file rehomes the telemetry API extract from Technical/api/api.md (track_event/track_error/get_usage_stats).

Runtime APIs

Signature: branchpy.telemetry.track_event(event_name: str, properties: Dict) -> None

Example:

track_event(
    "analyze_complete",
    {
        "file_count": 42,
        "duration_ms": 1234,
        "warnings_found": 5
    }
)

Signature: branchpy.telemetry.track_error(error: Exception, context: Dict) -> None

Usage:

try:
    run_analysis()
except Exception as exc:
    track_error(exc, {"component": "analyze", "stage": "parse"})

Signature: branchpy.telemetry.get_usage_stats() -> Dict

Returns:

{
    "total_analyses": 150,
    "total_fixes_applied": 45,
    "ai_requests": 20,
    "uptime_hours": 24.5
}

Emission is non-blocking; failures are logged but do not break user flows.
Events are sanitized before storage/export (no raw paths or content; hashed errors).
Stored locally in JSONL and ingested via package builder â†’ upload pipeline (see architecture/ingestion docs).