0
# Default Metrics
1

2
prom-client provides automated collection of Node.js runtime metrics that are recommended by Prometheus for monitoring application health. These metrics include CPU usage, memory consumption, event loop lag, garbage collection statistics, and other process-level information.
3

4
## Capabilities
5

6
### Default Metrics Collection
7

8
The `collectDefaultMetrics` function automatically sets up collection of standard Node.js runtime metrics. Metrics are collected on scrape (when `registry.metrics()` is called), not on an interval.
9

10
```typescript { .api }
11
/**
12
 * Configure default metrics collection
13
 */
14
const collectDefaultMetrics: {
15
  /**
16
   * Configure default metrics
17
   * @param config Configuration object for default metrics collector
18
   */
19
  <T extends RegistryContentType>(
20
    config?: DefaultMetricsCollectorConfiguration<T>
21
  ): void;
22
  /** All available default metrics */
23
  metricsList: string[];
24
};
25

26
interface DefaultMetricsCollectorConfiguration<T extends RegistryContentType> {
27
  register?: Registry<T>;
28
  prefix?: string;
29
  gcDurationBuckets?: number[];
30
  eventLoopMonitoringPrecision?: number;
31
  labels?: object;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { collectDefaultMetrics, register, Registry } from "prom-client";
39

40
// Collect default metrics with default configuration
41
collectDefaultMetrics();
42

43
// Collect default metrics with custom configuration
44
collectDefaultMetrics({
45
  prefix: "myapp_",
46
  labels: { service: "api-server", version: "1.0.0" },
47
  eventLoopMonitoringPrecision: 10,
48
});
49

50
// Use a custom registry
51
const customRegistry = new Registry();
52
collectDefaultMetrics({ register: customRegistry });
53

54
// Get all available default metric names
55
console.log(collectDefaultMetrics.metricsList);
56
```
57

58
### Configuration Options
59

60
#### Registry Selection
61

62
By default, metrics are registered to the global registry. You can specify a custom registry to keep default metrics separate from application metrics.
63

64
```typescript
65
import { collectDefaultMetrics, Registry } from "prom-client";
66

67
const metricsRegistry = new Registry();
68
collectDefaultMetrics({ register: metricsRegistry });
69

70
// Only default metrics will be in this registry
71
const defaultMetrics = await metricsRegistry.metrics();
72
```
73

74
#### Metric Name Prefixing
75

76
Add a prefix to all default metric names to avoid naming conflicts or to group metrics by application.
77

78
```typescript
79
import { collectDefaultMetrics } from "prom-client";
80

81
// All default metrics will be prefixed with "myservice_"
82
collectDefaultMetrics({ prefix: "myservice_" });
83

84
// Results in metrics like:
85
// myservice_process_cpu_user_seconds_total
86
// myservice_nodejs_heap_size_total_bytes
87
// myservice_nodejs_eventloop_lag_seconds
88
```
89

90
#### Generic Labels
91

92
Apply common labels to all default metrics, useful for multi-service environments or deployment tagging.
93

94
```typescript
95
import { collectDefaultMetrics } from "prom-client";
96

97
collectDefaultMetrics({
98
  labels: {
99
    service: "user-api",
100
    environment: "production",
101
    region: "us-west-2",
102
    instance: process.env.HOSTNAME,
103
  },
104
});
105
```
106

107
#### Garbage Collection Buckets
108

109
Customize the histogram buckets for garbage collection duration metrics.
110

111
```typescript
112
import { collectDefaultMetrics, linearBuckets } from "prom-client";
113

114
// Default GC buckets: [0.001, 0.01, 0.1, 1, 2, 5]
115
collectDefaultMetrics({
116
  gcDurationBuckets: linearBuckets(0.001, 0.001, 10), // More granular buckets
117
});
118
```
119

120
#### Event Loop Monitoring Precision
121

122
Configure the sampling rate for event loop lag monitoring in milliseconds.
123

124
```typescript
125
import { collectDefaultMetrics } from "prom-client";
126

127
collectDefaultMetrics({
128
  eventLoopMonitoringPrecision: 5, // Check every 5ms (more precise but higher overhead)
129
});
130
```
131

132
### Available Default Metrics
133

134
The `metricsList` property contains all available default metric names:
135

