BranchPy
Log in

Telemetry Quick Reference

Version: 1.1.1
Last Updated: March 30, 2026

Commands

  • branchpy telemetry mode --show — display current mode.
  • branchpy telemetry mode manual|auto|off — set mode (default manual).
  • branchpy telemetry stats — show event counts from local storage (reads JSONL files directly).
  • branchpy telemetry inspect [--last N] [--store core|sessions|all] [--event-type TEXT] — inspect raw events.
  • branchpy telemetry preview [--from 2h] [--json] [--full] — inspect package without writing.
  • branchpy telemetry export --output rc-metrics.json [--from 2h] — write sanitized package.
  • branchpy telemetry upload --file rc-metrics.json — upload existing package.
  • branchpy telemetry upload --auto [--from 24h] [--dry-run] [--endpoint URL] — build + send.

Storage Locations (canonical for pre-release)

Core command metadata (branchpy.core.telemetry):

  • Windows: %LOCALAPPDATA%\BranchPy\cache\telemetry.jsonl
  • Linux/Mac: ~/.BranchPy/cache/telemetry.jsonl

Session/structured events (branchpy.telemetry.local_writer):

  • Windows: %LOCALAPPDATA%\BranchPy\logs\telemetry\telemetry_<ts>.jsonl
  • Linux/Mac: ~/.branchpy/logs/telemetry/telemetry_<ts>.jsonl
  • Legacy/project-local fallback: <project>/.branchpy/logs/telemetry/

VS Code events:

  • Windows: %APPDATA%\Code\User\globalStorage\branchpy-team.branchpy\telemetry\*.jsonl
  • Analogous macOS/Linux paths.

Note: Phase3TelemetryHandler is an in-memory aggregation layer only — its persistence path is not yet implemented. JSONL files above are the authoritative durable store for the pre-release.

Modes & Defaults

  • Default mode: manual
  • Default time window: --from 2h
  • Auto upload interval: 24h (auto mode only)
  • Upload size cap: 5MB (config)
  • Cache sampling: 100% (can be reduced via env)

API Endpoints (rc-backend)

  • POST /api/telemetry/upload — ingest package
  • GET /api/telemetry/stats — summary totals
  • GET /api/telemetry/events — filtered events
  • GET /api/telemetry/aggregate/category|source|timeline — charts
  • GET /api/telemetry/errors/recent|slo — error views
  • GET /api/telemetry/sessions — session analytics
  • GET /api/telemetry/health — health check

Safety Checks

  • No auto-send in manual mode; auto requires explicit opt-in.
  • Paths and error messages hashed; no content stored.
  • Preview/dry-run recommended before uploads.