@enamul1/frontend-carbon-tracker

A zero-impact telemetry tracker for web browsers. It measures proxy metrics for energy consumption (Network bloat, CPU long tasks, and OLED display luminance) without causing battery drain or blocking the main thread.

Features

• Strict Size Budget: Under 1KB gzipped.
• Zero Runtime Dependencies: B2B production-ready.
• Main Thread Safe: CPU execution is kept under 5ms; background calculations are deferred via requestIdleCallback.
• Browser-Safe Failover: Fails silently and gracefully if performance APIs are unsupported.

Installation

npm install @enamul1/frontend-carbon-tracker

Usage

Initialize the tracker with your telemetry ingestion endpoint:

import CarbonTracker from '@enamul1/frontend-carbon-tracker';

// Initializes the tracker and registers hooks/observers
const tracker = new CarbonTracker('https://your-telemetry-endpoint.com/api');

// Retrieve current in-memory stats programmatically
console.log(tracker.getStats());
// Output: { totalBytes: 1024, longTaskTotalTime: 45, lightModeLuminance: 21 }

How It Works

1. Network Bloat: Listens to 'resource' entries via PerformanceObserver.
2. CPU Long Tasks: Listens to 'longtask' entries via PerformanceObserver.
3. OLED Display Luminance: Calculates root background color luminance (0–100%) on idle callback.
4. Transmission: Buffers data in memory and automatically dispatches it using navigator.sendBeacon when the page visibility changes to hidden.