Prometheus client_js: Thư Viện Metrics Node.js

Tìm Hiểu Về Prometheus Client Cho Node.js

Prometheus client for Node.js chính là prometheus/client_js, một thư viện JavaScript dưới tổ chức GitHub Prometheus, triển khai bốn loại metric cốt lõi — Counter, Gauge, Histogram và Summary — cùng một registry định dạng chúng thành text sẵn sàng cho scrape. Nó không tự khởi chạy HTTP server; bạn tự quyết định route `/metrics` được phục vụ ra sao. Nó cũng hiểu module `cluster` của Node.js và có thể xuất OpenMetrics lẫn định dạng cổ điển.

Tính Năng Cốt Lõi Để Giám Sát Ứng Dụng Node.js

• ✓Bốn loại metric của Prometheus — Counter (`inc()`), Gauge (`set()`/`inc()`/`dec()`/`setToCurrentTime()`), Histogram (`observe()` với bucket có thể cấu hình), và Summary (`observe()` với percentile có thể cấu hình cùng một sliding time window tùy chọn qua `maxAgeSeconds`/`ageBuckets`).
• ✓`collectDefaultMetrics()` thu thập các metric mà chính Prometheus khuyến nghị, cộng thêm các metric đặc thù Node.js — event loop lag, active handles, garbage collection, phiên bản Node.js — với các tùy chọn cấu hình như `prefix`, `gcDurationBuckets`, và `eventLoopMonitoringPrecision`.
• ✓Gộp metrics theo cluster qua `ClusterRegistry` và `AggregatorRegistry`, để `register.clusterMetrics()` gộp số liệu từ mọi worker thay vì một lần scrape chỉ chạm được tới một process.
• ✓Hỗ trợ label với ba cú pháp tương đương để gán giá trị có label, timer nhận biết label, và một hàm `zero()` để đăng ký trước các tổ hợp label cho histogram trước khi chúng được quan sát.
• ✓Default label theo từng registry qua `register.setDefaultLabels()`, tự động áp dụng cho mọi metric mà registry đó phát ra.
• ✓Định dạng exposition có thể chuyển đổi — text Prometheus cổ điển (0.0.4) hoặc OpenMetrics (1.0.0) — thiết lập theo từng registry bằng `register.setContentType()`.
• ✓Exemplar trên các metric Counter và Histogram, với default metrics tự động điền label exemplar `traceId`/`spanId` khi có OpenTelemetry.
• ✓Một client `Pushgateway` (`pushAdd`, `push`, `delete`) cho các job không thể ngồi chờ để được scrape, cùng các hàm hỗ trợ `linearBuckets()`/`exponentialBuckets()` để cấu hình histogram.

Bắt Đầu Với Prometheus client_js

README không nêu rõ lệnh npm install nào trong phần Usage hay API — mọi ví dụ code đều import thư viện theo cùng một cách, `require('@prometheus-io/client')`, cho biết tên định danh package nhưng không nói rõ câu lệnh cài đặt cụ thể. Nơi README trỏ tới để có một thiết lập hoạt động là thư mục `example/`, được tham chiếu riêng cho cách dùng với cluster và server thay vì mô tả trực tiếp trong văn bản.

Đo Lường Ứng Dụng Node.js Của Bạn Bằng Metrics

Vòng lặp cơ bản là: tạo một metric với `name` và `help` bắt buộc, gọi `.inc()`/`.set()`/`.observe()` trên nó khi code chạy, rồi trả lời request scrape của Prometheus bằng `await registry.metrics()` từ bất kỳ HTTP handler nào bạn đang chạy sẵn — thư viện không đóng gói framework web nào, nên route đó do bạn tự nối dây. Với các giá trị chỉ đọc được tại thời điểm scrape, như mức sử dụng bộ nhớ hiện tại thay vì thứ được tích lũy liên tục, hãy truyền một hàm `collect()` thay vì cập nhật metric theo timer; README nói rõ `collect()` — có thể đồng bộ hoặc bất đồng bộ — được gọi khi registry thu thập giá trị, còn callback `setInterval` không phải chỗ để ghi những cập nhật đó. Label lấy từ mảng `labelNames` trong cấu hình metric, rồi được gán qua `.labels(...).set(...)` hoặc bằng cách truyền một object label làm tham số đầu tiên cho lệnh gọi như `.inc()`. Chạy dưới module `cluster` của Node.js làm thay đổi bức tranh: registry cục bộ của một worker chỉ phản ánh số liệu riêng của worker đó, nên bạn cần khởi tạo `ClusterRegistry` trước khi rẽ nhánh theo `cluster.isPrimary`. Bỏ qua bước này ở một worker khiến worker đó không thể trả lời khi process primary yêu cầu gộp số liệu, nên `clusterMetrics()` sẽ treo cho tới khi hết thời gian chờ. Custom metric mặc định được cộng dồn (sum) qua các worker; đặt `aggregator` trong cấu hình metric thành `'first'`, `'min'`, `'max'`, `'average'`, hoặc `'omit'` khi phép cộng dồn không phải tổ hợp phù hợp cho metric đó.

Lựa Chọn Thay Thế Để Thu Thập Metrics Cho Node.js

Câu Hỏi Thường Gặp

Vấn đề nó giải quyết

Một process Node.js chạy chậm hoặc lỗi khi tải cao sẽ không tự nói cho bạn biết lý do, trừ khi có thứ gì đó bên trong đang đếm số request, đo thời gian xử lý, và theo dõi bộ nhớ cùng sức khỏe event loop theo định dạng mà hệ thống giám sát của bạn scrape được. Tự tay xây lớp đo lường đó — chọn ranh giới bucket cho histogram, tự định dạng text exposition của Prometheus, đảm bảo Counter không bao giờ giảm ngược — rất dễ sai ở những chi tiết nhỏ. prometheus/client_js tồn tại để chuẩn hoá lớp đo lường đó thay vì để mỗi team tự nghĩ ra quy ước đặt tên và định dạng metric riêng.

Trường hợp sử dụng tốt nhất

• •Đo lường một HTTP API Node.js bằng Counter đếm số request và Histogram đo thời gian xử lý request, để một Prometheus server scrape theo chu kỳ.
• •Gộp metrics trên một triển khai `cluster` Node.js, nơi mỗi worker vốn chỉ tự phơi bày số liệu cục bộ của riêng nó.
• •Liên kết metrics với distributed trace bằng cách gắn exemplar vào Counter và Histogram khi OpenTelemetry đã điền sẵn trace ID và span ID.
• •Đẩy metrics từ các job batch hoặc cron chạy ngắn hạn tới Pushgateway thay vì phải duy trì một process sống lâu để Prometheus scrape.
• •Chuyển một registry từ định dạng text Prometheus cổ điển sang OpenMetrics mà không cần viết lại phần code tạo ra giá trị metric.

Ai nên dùng — và ai nên bỏ qua

Hãy thử Prometheus client for Node.js nếu bạn đã chạy Prometheus, hoặc bất kỳ hệ thống nào tương thích OpenMetrics, và muốn có các loại Counter/Gauge/Histogram/Summary thực sự cùng cơ chế gộp cluster hoạt động được, thay vì tự tay định dạng text exposition. Bỏ qua nếu bạn không muốn tự sở hữu route HTTP `/metrics` và một scrape target — một agent APM trọn gói tự đi kèm bộ thu thập và dashboard sẽ cho bạn khả năng quan sát với ít công sức thiết lập hơn, đổi lại là dữ liệu của bạn gắn chặt với vendor đó.

Repo liên quan