prom client
v15.1.3
Klien prometheus untuk Node.js yang mendukung histogram, ringkasan, pengukur, dan penghitung.
Lihat contoh folder untuk contoh penggunaan. Perpustakaan tidak menggabungkan kerangka web apa pun. Untuk mengekspos metrik, tanggapi permintaan scrape Prometheus dengan hasil await registry.metrics() .
cluster Node.js Modul cluster Node.js memunculkan banyak proses dan menyerahkan koneksi soket ke pekerja tersebut. Mengembalikan metrik dari registri lokal pekerja hanya akan mengungkapkan metrik pekerja individual tersebut, yang umumnya tidak diinginkan. Untuk mengatasi hal ini, Anda dapat menggabungkan semua metrik pekerja dalam proses master. Lihat example/cluster.js sebagai contoh.
Metrik default menggunakan metode agregasi yang masuk akal. (Namun, perlu diperhatikan bahwa rata-rata dan persentil jeda loop peristiwa dirata-ratakan, yang tidak sepenuhnya akurat.) Metrik khusus dijumlahkan di seluruh pekerja secara default. Untuk menggunakan metode agregasi yang berbeda, setel properti aggregator di konfigurasi metrik ke salah satu 'jumlah', 'pertama', 'min', 'maks', 'rata-rata', atau 'hilangkan'. (Lihat lib/metrics/version.js sebagai contoh.)
Jika Anda perlu mengekspos metrik tentang masing-masing pekerja, Anda dapat menyertakan nilai yang unik untuk pekerja tersebut (seperti ID pekerja atau ID proses) dalam label. (Lihat example/server.js untuk contoh worker_${cluster.worker.id} sebagai nilai label.)
Metrik dikumpulkan dari registri global secara default. Untuk menggunakan registri yang berbeda, panggil client.AggregatorRegistry.setRegistries(registryOrArrayOfRegistries) dari proses pekerja.
Ada beberapa metrik default yang direkomendasikan oleh Prometheus sendiri. Untuk mengumpulkannya, hubungi collectDefaultMetrics . Selain itu, beberapa metrik khusus Node.js disertakan, seperti kelambatan loop peristiwa, penanganan aktif, GC, dan versi Node.js. Lihat lib/metrik untuk daftar semua metrik.
CATATAN: Beberapa metrik, mengenai Deskriptor File dan Memori, hanya tersedia di Linux.
collectDefaultMetrics secara opsional menerima objek konfigurasi dengan entri berikut:
prefix awalan opsional untuk nama metrik. Default: tanpa awalan.register ke registri mana metrik harus didaftarkan. Default: registri default global.gcDurationBuckets dengan keranjang khusus untuk histogram durasi GC. Keranjang default histogram durasi GC adalah [0.001, 0.01, 0.1, 1, 2, 5] (dalam detik).eventLoopMonitoringPrecision dengan laju pengambilan sampel dalam milidetik. Harus lebih besar dari nol. Bawaan: 10. Untuk mendaftarkan metrik ke registri lain, teruskan metrik tersebut sebagai register :
const client = require ( 'prom-client' ) ;
const collectDefaultMetrics = client . collectDefaultMetrics ;
const Registry = client . Registry ;
const register = new Registry ( ) ;
collectDefaultMetrics ( { register } ) ; Untuk menggunakan keranjang khusus untuk histogram durasi GC, teruskan sebagai gcDurationBuckets :
const client = require ( 'prom-client' ) ;
const collectDefaultMetrics = client . collectDefaultMetrics ;
collectDefaultMetrics ( { gcDurationBuckets : [ 0.1 , 0.2 , 0.3 ] } ) ; Untuk mengawali nama metrik dengan string arbitrer Anda sendiri, masukkan prefix :
const client = require ( 'prom-client' ) ;
const collectDefaultMetrics = client . collectDefaultMetrics ;
const prefix = 'my_application_' ;
collectDefaultMetrics ( { prefix } ) ; Untuk menerapkan label umum ke semua metrik default, teruskan objek ke properti labels (berguna jika Anda bekerja di lingkungan terklaster):
const client = require ( 'prom-client' ) ;
const collectDefaultMetrics = client . collectDefaultMetrics ;
collectDefaultMetrics ( {
labels : { NODE_APP_INSTANCE : process . env . NODE_APP_INSTANCE } ,
} ) ; Anda bisa mendapatkan daftar lengkap metrik dengan memeriksa client.collectDefaultMetrics.metricsList .
Metrik default dikumpulkan pada titik akhir metrik, bukan pada interval.
const client = require ( 'prom-client' ) ;
const collectDefaultMetrics = client . collectDefaultMetrics ;
collectDefaultMetrics ( ) ; Semua jenis metrik memiliki dua parameter wajib: name dan help . Lihat https://prometheus.io/docs/practices/naming/ untuk panduan tentang penamaan metrik.
Untuk metrik berdasarkan observasi titik waktu (misalnya penggunaan memori saat ini, bukan durasi permintaan HTTP yang diamati terus-menerus dalam histogram), Anda harus menyediakan fungsi collect() , yang akan dipanggil saat Prometheus menghapus titik akhir metrik Anda. collect() bisa sinkron atau mengembalikan janji. Lihat Gauge di bawah untuk contohnya. (Perhatikan bahwa Anda tidak boleh memperbarui nilai metrik dalam callback setInterval ; lakukan hal tersebut di fungsi collect ini.)
Lihat Label untuk informasi tentang cara mengonfigurasi label untuk semua jenis metrik.
Penghitung naik, dan direset ketika proses dimulai ulang.
const client = require ( 'prom-client' ) ;
const counter = new client . Counter ( {
name : 'metric_name' ,
help : 'metric_help' ,
} ) ;
counter . inc ( ) ; // Increment by 1
counter . inc ( 10 ) ; // Increment by 10 Pengukur mirip dengan Penghitung tetapi nilai Pengukur dapat dikurangi.
const client = require ( 'prom-client' ) ;
const gauge = new client . Gauge ( { name : 'metric_name' , help : 'metric_help' } ) ;
gauge . set ( 10 ) ; // Set to 10
gauge . inc ( ) ; // Increment 1
gauge . inc ( 10 ) ; // Increment 10
gauge . dec ( ) ; // Decrement by 1
gauge . dec ( 10 ) ; // Decrement by 10 Jika pengukur digunakan untuk observasi titik waktu, Anda harus menyediakan fungsi collect :
const client = require ( 'prom-client' ) ;
new client . Gauge ( {
name : 'metric_name' ,
help : 'metric_help' ,
collect ( ) {
// Invoked when the registry collects its metrics' values.
// This can be synchronous or it can return a promise/be an async function.
this . set ( /* the current value */ ) ;
} ,
} ) ; // Async version:
const client = require ( 'prom-client' ) ;
new client . Gauge ( {
name : 'metric_name' ,
help : 'metric_help' ,
async collect ( ) {
// Invoked when the registry collects its metrics' values.
const currentValue = await somethingAsync ( ) ;
this . set ( currentValue ) ;
} ,
} ) ; Perhatikan bahwa Anda tidak boleh menggunakan fungsi panah untuk collect karena fungsi panah tidak akan memiliki nilai yang benar untuk this .
// Set value to current time in seconds:
gauge . setToCurrentTime ( ) ;
// Record durations:
const end = gauge . startTimer ( ) ;
http . get ( 'url' , res => {
end ( ) ;
} ) ; Histogram melacak ukuran dan frekuensi kejadian.
Bucket default dimaksudkan untuk mencakup permintaan web/RPC biasa, namun dapat diganti. (Lihat juga Generator Bucket .)
const client = require ( 'prom-client' ) ;
new client . Histogram ( {
name : 'metric_name' ,
help : 'metric_help' ,
buckets : [ 0.1 , 5 , 15 , 50 , 100 , 500 ] ,
} ) ; const client = require ( 'prom-client' ) ;
const histogram = new client . Histogram ( {
name : 'metric_name' ,
help : 'metric_help' ,
} ) ;
histogram . observe ( 10 ) ; // Observe value in histogram const end = histogram . startTimer ( ) ;
xhrRequest ( function ( err , res ) {
const seconds = end ( ) ; // Observes and returns the value to xhrRequests duration in seconds
} ) ; Ringkasan menghitung persentil dari nilai yang diamati.
Persentil defaultnya adalah: 0,01, 0,05, 0,5, 0,9, 0,95, 0,99, 0,999. Tapi mereka bisa ditimpa dengan menentukan array percentiles . (Lihat juga Generator Bucket .)
const client = require ( 'prom-client' ) ;
new client . Summary ( {
name : 'metric_name' ,
help : 'metric_help' ,
percentiles : [ 0.01 , 0.1 , 0.9 , 0.99 ] ,
} ) ; Untuk mengaktifkan fungsionalitas jendela geser untuk ringkasan, Anda perlu menambahkan maxAgeSeconds dan ageBuckets ke konfigurasi seperti ini:
const client = require ( 'prom-client' ) ;
new client . Summary ( {
name : 'metric_name' ,
help : 'metric_help' ,
maxAgeSeconds : 600 ,
ageBuckets : 5 ,
pruneAgedBuckets : false ,
} ) ; maxAgeSeconds akan memberi tahu berapa umur sebuah bucket sebelum direset dan ageBuckets mengonfigurasi berapa banyak bucket yang akan kita miliki di jendela geser untuk ringkasannya. Jika pruneAgedBuckets false (default), nilai metrik akan selalu ada, meskipun kosong (nilai persentilnya adalah 0 ). Setel pruneAgedBuckets ke true jika Anda tidak ingin mengekspornya saat kosong.
const client = require ( 'prom-client' ) ;
const summary = new client . Summary ( {
name : 'metric_name' ,
help : 'metric_help' ,
} ) ;
summary . observe ( 10 ) ; const end = summary . startTimer ( ) ;
xhrRequest ( function ( err , res ) {
end ( ) ; // Observes the value to xhrRequests duration in seconds
} ) ; Semua metrik dapat menggunakan properti labelNames di objek konfigurasi. Semua nama label yang didukung metrik harus dinyatakan di sini. Ada dua cara untuk menambahkan nilai pada label:
const client = require ( 'prom-client' ) ;
const gauge = new client . Gauge ( {
name : 'metric_name' ,
help : 'metric_help' ,
labelNames : [ 'method' , 'statusCode' ] ,
} ) ;
// 1st version: Set value to 100 with "method" set to "GET" and "statusCode" to "200"
gauge . set ( { method : 'GET' , statusCode : '200' } , 100 ) ;
// 2nd version: Same effect as above
gauge . labels ( { method : 'GET' , statusCode : '200' } ) . set ( 100 ) ;
// 3rd version: And again the same effect as above
gauge . labels ( 'GET' , '200' ) . set ( 100 ) ;Dimungkinkan juga untuk menggunakan pengatur waktu dengan label, sebelum dan sesudah pengatur waktu dibuat:
const end = startTimer ( { method : 'GET' } ) ; // Set method to GET, we don't know statusCode yet
xhrRequest ( function ( err , res ) {
if ( err ) {
end ( { statusCode : '500' } ) ; // Sets value to xhrRequest duration in seconds with statusCode 500
} else {
end ( { statusCode : '200' } ) ; // Sets value to xhrRequest duration in seconds with statusCode 200
}
} ) ; Metrik dengan label tidak dapat diekspor sebelum metrik tersebut diamati setidaknya satu kali karena kemungkinan nilai label tidak diketahui sebelum metrik tersebut diamati.
Untuk histogram, hal ini dapat diselesaikan dengan secara eksplisit memusatkan perhatian pada semua nilai label yang diharapkan:
const histogram = new client . Histogram ( {
name : 'metric_name' ,
help : 'metric_help' ,
buckets : [ 0.1 , 5 , 15 , 50 , 100 , 500 ] ,
labels : [ 'method' ] ,
} ) ;
histogram . zero ( { method : 'GET' } ) ;
histogram . zero ( { method : 'POST' } ) ; TypeScript juga dapat menerapkan nama label menggunakan as const
import * as client from 'prom-client' ;
const counter = new client . Counter ( {
name : 'metric_name' ,
help : 'metric_help' ,
// add `as const` here to enforce label names
labelNames : [ 'method' ] as const ,
} ) ;
// Ok
counter . inc ( { method : 1 } ) ;
// this is an error since `'methods'` is not a valid `labelName`
// @ts-expect-error
counter . inc ( { methods : 1 } ) ; Label statis dapat diterapkan ke setiap metrik yang dikeluarkan oleh registri:
const client = require ( 'prom-client' ) ;
const defaultLabels = { serviceName : 'api-v1' } ;
client . register . setDefaultLabels ( defaultLabels ) ;Ini akan menampilkan metrik dengan cara berikut:
# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes{serviceName="api-v1"} 33853440 1498510040309
Label default akan diganti jika ada konflik nama.
register.clear() akan menghapus label default.
Contoh yang ditentukan dalam spesifikasi OpenMetrics dapat diaktifkan pada tipe metrik Penghitung dan Histogram. Metrik default memiliki dukungan untuk OpenTelemetry, metrik tersebut akan mengisi contoh dengan label {traceId, spanId} dan nilainya yang sesuai.
Format untuk panggilan inc() dan observe() berbeda jika contoh diaktifkan. Mereka mendapatkan satu objek dengan format {labels, value, exemplarLabels} .
Saat menggunakan contoh, registri yang digunakan untuk metrik harus disetel ke tipe OpenMetrics (termasuk registri global atau default jika tidak ada registri yang ditentukan).
Perpustakaan mendukung format Prometheus lama dan format OpenMetrics. Formatnya dapat diatur per registri. Untuk metrik default:
const Prometheus = require ( 'prom-client' ) ;
Prometheus . register . setContentType (
Prometheus . Registry . OPENMETRICS_CONTENT_TYPE ,
) ;Tipe registri yang tersedia saat ini ditentukan oleh tipe konten:
PROMETHEUS_CONTENT_TYPE - versi 0.0.4 dari metrik Prometheus asli, saat ini merupakan jenis registri default.
OPENMETRICS_CONTENT_TYPE - default ke versi 1.0.0 dari standar OpenMetrics.
String HTTP Content-Type untuk setiap jenis registri diekspos pada tingkat modul ( prometheusContentType dan openMetricsContentType ) dan sebagai properti statis pada objek Registry .
Konstanta contentType yang diekspos oleh modul mengembalikan tipe konten default saat membuat registri baru, saat ini defaultnya adalah tipe Prometheus.
Secara default, metrik secara otomatis terdaftar ke registri global (terletak di require('prom-client').register ). Anda dapat mencegah hal ini dengan menentukan registers: [] dalam konfigurasi konstruktor metrik.
Menggunakan registry non-global memerlukan pembuatan instance Registry dan meneruskannya ke dalam registers pada objek konfigurasi metrik. Alternatifnya, Anda dapat meneruskan array registers kosong dan mendaftarkannya secara manual.
Registri memiliki fungsi merge yang memungkinkan Anda mengekspos beberapa registri pada titik akhir yang sama. Jika nama metrik yang sama ada di kedua registri, kesalahan akan terjadi.
Menggabungkan registri dari jenis yang berbeda tidak ditentukan. Pengguna perlu memastikan semua registri yang digunakan memiliki tipe yang sama (versi Prometheus atau OpenMetrics).
const client = require ( 'prom-client' ) ;
const registry = new client . Registry ( ) ;
const counter = new client . Counter ( {
name : 'metric_name' ,
help : 'metric_help' ,
registers : [ registry ] , // specify a non-default registry
} ) ;
const histogram = new client . Histogram ( {
name : 'metric_name' ,
help : 'metric_help' ,
registers : [ ] , // don't automatically register this metric
} ) ;
registry . registerMetric ( histogram ) ; // register metric manually
counter . inc ( ) ;
const mergedRegistries = client . Registry . merge ( [ registry , client . register ] ) ; Jika Anda ingin menggunakan beberapa registri atau registri non-default dengan modul cluster Node.js, Anda perlu mengatur registri/registrasi agar digabungkan dari:
const AggregatorRegistry = client . AggregatorRegistry ;
AggregatorRegistry . setRegistries ( registry ) ;
// or for multiple registries:
AggregatorRegistry . setRegistries ( [ registry1 , registry2 ] ) ; Anda bisa mendapatkan semua metrik dengan menjalankan await register.metrics() , yang akan mengembalikan string dalam format eksposisi Prometheus.
Jika Anda perlu mengeluarkan satu metrik dalam format eksposisi Prometheus, Anda dapat menggunakan await register.getSingleMetricAsString(*name of metric*) , yang akan mengembalikan string untuk digunakan oleh Prometheus.
Jika Anda perlu mendapatkan referensi ke metrik yang didaftarkan sebelumnya, Anda dapat menggunakan register.getSingleMetric(*name of metric*) .
Anda dapat menghapus semua metrik dengan memanggil register.clear() . Anda juga dapat menghapus satu metrik dengan memanggil register.removeSingleMetric(*name of metric*) .
Jika Anda perlu menyetel ulang semua metrik, Anda dapat menggunakan register.resetMetrics() . Metrik akan tetap ada di register dan dapat digunakan tanpa perlu membuat instance lagi, seperti yang perlu Anda lakukan setelah register.clear() .
Anda bisa mendapatkan metrik gabungan untuk semua pekerja di kluster Node.js dengan await register.clusterMetrics() . Metode ini mengembalikan janji yang diselesaikan dengan string metrik yang sesuai untuk digunakan oleh Prometheus.
const metrics = await register . clusterMetrics ( ) ;
// - or -
register
. clusterMetrics ( )
. then ( metrics => {
/* ... */
} )
. catch ( err => {
/* ... */
} ) ;Dimungkinkan untuk mendorong metrik melalui Pushgateway.
const client = require ( 'prom-client' ) ;
let gateway = new client . Pushgateway ( 'http://127.0.0.1:9091' ) ;
gateway . pushAdd ( { jobName : 'test' } )
. then ( ( { resp , body } ) => {
/* ... */
} )
. catch ( err => {
/* ... */
} ) ) ; //Add metric and overwrite old ones
gateway . push ( { jobName : 'test' } )
. then ( ( { resp , body } ) => {
/* ... */
} )
. catch ( err => {
/* ... */
} ) ) ; //Overwrite all metrics (use PUT)
gateway . delete ( { jobName : 'test' } )
. then ( ( { resp , body } ) => {
/* ... */
} )
. catch ( err => {
/* ... */
} ) ) ; //Delete all metrics for jobName
//All gateway requests can have groupings on it
gateway . pushAdd ( { jobName : 'test' , groupings : { key : 'value' } } )
. then ( ( { resp , body } ) => {
/* ... */
} )
. catch ( err => {
/* ... */
} ) )
