@mts-pjsc/bretrics 1.0.6 → 1.0.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +161 -42
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,92 +1,211 @@
|
|
|
1
|
+
# Bretrics
|
|
2
|
+
|
|
1
3
|
[](https://www.codacy.com/gh/LabEG/reca/dashboard?utm_source=github.com&utm_medium=referral&utm_content=LabEG/reca&utm_campaign=Badge_Grade)
|
|
2
|
-
[](https://www.npmjs.com/package/@mts-pjsc/bretrics)
|
|
5
|
+
[](LICENSE)
|
|
3
6
|
[](CODE_OF_CONDUCT.md)
|
|
4
|
-
[](https://github.com/LabEG/reca/blob/main/LICENSE)
|
|
5
7
|
|
|
6
|
-
|
|
8
|
+
A lightweight TypeScript library for Real User Monitoring (RUM) that collects browser performance metrics and sends them to a Prometheus-compatible backend.
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
7
11
|
|
|
8
|
-
|
|
12
|
+
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.
|
|
9
13
|
|
|
10
14
|
## Features
|
|
11
15
|
|
|
12
|
-
- **
|
|
13
|
-
- **Custom Metrics
|
|
14
|
-
- **Business Metrics
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
16
|
+
- **Core Web Vitals**: Collects LCP, CLS, FCP, INP, and TTFB metrics from the [Web Vitals initiative](https://web.dev/vitals/)
|
|
17
|
+
- **Custom Metrics**: Track application-specific performance indicators
|
|
18
|
+
- **Business Metrics**: Monitor conversion funnels and user behavior
|
|
19
|
+
- **Prometheus Labels**: Attach metadata to metrics for detailed analysis
|
|
20
|
+
- **Device Detection**: Automatic classification of desktop, mobile, and tablet devices
|
|
21
|
+
- **Lightweight**: Minimal bundle size with zero runtime dependencies beyond web-vitals
|
|
22
|
+
- **TypeScript**: Full type safety and IntelliSense support
|
|
23
|
+
- **Extensible**: OOP-based architecture allows custom implementations
|
|
17
24
|
|
|
18
25
|
## Installation
|
|
19
26
|
|
|
20
|
-
npm:
|
|
21
|
-
|
|
22
27
|
```bash
|
|
23
28
|
npm install @mts-pjsc/bretrics
|
|
24
29
|
```
|
|
25
30
|
|
|
26
|
-
yarn
|
|
27
|
-
|
|
28
31
|
```bash
|
|
29
32
|
yarn add @mts-pjsc/bretrics
|
|
30
33
|
```
|
|
31
34
|
|
|
32
|
-
|
|
35
|
+
```bash
|
|
36
|
+
pnpm add @mts-pjsc/bretrics
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import { bretrics } from "@mts-pjsc/bretrics";
|
|
43
|
+
|
|
44
|
+
bretrics
|
|
45
|
+
.setup({ apiPath: "/bretrics" })
|
|
46
|
+
.useDefaultMonitoring();
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This configuration enables automatic collection of:
|
|
50
|
+
- Core Web Vitals (LCP, CLS, FCP, INP, TTFB)
|
|
51
|
+
- DOM element count
|
|
52
|
+
- Device type detection
|
|
53
|
+
- Current page path
|
|
33
54
|
|
|
34
|
-
|
|
55
|
+
## Usage
|
|
35
56
|
|
|
36
|
-
|
|
57
|
+
### Basic Configuration
|
|
37
58
|
|
|
38
|
-
```
|
|
39
|
-
import {bretrics} from "@mts-pjsc/bretrics";
|
|
59
|
+
```typescript
|
|
60
|
+
import { bretrics } from "@mts-pjsc/bretrics";
|
|
40
61
|
|
|
41
62
|
bretrics
|
|
42
|
-
.setup({apiPath: "/
|
|
63
|
+
.setup({ apiPath: "/api/metrics" })
|
|
43
64
|
.useDefaultMonitoring()
|
|
44
|
-
.sendMetrics({
|
|
65
|
+
.sendMetrics({ custom_metric: 42 });
|
|
45
66
|
```
|
|
46
67
|
|
|
47
|
-
|
|
68
|
+
### Adding Labels
|
|
48
69
|
|
|
49
|
-
|
|
70
|
+
Labels provide additional context for metric aggregation and filtering in Prometheus.
|
|
50
71
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
``` typescript
|
|
54
|
-
import {bretrics} from "@mts-pjsc/bretrics";
|
|
72
|
+
```typescript
|
|
73
|
+
import { bretrics } from "@mts-pjsc/bretrics";
|
|
55
74
|
|
|
56
75
|
bretrics
|
|
57
|
-
.setup({apiPath: "/bretrics"})
|
|
76
|
+
.setup({ apiPath: "/bretrics" })
|
|
58
77
|
.useDefaultMonitoring()
|
|
59
|
-
.setLabels({
|
|
78
|
+
.setLabels({
|
|
79
|
+
environment: "production",
|
|
80
|
+
version: "2.1.0"
|
|
81
|
+
})
|
|
60
82
|
.sendMetrics({
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
83
|
+
page_load_time: 1250,
|
|
84
|
+
api_response_time: {
|
|
85
|
+
value: 340,
|
|
86
|
+
labels: { endpoint: "/api/users" }
|
|
64
87
|
}
|
|
65
88
|
});
|
|
66
89
|
```
|
|
67
90
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
### Example Bretrics customization
|
|
91
|
+
### Extending the Library
|
|
71
92
|
|
|
72
|
-
|
|
93
|
+
For advanced use cases, extend the `Bretrics` class to implement custom behavior.
|
|
73
94
|
|
|
74
|
-
```
|
|
75
|
-
import {Bretrics} from "@mts-pjsc/bretrics";
|
|
95
|
+
```typescript
|
|
96
|
+
import { Bretrics } from "@mts-pjsc/bretrics";
|
|
76
97
|
|
|
77
|
-
export class
|
|
98
|
+
export class CustomMetricsService extends Bretrics {
|
|
78
99
|
|
|
79
|
-
public override sendMetrics
|
|
80
|
-
|
|
100
|
+
public override sendMetrics(metrics: Record<string, number>): this {
|
|
101
|
+
// Add preprocessing logic
|
|
102
|
+
const enrichedMetrics = this.enrichMetrics(metrics);
|
|
81
103
|
|
|
82
|
-
|
|
104
|
+
super.sendMetrics(enrichedMetrics);
|
|
83
105
|
|
|
84
106
|
return this;
|
|
85
107
|
}
|
|
86
108
|
|
|
109
|
+
private enrichMetrics(metrics: Record<string, number>): Record<string, number> {
|
|
110
|
+
return {
|
|
111
|
+
...metrics,
|
|
112
|
+
timestamp: Date.now()
|
|
113
|
+
};
|
|
114
|
+
}
|
|
87
115
|
}
|
|
116
|
+
|
|
117
|
+
export const metricsService = new CustomMetricsService();
|
|
88
118
|
```
|
|
89
119
|
|
|
120
|
+
## API Reference
|
|
121
|
+
|
|
122
|
+
### Class: Bretrics
|
|
123
|
+
|
|
124
|
+
#### Properties
|
|
125
|
+
|
|
126
|
+
| Property | Type | Default | Description |
|
|
127
|
+
|----------|------|---------|-------------|
|
|
128
|
+
| `apiPath` | `string` | `"/bretrics"` | Endpoint path for metrics submission |
|
|
129
|
+
| `labels` | `Record<string, number \| string>` | `{}` | Default labels applied to all metrics |
|
|
130
|
+
|
|
131
|
+
#### Methods
|
|
132
|
+
|
|
133
|
+
| Method | Returns | Description |
|
|
134
|
+
|--------|---------|-------------|
|
|
135
|
+
| `setup(config)` | `this` | Configure the instance with custom settings |
|
|
136
|
+
| `useDefaultMonitoring()` | `this` | Enable automatic Web Vitals and DOM metrics collection |
|
|
137
|
+
| `useDefaultLabels()` | `this` | Set default labels (device_type, path) |
|
|
138
|
+
| `sendWebVitalsMetrics()` | `this` | Subscribe to Web Vitals events |
|
|
139
|
+
| `sendMetrics(metrics)` | `this` | Send custom metrics to the backend |
|
|
140
|
+
| `setLabels(labels)` | `this` | Add or update metric labels |
|
|
141
|
+
|
|
142
|
+
### Interface: IMetric
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
interface IMetric {
|
|
146
|
+
value: number;
|
|
147
|
+
labels: Record<string, number | string>;
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Collected Metrics
|
|
152
|
+
|
|
153
|
+
### Core Web Vitals
|
|
154
|
+
|
|
155
|
+
| Metric | Description |
|
|
156
|
+
|--------|-------------|
|
|
157
|
+
| `lcp` | Largest Contentful Paint (ms) |
|
|
158
|
+
| `cls` | Cumulative Layout Shift (score) |
|
|
159
|
+
| `fcp` | First Contentful Paint (ms) |
|
|
160
|
+
| `inp` | Interaction to Next Paint (ms) |
|
|
161
|
+
| `ttfb` | Time to First Byte (ms) |
|
|
162
|
+
|
|
163
|
+
### Default Metrics
|
|
164
|
+
|
|
165
|
+
| Metric | Description |
|
|
166
|
+
|--------|-------------|
|
|
167
|
+
| `elements_count` | Total DOM elements on page load |
|
|
168
|
+
|
|
169
|
+
### Default Labels
|
|
170
|
+
|
|
171
|
+
| Label | Description |
|
|
172
|
+
|-------|-------------|
|
|
173
|
+
| `device_type` | Device category: desktop, mobile, or tablet |
|
|
174
|
+
| `path` | Current page pathname |
|
|
175
|
+
|
|
176
|
+
## Backend Integration
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
A ready-to-use backend microservice for collecting and exposing metrics to Prometheus is available at [MobileTeleSystems/bretrics](https://github.com/MobileTeleSystems/bretrics).
|
|
181
|
+
|
|
182
|
+
Example payload:
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
{
|
|
186
|
+
"lcp": {
|
|
187
|
+
"value": 2500,
|
|
188
|
+
"labels": {
|
|
189
|
+
"device_type": "mobile",
|
|
190
|
+
"path": "/products"
|
|
191
|
+
}
|
|
192
|
+
},
|
|
193
|
+
"custom_metric": 42
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Browser Support
|
|
198
|
+
|
|
199
|
+
Bretrics supports all modern browsers. The library uses `navigator.sendBeacon` when available, with a `fetch` fallback for older browsers.
|
|
200
|
+
|
|
201
|
+
## Contributing
|
|
202
|
+
|
|
203
|
+
Contributions are welcome. Please read the [Contributing Guide](CONTRIBUTING.md) before submitting a pull request.
|
|
204
|
+
|
|
90
205
|
## License
|
|
91
206
|
|
|
92
|
-
|
|
207
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
208
|
+
|
|
209
|
+
## Related Projects
|
|
210
|
+
|
|
211
|
+
- [web-vitals](https://github.com/GoogleChrome/web-vitals) - Library for measuring Web Vitals metrics
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mts-pjsc/bretrics",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.10",
|
|
4
4
|
"description": "Web Monitoring",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"type": "module",
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"test:module": "node ./dist/index.js",
|
|
21
21
|
"release": "cliff-jumper --name '@mts-pjsc/bretrics' --package-path '.' --no-skip-changelog --no-skip-tag",
|
|
22
22
|
"prepublishOnly": "npm run test && npm run build",
|
|
23
|
-
"prepare": "husky
|
|
23
|
+
"prepare": "husky"
|
|
24
24
|
},
|
|
25
25
|
"keywords": [
|
|
26
26
|
"metrics",
|