Skip to content

feat(telemetry): asset compression telemetry & payload size diagnostic - #39

Merged
ATLURI0001 merged 1 commit into
mainfrom
feat/asset-telemetry-diagnostic
Nov 22, 2026
Merged

ATLURI0001 merged 1 commit into
mainfrom
feat/asset-telemetry-diagnostic

Conversation

@ATLURI0001

Copy link
Copy Markdown
Owner

Architecture & System Overview

Large static site builds and Single Page Application bundles frequently encounter unmonitored payload bloat, degrading Largest Contentful Paint (LCP) and mobile web performance. This pull request introduces a dedicated Build Asset Compression Telemetry & Payload Size Diagnostic Engine in src/buildsite/asset_telemetry.py paired with a test suite in tests/test_asset_telemetry.py.

          Static Build Artifacts (JS, CSS, HTML, Media)
                               │
                               ▼
        ┌──────────────────────────────────────────────┐
        │          AssetTelemetryCollector             │
        │ - Content-Type / Category Heuristic          │
        │ - Gzip Level 9 Compression Metric            │
        │ - Compression Efficiency Ratio               │
        └──────────────────────┬───────────────────────┘
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌─────────────────────────┐           ┌────────────────────────┐
│  Category Size Budgets  │           │ Diagnostic Anomaly Log │
│  - max_raw_per_asset    │           │ - CRITICAL: Ceiling    │
│  - max_gzip_per_asset   │           │ - WARNING: Low Ratio   │
│  - max_total_raw_bytes  │           │ - Markdown / JSON      │
└─────────────────────────┘           └────────────────────────┘

Core Components & Capabilities:

  1. Asset Classification & Category Segmentation:

    • Classifies build assets into discrete buckets: JS, CSS, HTML, IMAGE, FONT, and OTHER.
    • Evaluates size and compression behavior against category-specific budgets (e.g. JS: 250KB raw / 75KB gzip; CSS: 100KB raw / 30KB gzip).
  2. Compression Efficiency Diagnostics:

    • Calculates exact byte-level bandwidth savings: $\text{Savings} = \text{Raw} - \text{Gzip}$.
    • Detects sub-optimal compression ratios ($< 1.15\times$) on compressible text assets (flags unminified code or pre-compressed assets).
  3. Global Bundle Ceilings:

    • Tracks site-wide aggregated raw and compressed payloads, alerting when cumulative transfer sizes cross the threshold (default 5MB raw / 1.5MB gzip).
  4. Automated Diagnostic Reporting:

    • Generates formatted Markdown and dictionary representations summarizing transfer stats, category metrics, and prioritized anomaly tables.

Diagnostic Verification Matrix

  • test_asset_category_from_path: Confirms extension routing for standard web types (.js, .css, .html, .svg, .woff2).
  • test_record_asset_compression_calculation: Asserts exact compression computation, ratio determination, and OK severity.
  • test_record_empty_asset: Confirms zero-byte files are handled gracefully without zero-division errors.
  • test_asset_size_budget_breach: Validates CRITICAL severity flags when assets cross individual ceilings.
  • test_suboptimal_compression_warning: Asserts WARNING severity when compressible categories yield poor compression factors.
  • test_global_bundle_budget_breach: Confirms global bundle warnings when aggregate payload thresholds are breached.
  • test_diagnostic_report_and_reset: Asserts Markdown table rendering and collector memory reset.
============================= 109 passed in 5.61s =============================

@ATLURI0001
ATLURI0001 merged commit 31f0b12 into main Nov 22, 2026
9 checks passed
@ATLURI0001
ATLURI0001 deleted the feat/asset-telemetry-diagnostic branch November 22, 2026 03:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant