Skip to main content

Class: PrometheusMetrics

Defined in: src/observability/metrics-exporter.ts:119

Prometheus-based metrics implementation.

Remarks​

Implements IMetrics interface with:

  • Dynamic metric creation (metrics created on first use)
  • Metric caching (avoids re-registration)
  • Cardinality protection (limits unique label combinations)
  • Automatic label name extraction

Metrics are registered with the provided Prometheus registry and can be scraped via the /metrics endpoint.

Example​

const metrics = new PrometheusMetrics({ prefix: 'myapp_' });

// Counter
metrics.incrementCounter('requests_total', { method: 'GET', status: '200' });

// Gauge
metrics.setGauge('queue_size', 42, { queue: 'indexing' });

// Histogram
metrics.observeHistogram('request_duration_seconds', 0.15, { endpoint: '/api' });

// Timer
const endTimer = metrics.startTimer('operation_duration_seconds', { op: 'index' });
await doWork();
endTimer();

See​

IMetrics for interface contract

Since​

0.1.0

Implements​

Constructors​

new PrometheusMetrics()​

new PrometheusMetrics(options): PrometheusMetrics

Defined in: src/observability/metrics-exporter.ts:146

Creates a new PrometheusMetrics instance.

Parameters​

options​

PrometheusMetricsOptions = {}

Configuration options

Returns​

PrometheusMetrics

Example​

// Use defaults
const metrics = new PrometheusMetrics();

// Custom configuration
const customMetrics = new PrometheusMetrics({
  prefix: 'myservice_',
  defaultBuckets: [0.1, 0.5, 1, 2, 5],
  maxCardinality: 5000,
});

Methods​

incrementCounter()​

incrementCounter(name, labels?, value?): void

Defined in: src/observability/metrics-exporter.ts:360

Increments a counter metric.

Parameters​

name​

string

Metric name (prefix added automatically)

labels?​

Readonly<Record<string, string>>

Optional labels for dimensionality

value?​

number = 1

Increment value (default: 1)

Returns​

void

Remarks​

Counter values can only increase. Use for tracking totals. Creates the metric on first use.

Example​

// Simple increment
metrics.incrementCounter('requests_total');

// With labels
metrics.incrementCounter('http_requests_total', { method: 'GET', status: '200' });

// Increment by specific value
metrics.incrementCounter('bytes_received_total', { endpoint: '/upload' }, 1024);

Implementation of​

IMetrics.incrementCounter

observeHistogram()​

observeHistogram(name, value, labels?): void

Defined in: src/observability/metrics-exporter.ts:443

Observes a value in a histogram metric.

Parameters​

name​

string

Metric name (prefix added automatically)

value​

number

Observed value

labels?​

Readonly<Record<string, string>>

Optional labels for dimensionality

Returns​

void

Remarks​

Histograms track distributions of values. Use for latencies, sizes, and other measurements. Creates the metric on first use.

Example​

// Record request duration
metrics.observeHistogram('request_duration_seconds', 0.156);

// With labels
metrics.observeHistogram('http_request_duration_seconds', duration, {
  method: 'GET',
  endpoint: '/api/preprints',
  status: '200',
});

// Record response size
metrics.observeHistogram('response_size_bytes', responseBody.length, { endpoint: '/api' });

Implementation of​

IMetrics.observeHistogram

setGauge()​

setGauge(name, value, labels?): void

Defined in: src/observability/metrics-exporter.ts:399

Sets a gauge metric value.

Parameters​

name​

string

Metric name (prefix added automatically)

value​

number

Gauge value (can increase or decrease)

labels?​

Readonly<Record<string, string>>

Optional labels for dimensionality

Returns​

void

Remarks​

Gauge values can go up or down. Use for current state. Creates the metric on first use.

Example​

// Set current value
metrics.setGauge('queue_size', queueLength);

// With labels
metrics.setGauge('active_connections', connectionCount, { database: 'postgresql' });

// Track temperature
metrics.setGauge('cpu_temperature_celsius', 65.5, { core: '0' });

Implementation of​

IMetrics.setGauge

startTimer()​

startTimer(name, labels?): () => void

Defined in: src/observability/metrics-exporter.ts:502

Starts a timer for measuring duration.

Parameters​

name​

string

Metric name (prefix added automatically)

labels?​

Readonly<Record<string, string>>

Optional labels for dimensionality

Returns​

Function

Function to call when operation completes

Returns​

void

Remarks​

Returns a function that records the elapsed time when called. Uses high-resolution time for accuracy. Creates the histogram metric on first use.

Example​

// Basic timer
const endTimer = metrics.startTimer('operation_duration_seconds');
await performOperation();
endTimer(); // Records elapsed time

// With labels
const endTimer = metrics.startTimer('db_query_duration_seconds', {
  database: 'postgresql',
  operation: 'select',
});
try {
  await executeQuery();
} finally {
  endTimer();
}

// In async context
async function processRequest(req: Request) {
  const endTimer = metrics.startTimer('request_processing_seconds', {
    endpoint: req.path,
  });
  try {
    return await handleRequest(req);
  } finally {
    endTimer();
  }
}

Implementation of​

IMetrics.startTimer