Docs-Builder

# Telemetry Ingestion

Version: 1.1.1
Last Updated: January 23, 2026

Pipelines

• Manual Export: branchpy telemetry export --output rc-metrics.json generates a sanitized package for user review. No upload occurs automatically.
• Manual Upload: branchpy telemetry upload --file rc-metrics.json or --auto --from <window> sends a freshly built package.
• Auto Mode: Background scheduler (config interval) runs export+upload with size caps and dry-run guardrails. Default mode is Manual (auto disabled).
• Extension Path: Control Center UI triggers the same CLI commands via telemetry.* message handlers; JSONL source is the extension globalStorage directory.

Package Contents (Schema v1.0.0)

• export_timestamp, branchpy_version, platform summary.
• events: Sanitized events (no raw paths or content; error messages hashed).
• performance_metrics: Durations aggregated by command.
• usage_statistics: Feature/command usage counts.
• errors: Hashed error samples with codes.
• governance_id and correlation IDs.

Ingestion API (rc-backend)

• Base: /api/telemetry/* (Flask). API key or auth token required except /health.
• Key Endpoints:
  • GET /api/telemetry/health — readiness probe.
  • POST /api/telemetry/upload — accept telemetry package JSON.
  • GET /api/telemetry/stats — aggregate totals for dashboard cards.
  • GET /api/telemetry/events — filtered events (category, source, date range, pagination).
  • GET /api/telemetry/aggregate/category|source|timeline — chart data.
  • GET /api/telemetry/errors/recent|slo — error and SLO widgets.
  • GET /api/telemetry/sessions — session analytics.

Storage Sinks

• MySQLTelemetrySink — production primary with pooling, prepared statements, 15 indexes.
• LocalSQLiteSink — developer/CLI default; schema auto-creates with 5 indexes.
• CompositeSink — writes to multiple sinks; isolates failures per backend.
• MemorySink — tests only.

Data Retention & Rotation

• JSONL logs rotate via telemetry_sync jobs or manual cleanup; upload size cap enforced by telemetry.max_upload_size_mb (default 5MB).
• SQLite files stored at .branchpy/telemetry/events.db; extension logs under VS Code globalStorage.
• Server-side retention governed by database policy (see BranchPyDB/telemetry_events schema).

Validation & Error Handling

• Schema validation before upload; rejects packages containing raw paths or content.
• Failed uploads return HTTP errors; client surfaces message and keeps local package.
• Non-blocking emitters: on failure, telemetry is skipped and flow continues.