136
```typescript { .api }
137
/**
138
 * All available default metrics
139
 */
140
metricsList: string[];
141
```
142

143
**Default metrics include:**
144

145
- **Process CPU Usage**: `process_cpu_user_seconds_total`, `process_cpu_system_seconds_total`
146
- **Process Start Time**: `process_start_time_seconds`
147
- **Process File Descriptors**: `process_open_fds`, `process_max_fds` (Linux only)
148
- **Event Loop Lag**: `nodejs_eventloop_lag_seconds`, `nodejs_eventloop_lag_min_seconds`, `nodejs_eventloop_lag_max_seconds`, `nodejs_eventloop_lag_mean_seconds`, `nodejs_eventloop_lag_stddev_seconds`, `nodejs_eventloop_lag_p50_seconds`, `nodejs_eventloop_lag_p90_seconds`, `nodejs_eventloop_lag_p99_seconds`
149
- **Process Handles**: `nodejs_active_handles`, `nodejs_active_handles_total`
150
- **Process Requests**: `nodejs_active_requests`, `nodejs_active_requests_total`
151
- **Heap Memory**: `nodejs_heap_size_total_bytes`, `nodejs_heap_size_used_bytes`, `nodejs_external_memory_bytes`
152
- **Heap Spaces**: `nodejs_heap_space_size_total_bytes`, `nodejs_heap_space_size_used_bytes`, `nodejs_heap_space_size_available_bytes`
153
- **Node.js Version**: `nodejs_version_info`
154
- **Garbage Collection**: `nodejs_gc_duration_seconds`
155
- **OS Memory**: `process_resident_memory_bytes`, `process_virtual_memory_bytes`, `process_heap_bytes` (Linux only)
156
- **Process Resources**: `nodejs_active_resources`, `nodejs_active_resources_total` (if available)
157

158
**Usage Example:**
159

160
```typescript
161
import { collectDefaultMetrics } from "prom-client";
162

163
// Enable default metrics
164
collectDefaultMetrics();
165

166
// List all available default metrics
167
console.log("Available default metrics:");
168
collectDefaultMetrics.metricsList.forEach(metricName => {
169
  console.log(`- ${metricName}`);
170
});
171
```
172

173
### Platform-Specific Metrics
174

175
Some metrics are only available on specific platforms:
176

177
- **Linux-only metrics**: File descriptor metrics (`process_open_fds`, `process_max_fds`) and OS memory heap metrics
178
- **Node.js version-dependent**: Process resources metrics are only available if `process.getActiveResourcesInfo` function exists
179

180
### Performance Considerations
181

182
Default metrics collection is designed to be lightweight:
183

184
- Metrics are collected on-demand when `registry.metrics()` is called
185
- No background timers or intervals are created
186
- Event loop monitoring can be tuned via `eventLoopMonitoringPrecision`
187
- GC metrics use native V8 hooks for minimal overhead
188

189
**Example with performance tuning:**
190

191
```typescript
192
import { collectDefaultMetrics } from "prom-client";
193

194
// Optimize for high-throughput applications
195
collectDefaultMetrics({
196
  eventLoopMonitoringPrecision: 100, // Less frequent sampling
197
  gcDurationBuckets: [0.001, 0.01, 0.1, 1, 5], // Fewer buckets
198
});
199
```
200

201
### Integration with Web Frameworks
202

203
```typescript
204
import express from "express";
205
import { collectDefaultMetrics, register } from "prom-client";
206

207
const app = express();
208

209
// Enable default metrics collection
210
collectDefaultMetrics();
211

212
// Expose metrics endpoint
213
app.get("/metrics", async (req, res) => {
214
  res.set("Content-Type", register.contentType);
215
  const metrics = await register.metrics();
216
  res.end(metrics);
217
});
218

219
app.listen(3000);
220
```
221

222
## Types
223

224
```typescript { .api }
225
interface DefaultMetricsCollectorConfiguration<T extends RegistryContentType> {
226
  register?: Registry<T>;
227
  prefix?: string;
228
  gcDurationBuckets?: number[];
229
  eventLoopMonitoringPrecision?: number;
230
  labels?: object;
231
}
232

233
type RegistryContentType = PrometheusContentType | OpenMetricsContentType;
234
```