BranchPy
Log in

Docs-Builder

# Telemetry Architecture

Version: 1.1.1
Last Updated: January 23, 2026

System Overview

  • Emitters: BranchPy CLI/daemon commands, cache decorators (cache.* events), provider/validation modules, VS Code extension UI.
  • Local Logs: JSONL events written per app context (~/.branchpy/telemetry/events.jsonl, VS Code globalStorage path). No network writes at emit time.
  • Package Builder: branchpy.telemetry.package_builder.build_telemetry_package() reads JSONL, sanitizes, aggregates, and produces a versioned TelemetryPackage (schema v1.0.0).
  • Upload/Export: CLI drives export or upload; VS Code Control Center wraps the same CLI commands. Auto mode schedules uploads; manual mode requires explicit actions.
  • Ingestion: rc-backend /api/telemetry/* endpoints ingest packages into storage sinks (MySQL primary, SQLite/dev, Composite optional).
  • Dashboard: WebSite admin-telemetry.html consumes rc-backend endpoints for charts and stats.

Data Flow

Emitters (CLI, daemon, extension, decorators)
      ↓
Local JSONL logs (per-app storage)
      ↓
Telemetry Package Builder (sanitize + aggregate)
      ↓
Export file (rc-metrics.json) or auto upload
      ↓
rc-backend ingestion API (API key / auth token)
      ↓
Storage sink (MySQL | SQLite | Composite)
      ↓
Admin dashboard & analytics

Core Modules

  • branchpy.telemetry.package_schema: Typed schema for TelemetryPackage, TelemetryEvent, PerformanceMetrics, UsageStatistics, SanitizedError; enforces privacy validation.
  • branchpy.telemetry.package_builder: Entry points (build_telemetry_package, build_client_info, sanitize_event, build_performance_metrics, build_usage_statistics, extract_errors).
  • branchpy.telemetry.storage_*: Storage backends (MySQLTelemetrySink, LocalSQLiteSink, CompositeSink, MemorySink).
  • branchpy.telemetry.config: Telemetry config surface (mode, auto interval, upload size cap, endpoint, auth token).
  • BranchPyApp/branchpy/cli/telemetry_cmd.py: CLI commands for mode, preview, export, upload.
  • vscode-addon/controlCenter.html + src/controlCenter.ts: UI layer that proxies the CLI for mode/preview/export/upload.

Event Sources

  • CLI/Daemon: Command lifecycle, performance metrics, error envelopes (hashed messages, hashed file paths).
  • Cache Decorators: cache.hit/miss/evict/invalidate/stats with latency and hit ratios; sampling controls in TelemetryConfig.
  • Providers: provider.* events with operation, latency, counts, optional path (hashed before upload).
  • Validation: validation.start/complete/error from ValidationTelemetryContext (issues, duration, module).
  • VS Code: UI usage (media.*), performance metrics (ui.render_time), export actions; privacy tier controls obfuscation.

Reliability & Performance

  • Non-blocking emitters; telemetry failures are logged and do not block user flows.
  • Throughput target ≥10k events/sec (measured 1.13M/sec in Phase 3); p95 latency <1ms.
  • Unicode-safe ingestion/export (emoji and multi-script paths handled; tests cover CP-1252 edge cases).

Governance & Audit

  • Opt-in sending: no network traffic without manual export or user-selected auto mode.
  • Event validation against schema and governance IDs; export package is reviewable JSON.
  • Correlation IDs preserved end-to-end; device IDs double-hashed for privacy.