or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cluster.mddefault-metrics.mdindex.mdmetrics.mdpushgateway.mdregistry.md
tile.json

tessl/npm-prom-client

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/prom-client@15.1.x

To install, run

npx @tessl/cli install tessl/npm-prom-client@15.1.0

index.mddocs/

prom-client

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;
}