0
# prom-client
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: prom-client
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install prom-client`
10

11
## Core Imports
12

13
```typescript
14
import { Counter, Gauge, Histogram, Summary, register } from "prom-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Counter, Gauge, Histogram, Summary, register } = require("prom-client");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Counter, Gauge, register, collectDefaultMetrics } from "prom-client";
27

28
// Collect default Node.js metrics
29
collectDefaultMetrics();
30

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

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

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

47
// Set gauge value
48
activeConnections.set(42);
49

50
// Get all metrics in Prometheus format
51
const metrics = await register.metrics();
52
console.log(metrics);
53
```
54

55
## Architecture
56

57
prom-client is built around several key components:
58

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

66
## Capabilities
67

68
### Metric Types
69

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

72
```typescript { .api }
73
class Counter<T extends string = string> {
74
  constructor(configuration: CounterConfiguration<T>);
75
  inc(labels?: LabelValues<T>, value?: number): void;
76
  inc(value?: number): void;
77
  get(): Promise<MetricObjectWithValues<MetricValue<T>>>;
78
}
79

80
class Gauge<T extends string = string> {
81
  constructor(configuration: GaugeConfiguration<T>);
82
  inc(labels?: LabelValues<T>, value?: number): void;
83
  dec(labels?: LabelValues<T>, value?: number): void;
84
  set(labels?: LabelValues<T>, value: number): void;
85
  get(): Promise<MetricObjectWithValues<MetricValue<T>>>;
86
}
87

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

94
class Summary<T extends string = string> {
95
  constructor(configuration: SummaryConfiguration<T>);
96
  observe(labels?: LabelValues<T>, value: number): void;
97
  get(): Promise<MetricObjectWithValues<MetricValueWithName<T>>>;
98
}
99
```
100

101
[Metric Types](./metrics.md)
102

103
### Registry Management
104

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

107
```typescript { .api }
108
class Registry<BoundRegistryContentType extends RegistryContentType = PrometheusContentType> {
109
  constructor(regContentType?: BoundRegistryContentType);
110
  metrics(): Promise<string>;
111
  registerMetric<T extends string>(metric: Metric<T>): void;
112
  getMetricsAsJSON(): Promise<MetricObjectWithValues<MetricValue<string>>[]>;
113
  clear(): void;
114
  resetMetrics(): void;
115
}
116

117
const register: Registry;
118
```
119

120
[Registry Management](./registry.md)
121

122
### Default Metrics Collection
123

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

126
```typescript { .api }
127
const collectDefaultMetrics: {
128
  <T extends RegistryContentType>(config?: DefaultMetricsCollectorConfiguration<T>): void;
129
  metricsList: string[];
130
};
131

132
interface DefaultMetricsCollectorConfiguration<T extends RegistryContentType> {
133
  register?: Registry<T>;
134
  prefix?: string;
135
  gcDurationBuckets?: number[];
136
  eventLoopMonitoringPrecision?: number;
137
  labels?: object;
138
}
139
```
140

141
[Default Metrics](./default-metrics.md)
142

143
### Pushgateway Integration
144

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

147
```typescript { .api }
148
class Pushgateway<T extends RegistryContentType> {
149
  constructor(url: string, options?: any, registry?: Registry<T>);
150
  pushAdd(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
151
  push(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
152
  delete(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }>;
153
}
154
```
155

156
[Pushgateway](./pushgateway.md)
157

158
### Cluster Support
159

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

162
```typescript { .api }
163
class AggregatorRegistry<T extends RegistryContentType> extends Registry<T> {
164
  clusterMetrics(): Promise<string>;
165
  static aggregate<T extends RegistryContentType>(metricsArr: Array<object>): Registry<T>;
166
  static setRegistries(regs: Array<Registry> | Registry): void;
167
}
168

169
const aggregators: {
170
  sum: (values: number[]) => number;
171
  first: (values: number[]) => number;
172
  min: (values: number[]) => number;
173
  max: (values: number[]) => number;
174
  average: (values: number[]) => number;
175
  omit: (values: number[]) => undefined;
176
};
177
```
178

179
[Cluster Support](./cluster.md)
180

181
## Utility Functions
182

183
```typescript { .api }
184
function validateMetricName(name: string): boolean;
185
function validateLabelName(names?: string[]): boolean;
186
function validateLabel(savedLabels: string[], labels: object): void;
187
function linearBuckets(start: number, width: number, count: number): number[];
188
function exponentialBuckets(start: number, factor: number, count: number): number[];
189

190
const prometheusContentType: PrometheusContentType;
191
const openMetricsContentType: OpenMetricsContentType;
192

193
// Advanced aggregation utility for custom aggregator functions
194
const AggregatorFactory: (aggregatorFn: Function) => Function;
195
```
196

197
## Core Types
198

199
```typescript { .api }
200
type LabelValues<T extends string> = Partial<Record<T, string | number>>;
201

202
interface MetricConfiguration<T extends string> {
203
  name: string;
204
  help: string;
205
  labelNames?: T[] | readonly T[];
206
  registers?: Registry[];
207
  aggregator?: Aggregator;
208
  collect?: CollectFunction<any>;
209
}
210

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

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

217
class Exemplar {
218
  labelSet: object;
219
  value: number;
220
  timestamp?: number;
221
  constructor(labelSet?: object, value?: number);
222
  validateExemplarLabelSet(labelSet: object): void;
223
}
224
```