Bretrics

A lightweight TypeScript library for Real User Monitoring (RUM) that collects browser performance metrics and sends them to a Prometheus-compatible backend.

Overview

Bretrics enables you to monitor the performance of your web applications from the perspective of real users. It collects Core Web Vitals, custom performance metrics, and business metrics, then transmits them to your metrics collection endpoint using the efficient navigator.sendBeacon API.

Features

• Core Web Vitals: Collects LCP, CLS, FCP, INP, and TTFB metrics from the Web Vitals initiative
• Custom Metrics: Track application-specific performance indicators
• Business Metrics: Monitor conversion funnels and user behavior
• Prometheus Labels: Attach metadata to metrics for detailed analysis
• Device Detection: Automatic classification of desktop, mobile, and tablet devices
• Lightweight: Minimal bundle size with zero runtime dependencies beyond web-vitals
• TypeScript: Full type safety and IntelliSense support
• Extensible: OOP-based architecture allows custom implementations

Installation

npm install @mts-pjsc/bretrics

yarn add @mts-pjsc/bretrics

pnpm add @mts-pjsc/bretrics

Quick Start

import { bretrics } from "@mts-pjsc/bretrics";

bretrics
    .setup({ apiPath: "/bretrics" })
    .useDefaultMonitoring();

This configuration enables automatic collection of:

• Core Web Vitals (LCP, CLS, FCP, INP, TTFB)
• DOM element count
• Device type detection
• Current page path

Usage

Basic Configuration

import { bretrics } from "@mts-pjsc/bretrics";

bretrics
    .setup({ apiPath: "/api/metrics" })
    .useDefaultMonitoring()
    .sendMetrics({ custom_metric: 42 });

Adding Labels

Labels provide additional context for metric aggregation and filtering in Prometheus.

import { bretrics } from "@mts-pjsc/bretrics";

bretrics
    .setup({ apiPath: "/bretrics" })
    .useDefaultMonitoring()
    .setLabels({
        environment: "production",
        version: "2.1.0"
    })
    .sendMetrics({
        page_load_time: 1250,
        api_response_time: {
            value: 340,
            labels: { endpoint: "/api/users" }
        }
    });

Extending the Library

For advanced use cases, extend the Bretrics class to implement custom behavior.

import { Bretrics } from "@mts-pjsc/bretrics";

export class CustomMetricsService extends Bretrics {

    public override sendMetrics(metrics: Record<string, number>): this {
        // Add preprocessing logic
        const enrichedMetrics = this.enrichMetrics(metrics);

        super.sendMetrics(enrichedMetrics);

        return this;
    }

    private enrichMetrics(metrics: Record<string, number>): Record<string, number> {
        return {
            ...metrics,
            timestamp: Date.now()
        };
    }
}

export const metricsService = new CustomMetricsService();

API Reference

Class: Bretrics

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | apiPath | string | "/bretrics" | Endpoint path for metrics submission | | labels | Record<string, number \| string> | {} | Default labels applied to all metrics |

Methods

| Method | Returns | Description | |--------|---------|-------------| | setup(config) | this | Configure the instance with custom settings | | useDefaultMonitoring() | this | Enable automatic Web Vitals and DOM metrics collection | | useDefaultLabels() | this | Set default labels (device_type, path) | | sendWebVitalsMetrics() | this | Subscribe to Web Vitals events | | sendMetrics(metrics) | this | Send custom metrics to the backend | | setLabels(labels) | this | Add or update metric labels |

Interface: IMetric

interface IMetric {
    value: number;
    labels: Record<string, number | string>;
}

Collected Metrics

Core Web Vitals

| Metric | Description | |--------|-------------| | lcp | Largest Contentful Paint (ms) | | cls | Cumulative Layout Shift (score) | | fcp | First Contentful Paint (ms) | | inp | Interaction to Next Paint (ms) | | ttfb | Time to First Byte (ms) |

Default Metrics

| Metric | Description | |--------|-------------| | elements_count | Total DOM elements on page load |

Default Labels

| Label | Description | |-------|-------------| | device_type | Device category: desktop, mobile, or tablet | | path | Current page pathname |

Backend Integration

Bretrics sends metrics via HTTP POST to {apiPath}/send-metrics/metrics. The request body contains a JSON object with metric names as keys and values or IMetric objects.

A ready-to-use backend microservice for collecting and exposing metrics to Prometheus is available at MobileTeleSystems/bretrics.

Example payload:

{
    "lcp": {
        "value": 2500,
        "labels": {
            "device_type": "mobile",
            "path": "/products"
        }
    },
    "custom_metric": 42
}

Browser Support

Bretrics supports all modern browsers. The library uses navigator.sendBeacon when available, with a fetch fallback for older browsers.

Contributing

Contributions are welcome. Please read the Contributing Guide before submitting a pull request.

License

This project is licensed under the MIT License.

Related Projects

• web-vitals - Library for measuring Web Vitals metrics