0
# Registry Management
1

2
The Registry system in prom-client provides centralized collection, management, and serialization of metrics. It serves as the central store for all metrics and handles their output in Prometheus or OpenMetrics format.
3

4
## Capabilities
5

6
### Registry Class
7

8
The Registry class is the core container for all registered metrics. It manages metric collection, serialization, and provides methods for accessing metrics in various formats.
9

10
```typescript { .api }
11
/**
12
 * Container for all registered metrics
13
 */
14
class Registry<BoundRegistryContentType extends RegistryContentType = PrometheusContentType> {
15
  /**
16
   * Create a new Registry instance
17
   * @param regContentType Content type for metrics output (Prometheus or OpenMetrics)
18
   */
19
  constructor(regContentType?: BoundRegistryContentType);
20

21
  /**
22
   * Get string representation for all metrics
23
   */
24
  metrics(): Promise<string>;
25

26
  /**
27
   * Remove all metrics from the registry
28
   */
29
  clear(): void;
30

31
  /**
32
   * Reset all metrics in the registry
33
   */
34
  resetMetrics(): void;
35

36
  /**
37
   * Register metric to register
38
   * @param metric Metric to add to register
39
   */
40
  registerMetric<T extends string>(metric: Metric<T>): void;
41

42
  /**
43
   * Get all metrics as objects
44
   */
45
  getMetricsAsJSON(): Promise<MetricObjectWithValues<MetricValue<string>>[]>;
46

47
  /**
48
   * Get all metrics as objects
49
   */
50
  getMetricsAsArray(): MetricObject[];
51

52
  /**
53
   * Remove a single metric
54
   * @param name The name of the metric to remove
55
   */
56
  removeSingleMetric(name: string): void;
57

58
  /**
59
   * Get a single metric
60
   * @param name The name of the metric
61
   */
62
  getSingleMetric<T extends string>(name: string): Metric<T> | undefined;
63

64
  /**
65
   * Set static labels to every metric emitted by this registry
66
   * @param labels of name/value pairs:
67
   * { defaultLabel: "value", anotherLabel: "value 2" }
68
   */
69
  setDefaultLabels(labels: object): void;
70

71
  /**
72
   * Get a string representation of a single metric by name
73
   * @param name The name of the metric
74
   */
75
  getSingleMetricAsString(name: string): Promise<string>;
76

77
  /**
78
   * Gets the Content-Type of the metrics for use in the response headers.
79
   */
80
  readonly contentType: BoundRegistryContentType;
81

82
  /**
83
   * Set the content type of a registry. Used to change between Prometheus and
84
   * OpenMetrics versions.
85
   * @param contentType The type of the registry
86
   */
87
  setContentType(contentType: BoundRegistryContentType): void;
88

89
  /**
90
   * Merge registers
91
   * @param registers The registers you want to merge together
92
   */
93
  static merge(registers: Registry[]): Registry;
94

95
  /**
96
   * HTTP Prometheus Content-Type for metrics response headers.
97
   */
98
  static PROMETHEUS_CONTENT_TYPE: PrometheusContentType;
99

100
  /**
101
   * HTTP OpenMetrics Content-Type for metrics response headers.
102
   */
103
  static OPENMETRICS_CONTENT_TYPE: OpenMetricsContentType;
104
}
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { Registry, Counter, Gauge } from "prom-client";
111

112
// Create a custom registry
113
const customRegistry = new Registry();
114

115
// Create metrics and register them to custom registry
116
const requestsCounter = new Counter({
117
  name: "http_requests_total",
118
  help: "Total HTTP requests",
119
  registers: [customRegistry], // Register to custom registry
120
});
121

122
const memoryGauge = new Gauge({
123
  name: "memory_usage_bytes",
124
  help: "Memory usage in bytes",
125
  registers: [customRegistry],
126
});
127

128
// Get metrics as Prometheus format string
129
const prometheusMetrics = await customRegistry.metrics();
130
console.log(prometheusMetrics);
131

132
// Get metrics as JSON objects
133
const metricsJSON = await customRegistry.getMetricsAsJSON();
134
console.log(metricsJSON);
135

136
// Set default labels for all metrics in this registry
137
customRegistry.setDefaultLabels({
138
  service: "api-server",
139
  version: "1.0.0",
140
});
141

142
// Clear all metrics
143
customRegistry.clear();
144
```
145

146
### Global Registry
147

148
The global registry is automatically created and exported as `register`. All metrics are registered to this registry by default unless specified otherwise.
149

