feat: register metrics with custom registry (#4)

Some applications (*cough cough lodestar*) use a custom registry to
register metrics.
This allows for more graceful capture of metrics from multiple services
within a single javascript runtime.

This PR adds the feature to pass in a custom registry to register all
libp2p metrics with.

Author: wemeetagain

src/counter-group.ts

@@ -1,12 +1,13 @@
-import type { CounterGroup, CalculatedMetricOptions, CalculateMetric } from '@libp2p/interface-metrics'
+import type { CounterGroup, CalculateMetric } from '@libp2p/interface-metrics'
 import { Counter as PromCounter, CollectFunction } from 'prom-client'
+import type { PrometheusCalculatedMetricOptions } from './index.js'
 import { normaliseString } from './utils.js'
 
 export class PrometheusCounterGroup implements CounterGroup {
   private readonly counter: PromCounter
   private readonly label: string
 
-  constructor (name: string, opts: CalculatedMetricOptions<Record<string, number>>) {
+  constructor (name: string, opts: PrometheusCalculatedMetricOptions<Record<string, number>>) {
     name = normaliseString(name)
     const help = normaliseString(opts.help ?? name)
     const label = this.label = normaliseString(opts.label ?? name)
@@ -29,6 +30,7 @@ export class PrometheusCounterGroup implements CounterGroup {
       name,
       help,
       labelNames: [this.label],
+      registers: opts.registry !== undefined ? [opts.registry] : undefined,
       collect
     })
   }

src/counter.ts

@@ -1,11 +1,12 @@
-import type { Counter, CalculatedMetricOptions } from '@libp2p/interface-metrics'
+import type { Counter } from '@libp2p/interface-metrics'
 import { CollectFunction, Counter as PromCounter } from 'prom-client'
+import type { PrometheusCalculatedMetricOptions } from './index.js'
 import { normaliseString } from './utils.js'
 
 export class PrometheusCounter implements Counter {
   private readonly counter: PromCounter
 
-  constructor (name: string, opts: CalculatedMetricOptions) {
+  constructor (name: string, opts: PrometheusCalculatedMetricOptions) {
     name = normaliseString(name)
     const help = normaliseString(opts.help ?? name)
     const labels = opts.label != null ? [normaliseString(opts.label)] : []
@@ -26,6 +27,7 @@ export class PrometheusCounter implements Counter {
       name,
       help,
       labelNames: labels,
+      registers: opts.registry !== undefined ? [opts.registry] : undefined,
       collect
     })
   }

src/index.ts

@@ -1,5 +1,5 @@
 import type { CalculatedMetricOptions, Counter, CounterGroup, Metric, MetricGroup, MetricOptions, Metrics } from '@libp2p/interface-metrics'
-import { collectDefaultMetrics, DefaultMetricsCollectorConfiguration, register } from 'prom-client'
+import { collectDefaultMetrics, DefaultMetricsCollectorConfiguration, register, Registry } from 'prom-client'
 import type { MultiaddrConnection, Stream, Connection } from '@libp2p/interface-connection'
 import type { Duplex } from 'it-stream-types'
 import each from 'it-foreach'
@@ -12,6 +12,12 @@ import { logger } from '@libp2p/logger'
 const log = logger('libp2p:prometheus-metrics')
 
 export interface PrometheusMetricsInit {
+  /**
+   * Use a custom registry to register metrics.
+   * By default, the global registry is used to register metrics.
+   */
+  registry?: Registry
+
   /**
    * By default we collect default metrics - CPU, memory etc, to not do
    * this, pass true here
@@ -31,18 +37,25 @@ export interface PrometheusMetricsInit {
   preserveExistingMetrics?: boolean
 }
 
+export interface PrometheusCalculatedMetricOptions<T=number> extends CalculatedMetricOptions<T> {
+  registry?: Registry
+}
+
 class PrometheusMetrics implements Metrics {
   private transferStats: Map<string, number>
+  private readonly registry?: Registry
 
   constructor (init?: Partial<PrometheusMetricsInit>) {
+    this.registry = init?.registry
+
     if (init?.preserveExistingMetrics !== true) {
       log('Clearing existing metrics')
-      register.clear()
+      ;(this.registry ?? register).clear()
     }
 
     if (init?.preserveExistingMetrics !== false) {
       log('Collecting default metrics')
-      collectDefaultMetrics(init?.defaultMetrics)
+      collectDefaultMetrics({ ...init?.defaultMetrics, register: this.registry ?? init?.defaultMetrics?.register })
     }
 
     // holds global and per-protocol sent/received stats
@@ -120,60 +133,60 @@ class PrometheusMetrics implements Metrics {
     this._track(stream, stream.stat.protocol)
   }
 
-  registerMetric (name: string, opts: CalculatedMetricOptions): void
+  registerMetric (name: string, opts: PrometheusCalculatedMetricOptions): void
   registerMetric (name: string, opts?: MetricOptions): Metric
   registerMetric (name: string, opts: any = {}): any {
     if (name == null ?? name.trim() === '') {
       throw new Error('Metric name is required')
     }
 
     log('Register metric', name)
-    const metric = new PrometheusMetric(name, opts ?? {})
+    const metric = new PrometheusMetric(name, { registry: this.registry, ...opts })
 
     if (opts.calculate == null) {
       return metric
     }
   }
 
-  registerMetricGroup (name: string, opts: CalculatedMetricOptions<Record<string, number>>): void
+  registerMetricGroup (name: string, opts: PrometheusCalculatedMetricOptions<Record<string, number>>): void
   registerMetricGroup (name: string, opts?: MetricOptions): MetricGroup
   registerMetricGroup (name: string, opts: any = {}): any {
     if (name == null ?? name.trim() === '') {
       throw new Error('Metric name is required')
     }
 
     log('Register metric group', name)
-    const group = new PrometheusMetricGroup(name, opts ?? {})
+    const group = new PrometheusMetricGroup(name, { registry: this.registry, ...opts })
 
     if (opts.calculate == null) {
       return group
     }
   }
 
-  registerCounter (name: string, opts: CalculatedMetricOptions): void
+  registerCounter (name: string, opts: PrometheusCalculatedMetricOptions): void
   registerCounter (name: string, opts?: MetricOptions): Counter
   registerCounter (name: string, opts: any = {}): any {
     if (name == null ?? name.trim() === '') {
       throw new Error('Counter name is required')
     }
 
     log('Register counter', name)
-    const counter = new PrometheusCounter(name, opts)
+    const counter = new PrometheusCounter(name, { registry: this.registry, ...opts })
 
     if (opts.calculate == null) {
       return counter
     }
   }
 
-  registerCounterGroup (name: string, opts: CalculatedMetricOptions<Record<string, number>>): void
+  registerCounterGroup (name: string, opts: PrometheusCalculatedMetricOptions<Record<string, number>>): void
   registerCounterGroup (name: string, opts?: MetricOptions): CounterGroup
   registerCounterGroup (name: string, opts: any = {}): any {
     if (name == null ?? name.trim() === '') {
       throw new Error('Metric name is required')
     }
 
     log('Register counter group', name)
-    const group = new PrometheusCounterGroup(name, opts)
+    const group = new PrometheusCounterGroup(name, { registry: this.registry, ...opts })
 
     if (opts.calculate == null) {
       return group

src/metric-group.ts

@@ -1,12 +1,13 @@
-import type { CalculatedMetricOptions, CalculateMetric, MetricGroup, StopTimer } from '@libp2p/interface-metrics'
+import type { CalculateMetric, MetricGroup, StopTimer } from '@libp2p/interface-metrics'
 import { CollectFunction, Gauge } from 'prom-client'
+import type { PrometheusCalculatedMetricOptions } from './index.js'
 import { normaliseString } from './utils.js'
 
 export class PrometheusMetricGroup implements MetricGroup {
   private readonly gauge: Gauge
   private readonly label: string
 
-  constructor (name: string, opts: CalculatedMetricOptions<Record<string, number>>) {
+  constructor (name: string, opts: PrometheusCalculatedMetricOptions<Record<string, number>>) {
     name = normaliseString(name)
     const help = normaliseString(opts.help ?? name)
     const label = this.label = normaliseString(opts.label ?? name)
@@ -29,6 +30,7 @@ export class PrometheusMetricGroup implements MetricGroup {
       name,
       help,
       labelNames: [this.label],
+      registers: opts.registry !== undefined ? [opts.registry] : undefined,
       collect
     })
   }

src/metric.ts

@@ -1,11 +1,12 @@
-import type { Metric, CalculatedMetricOptions, StopTimer } from '@libp2p/interface-metrics'
+import type { Metric, StopTimer } from '@libp2p/interface-metrics'
 import { CollectFunction, Gauge } from 'prom-client'
+import type { PrometheusCalculatedMetricOptions } from './index.js'
 import { normaliseString } from './utils.js'
 
 export class PrometheusMetric implements Metric {
   private readonly gauge: Gauge
 
-  constructor (name: string, opts: CalculatedMetricOptions) {
+  constructor (name: string, opts: PrometheusCalculatedMetricOptions) {
     name = normaliseString(name)
     const help = normaliseString(opts.help ?? name)
     const labels = opts.label != null ? [normaliseString(opts.label)] : []
@@ -26,6 +27,7 @@ export class PrometheusMetric implements Metric {
       name,
       help,
       labelNames: labels,
+      registers: opts.registry !== undefined ? [opts.registry] : undefined,
       collect
     })
   }

test/custom-registry.spec.ts

@@ -0,0 +1,23 @@
+import { expect } from 'aegir/chai'
+import { prometheusMetrics } from '../src/index.js'
+import client, { Registry } from 'prom-client'
+import { randomMetricName } from './fixtures/random-metric-name.js'
+
+describe('custom registry', () => {
+  it('should set a metric in the custom registry and not in the global registry', async () => {
+    const metricName = randomMetricName()
+    const metricValue = 5
+    const registry = new Registry()
+    const metrics = prometheusMetrics({ registry })()
+    const metric = metrics.registerMetric(metricName)
+    metric.update(metricValue)
+
+    const customRegistryReport = await registry.metrics()
+    expect(customRegistryReport).to.include(`# TYPE ${metricName} gauge`, 'did not include metric type')
+    expect(customRegistryReport).to.include(`${metricName} ${metricValue}`, 'did not include updated metric')
+
+    const globalRegistryReport = await client.register.metrics()
+    expect(globalRegistryReport).to.not.include(`# TYPE ${metricName} gauge`, 'erroneously includes metric type')
+    expect(globalRegistryReport).to.not.include(`${metricName} ${metricValue}`, 'erroneously includes updated metric')
+  })
+})