tessl/npm-prom-client

Client for prometheus that provides comprehensive Prometheus metrics collection and exposition for Node.js applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

prom-client

Name: tessl/npm-prom-client
Author: tessl

prom-client is a comprehensive Prometheus client library for Node.js applications that enables developers to create, collect, and expose metrics in the Prometheus format. It supports all standard Prometheus metric types including counters, gauges, histograms, and summaries, with built-in default metrics collection for Node.js runtime statistics.

Package Information

Package Name: prom-client
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install prom-client

Core Imports

import { Counter, Gauge, Histogram, Summary, register } from "prom-client";

For CommonJS:

const { Counter, Gauge, Histogram, Summary, register } = require("prom-client");

Basic Usage

import { Counter, Gauge, register, collectDefaultMetrics } from "prom-client";

// Collect default Node.js metrics
collectDefaultMetrics();

// Create a counter metric
const httpRequestsTotal = new Counter({
  name: "http_requests_total",
  help: "Total number of HTTP requests",
  labelNames: ["method", "status_code"],
});

// Create a gauge metric
const activeConnections = new Gauge({
  name: "active_connections",
  help: "Number of active connections",
});

// Increment counter
httpRequestsTotal.inc({ method: "GET", status_code: "200" });

// Set gauge value
activeConnections.set(42);

// Get all metrics in Prometheus format
const metrics = await register.metrics();
console.log(metrics);

Architecture

prom-client is built around several key components:

Metric Types: Four core metric types (Counter, Gauge, Histogram, Summary) implementing the Prometheus data model
Registry System: Central registry for collecting and managing all metrics with support for multiple registries
Default Metrics: Built-in collection of Node.js runtime metrics (CPU, memory, event loop, GC, etc.)
Cluster Support: Aggregation of metrics across Node.js cluster workers for distributed applications
Push Gateway: Support for pushing metrics to Prometheus Push Gateway for batch jobs
Type Safety: Full TypeScript support with generic type parameters for strongly-typed labels

Capabilities

Metric Types

Core Prometheus metric types for collecting application-specific measurements. Each metric type serves different use cases and provides specific measurement semantics.

class Counter<T extends string = string> {
  constructor(configuration: CounterConfiguration<T>);
  inc(labels?: LabelValues<T>, value?: number): void;
  inc(value?: number): void;
  get(): Promise<MetricObjectWithValues<MetricValue<T>>>;
}

class Gauge<T extends string = string> {
  constructor(configuration: GaugeConfiguration<T>);
  inc(labels?: LabelValues<T>, value?: number): void;
  dec(labels?: LabelValues<T>, value?: number): void;
  set(labels?: LabelValues<T>, value: number): void;
  get(): Promise<MetricObjectWithValues<MetricValue<T>>>;
}

class Histogram<T extends string = string> {
  constructor(configuration: HistogramConfiguration<T>);
  observe(labels?: LabelValues<T>, value: number): void;
  get(): Promise<MetricObjectWithValues<MetricValueWithName<T>>>;
}

class Summary<T extends string = string> {
  constructor(configuration: SummaryConfiguration<T>);
  observe(labels?: LabelValues<T>, value: number): void;
  get(): Promise<MetricObjectWithValues<MetricValueWithName<T>>>;
}

Metric Types

Registry Management

Registry system for collecting, managing, and outputting metrics in Prometheus or OpenMetrics format. Provides centralized metric collection and serialization.

class Registry<BoundRegistryContentType extends RegistryContentType = PrometheusContentType> {
  constructor(regContentType?: BoundRegistryContentType);
  metrics(): Promise<string>;
  registerMetric<T extends string>(metric: Metric<T>): void;
  getMetricsAsJSON(): Promise<MetricObjectWithValues<MetricValue<string>>[]>;
  clear(): void;
  resetMetrics(): void;
}

const register: Registry;

Registry Management

Default Metrics Collection

Automated collection of Node.js runtime metrics including CPU usage, memory consumption, event loop lag, garbage collection statistics, and process information.

const collectDefaultMetrics: {
  <T extends RegistryContentType>(config?: DefaultMetricsCollectorConfiguration<T>): void;
  metricsList: string[];
};

interface DefaultMetricsCollectorConfiguration<T extends RegistryContentType> {
  register?: Registry<T>;
  prefix?: string;
  gcDurationBuckets?: number[];
  eventLoopMonitoringPrecision?: number;
  labels?: object;
}

Default Metrics

Pushgateway Integration

Push metrics to Prometheus Push Gateway for batch jobs, scheduled tasks, and short-lived processes that cannot be scraped directly.

class Pushgateway<T extends RegistryContentType> {
  constructor(url: string, options?: any, registry?: Registry<T>);
  pushAdd(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
  push(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
  delete(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
}

Pushgateway

Cluster Support

Aggregate metrics across Node.js cluster workers, providing consolidated metrics from multiple processes with configurable aggregation strategies.

class AggregatorRegistry<T extends RegistryContentType> extends Registry<T> {
  clusterMetrics(): Promise<string>;
  static aggregate<T extends RegistryContentType>(metricsArr: Array<object>): Registry<T>;
  static setRegistries(regs: Array<Registry> | Registry): void;
}

const aggregators: {
  sum: (values: number[]) => number;
  first: (values: number[]) => number;
  min: (values: number[]) => number;
  max: (values: number[]) => number;
  average: (values: number[]) => number;
  omit: (values: number[]) => undefined;
};

Cluster Support

Utility Functions

function validateMetricName(name: string): boolean;
function validateLabelName(names?: string[]): boolean;
function validateLabel(savedLabels: string[], labels: object): void;
function linearBuckets(start: number, width: number, count: number): number[];
function exponentialBuckets(start: number, factor: number, count: number): number[];

const prometheusContentType: PrometheusContentType;
const openMetricsContentType: OpenMetricsContentType;

// Advanced aggregation utility for custom aggregator functions
const AggregatorFactory: (aggregatorFn: Function) => Function;

Core Types

type LabelValues<T extends string> = Partial<Record<T, string | number>>;

interface MetricConfiguration<T extends string> {
  name: string;
  help: string;
  labelNames?: T[] | readonly T[];
  registers?: Registry[];
  aggregator?: Aggregator;
  collect?: CollectFunction<any>;
}

type Aggregator = 'omit' | 'sum' | 'first' | 'min' | 'max' | 'average';

type RegistryContentType = PrometheusContentType | OpenMetricsContentType;
type PrometheusContentType = 'text/plain; version=0.0.4; charset=utf-8';
type OpenMetricsContentType = 'application/openmetrics-text; version=1.0.0; charset=utf-8';

class Exemplar {
  labelSet: object;
  value: number;
  timestamp?: number;
  constructor(labelSet?: object, value?: number);
  validateExemplarLabelSet(labelSet: object): void;
}

Install with Tessl CLI