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

Default Metrics

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

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.

Capabilities

Default Metrics Collection

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.

/**
 * Configure default metrics collection
 */
const collectDefaultMetrics: {
  /**
   * Configure default metrics
   * @param config Configuration object for default metrics collector
   */
  <T extends RegistryContentType>(
    config?: DefaultMetricsCollectorConfiguration<T>
  ): void;
  /** All available default metrics */
  metricsList: string[];
};

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

Usage Examples:

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

// Collect default metrics with default configuration
collectDefaultMetrics();

// Collect default metrics with custom configuration
collectDefaultMetrics({
  prefix: "myapp_",
  labels: { service: "api-server", version: "1.0.0" },
  eventLoopMonitoringPrecision: 10,
});

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

// Get all available default metric names
console.log(collectDefaultMetrics.metricsList);

Configuration Options

Registry Selection

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

import { collectDefaultMetrics, Registry } from "prom-client";

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

// Only default metrics will be in this registry
const defaultMetrics = await metricsRegistry.metrics();

Metric Name Prefixing

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

import { collectDefaultMetrics } from "prom-client";

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

// Results in metrics like:
// myservice_process_cpu_user_seconds_total
// myservice_nodejs_heap_size_total_bytes
// myservice_nodejs_eventloop_lag_seconds

Generic Labels

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

import { collectDefaultMetrics } from "prom-client";

collectDefaultMetrics({
  labels: {
    service: "user-api",
    environment: "production",
    region: "us-west-2",
    instance: process.env.HOSTNAME,
  },
});

Garbage Collection Buckets

Customize the histogram buckets for garbage collection duration metrics.

import { collectDefaultMetrics, linearBuckets } from "prom-client";

// Default GC buckets: [0.001, 0.01, 0.1, 1, 2, 5]
collectDefaultMetrics({
  gcDurationBuckets: linearBuckets(0.001, 0.001, 10), // More granular buckets
});

Event Loop Monitoring Precision

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

import { collectDefaultMetrics } from "prom-client";

collectDefaultMetrics({
  eventLoopMonitoringPrecision: 5, // Check every 5ms (more precise but higher overhead)
});

Available Default Metrics

The metricsList property contains all available default metric names:

/**
 * All available default metrics
 */
metricsList: string[];

Default metrics include:

Process CPU Usage: process_cpu_user_seconds_total, process_cpu_system_seconds_total
Process Start Time: process_start_time_seconds
Process File Descriptors: process_open_fds, process_max_fds (Linux only)
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
Process Handles: nodejs_active_handles, nodejs_active_handles_total
Process Requests: nodejs_active_requests, nodejs_active_requests_total
Heap Memory: nodejs_heap_size_total_bytes, nodejs_heap_size_used_bytes, nodejs_external_memory_bytes
Heap Spaces: nodejs_heap_space_size_total_bytes, nodejs_heap_space_size_used_bytes, nodejs_heap_space_size_available_bytes
Node.js Version: nodejs_version_info
Garbage Collection: nodejs_gc_duration_seconds
OS Memory: process_resident_memory_bytes, process_virtual_memory_bytes, process_heap_bytes (Linux only)
Process Resources: nodejs_active_resources, nodejs_active_resources_total (if available)

Usage Example:

import { collectDefaultMetrics } from "prom-client";

// Enable default metrics
collectDefaultMetrics();

// List all available default metrics
console.log("Available default metrics:");
collectDefaultMetrics.metricsList.forEach(metricName => {
  console.log(`- ${metricName}`);
});

Platform-Specific Metrics

Some metrics are only available on specific platforms:

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

Performance Considerations

Default metrics collection is designed to be lightweight:

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

Example with performance tuning:

import { collectDefaultMetrics } from "prom-client";

// Optimize for high-throughput applications
collectDefaultMetrics({
  eventLoopMonitoringPrecision: 100, // Less frequent sampling
  gcDurationBuckets: [0.001, 0.01, 0.1, 1, 5], // Fewer buckets
});

Integration with Web Frameworks

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

const app = express();

// Enable default metrics collection
collectDefaultMetrics();

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

app.listen(3000);

Types

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

type RegistryContentType = PrometheusContentType | OpenMetricsContentType;

Install with Tessl CLI