150
```typescript { .api }
151
/**
152
 * The register that contains all metrics
153
 */
154
const register: Registry;
155

156
/**
157
 * HTTP Content-Type for metrics response headers for the default registry,
158
 * defaults to Prometheus text format.
159
 */
160
const contentType: RegistryContentType;
161

162
/**
163
 * HTTP Prometheus Content-Type for metrics response headers.
164
 */
165
const prometheusContentType: PrometheusContentType;
166

167
/**
168
 * HTTP OpenMetrics Content-Type for metrics response headers.
169
 */
170
const openMetricsContentType: OpenMetricsContentType;
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
import { register, Counter } from "prom-client";
177

178
// Metrics are automatically registered to the global registry
179
const httpRequests = new Counter({
180
  name: "http_requests_total",
181
  help: "Total HTTP requests",
182
  // No need to specify registers - uses global registry by default
183
});
184

185
// Get all metrics from global registry
186
const metrics = await register.metrics();
187

188
// Set default labels on global registry
189
register.setDefaultLabels({
190
  application: "my-app",
191
  environment: "production",
192
});
193

194
// Get content type
195
console.log(register.contentType); // "text/plain; version=0.0.4; charset=utf-8"
196
```
197

198
### Content Type Management
199

200
Registries support both Prometheus and OpenMetrics output formats. You can configure the content type when creating a registry or change it later.
201

202
```typescript { .api }
203
type RegistryContentType = PrometheusContentType | OpenMetricsContentType;
204
type PrometheusContentType = 'text/plain; version=0.0.4; charset=utf-8';
205
type OpenMetricsContentType = 'application/openmetrics-text; version=1.0.0; charset=utf-8';
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { Registry } from "prom-client";
212

213
// Create registry with Prometheus format (default)
214
const prometheusRegistry = new Registry();
215

216
// Create registry with OpenMetrics format
217
const openMetricsRegistry = new Registry(Registry.OPENMETRICS_CONTENT_TYPE);
218

219
// Change content type after creation
220
prometheusRegistry.setContentType(Registry.OPENMETRICS_CONTENT_TYPE);
221

222
// Check current content type
223
console.log(openMetricsRegistry.contentType);
224
```
225

226
### Registry Merging
227

228
Multiple registries can be merged into a single registry, combining all their metrics.
229

230
```typescript { .api }
231
/**
232
 * Merge registers
233
 * @param registers The registers you want to merge together
234
 */
235
static merge(registers: Registry[]): Registry;
236
```
237

238
**Usage Examples:**
239

240
```typescript
241
import { Registry, Counter } from "prom-client";
242

243
// Create separate registries
244
const registry1 = new Registry();
245
const registry2 = new Registry();
246

247
// Add metrics to each registry
248
new Counter({
249
  name: "requests_total",
250
  help: "Total requests",
251
  registers: [registry1],
252
});
253

254
new Counter({
255
  name: "errors_total", 
256
  help: "Total errors",
257
  registers: [registry2],
258
});
259

260
// Merge registries
261
const mergedRegistry = Registry.merge([registry1, registry2]);
262

263
// The merged registry now contains metrics from both registries
264
const allMetrics = await mergedRegistry.metrics();
265
```
266

267
### Metric Lifecycle Management
268

269
```typescript { .api }
270
/**
271
 * Remove a single metric
272
 * @param name The name of the metric to remove
273
 */
274
removeSingleMetric(name: string): void;
275

276
/**
277
 * Get a single metric
278
 * @param name The name of the metric
279
 */
280
getSingleMetric<T extends string>(name: string): Metric<T> | undefined;
281

282
/**
283
 * Remove all metrics from the registry
284
 */
285
clear(): void;
286

287
/**
288
 * Reset all metrics in the registry
289
 */
290
resetMetrics(): void;
291
```
292

293
**Usage Examples:**
294

295
```typescript
296
import { register, Counter } from "prom-client";
297

298
const httpRequests = new Counter({
299
  name: "http_requests_total",
300
  help: "Total HTTP requests",
301
});
302

303
// Get a specific metric
304
const metric = register.getSingleMetric("http_requests_total");
305
console.log(metric?.help); // "Total HTTP requests"
306

307
// Remove a specific metric
308
register.removeSingleMetric("http_requests_total");
309

310
// Reset all metric values to zero (but keep the metrics registered)
311
register.resetMetrics();
312

313
// Remove all metrics from registry
314
register.clear();
315
```
316

317
## Types
318

319
```typescript { .api }
320
interface MetricObject {
321
  name: string;
322
  help: string;
323
  type: MetricType;
324
  aggregator: Aggregator;
325
  collect: CollectFunction<any>;
326
}
327

328
interface MetricObjectWithValues<T extends MetricValue<string>> extends MetricObject {
329
  values: T[];
330
}
331

332
type Metric<T extends string = string> = Counter<T> | Gauge<T> | Summary<T> | Histogram<T>;
333

334
type Collector = () => void;
335
```