@libp2p/interface 1.1.2-08f6f607d → 1.1.2-1cb2408ac

package/dist/src/metrics/index.d.ts

@@ -128,6 +128,144 @@ export interface CounterGroup {
  * The libp2p metrics tracking object. This interface is only concerned
  * with the collection of metrics, please see the individual implementations
  * for how to extract metrics for viewing.
+ *
+ * @example How to register a simple metric
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetric.update(1)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a dynamically calculated metric
+ *
+ * A metric that is expensive to calculate can be created by passing a `calculate` function that will only be invoked when metrics are being scraped:
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text',
+ *       calculate: async () => {
+ *         // do something expensive
+ *         return 1
+ *       }
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a group of metrics
+ *
+ * If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
+ *
+ * ```typescript
+ * import { Metrics, MetricGroup } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetricGroup: MetricGroup
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetricGroup = components.metrics.registerMetricGroup({
+ *       name: 'my_metric_group',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetricGroup.increment({ my_label: 'my_value' })
+ *   }
+ * }
+ * ```
+ *
+ * There are specific metric groups for tracking libp2p connections and streams:
+ *
+ * @example How to track multiaddr connections
+ *
+ * This is something only libp2p transports need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const connection = {} // create a connection
+ *     this.metrics.trackMultiaddrConnection(connection)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to track protocol streams
+ *
+ * This is something only libp2p connections need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const stream = {} // create a stream
+ *     this.metrics.trackProtocolStream(stream)
+ *   }
+ * }
+ * ```
  */
 export interface Metrics {
     /**

package/dist/src/metrics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/interface",
-  "version": "1.1.2-08f6f607d",
+  "version": "1.1.2-1cb2408ac",
   "description": "The interface implemented by a libp2p node",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/interface#readme",

package/src/metrics/index.ts

@@ -146,6 +146,144 @@ export interface CounterGroup {
  * The libp2p metrics tracking object. This interface is only concerned
  * with the collection of metrics, please see the individual implementations
  * for how to extract metrics for viewing.
+ *
+ * @example How to register a simple metric
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetric.update(1)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a dynamically calculated metric
+ *
+ * A metric that is expensive to calculate can be created by passing a `calculate` function that will only be invoked when metrics are being scraped:
+ *
+ * ```typescript
+ * import { Metrics, Metric } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetric: Metric
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetric = components.metrics.registerMetric({
+ *       name: 'my_metric',
+ *       label: 'my_label',
+ *       help: 'my help text',
+ *       calculate: async () => {
+ *         // do something expensive
+ *         return 1
+ *       }
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @example How to register a group of metrics
+ *
+ * If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
+ *
+ * ```typescript
+ * import { Metrics, MetricGroup } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly myMetricGroup: MetricGroup
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.myMetricGroup = components.metrics.registerMetricGroup({
+ *       name: 'my_metric_group',
+ *       label: 'my_label',
+ *       help: 'my help text'
+ *     })
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     this.myMetricGroup.increment({ my_label: 'my_value' })
+ *   }
+ * }
+ * ```
+ *
+ * There are specific metric groups for tracking libp2p connections and streams:
+ *
+ * @example How to track multiaddr connections
+ *
+ * This is something only libp2p transports need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const connection = {} // create a connection
+ *     this.metrics.trackMultiaddrConnection(connection)
+ *   }
+ * }
+ * ```
+ *
+ * @example How to track protocol streams
+ *
+ * This is something only libp2p connections need to do.
+ *
+ * ```typescript
+ * import { Metrics } from '@libp2p/interface/metrics
+ *
+ * interface MyServiceComponents {
+ *   metrics: Metrics
+ * }
+ *
+ * class MyService {
+ *   private readonly metrics: Metrics
+ *
+ *   constructor (components: MyServiceComponents) {
+ *     this.metrics = components.metrics
+ *   }
+ *
+ *   // later
+ *   doSomething () {
+ *     const stream = {} // create a stream
+ *     this.metrics.trackProtocolStream(stream)
+ *   }
+ * }
+ * ```
  */
 export interface Metrics {
   /**