Skip to content

Commit

Permalink
chore: move generic metrics docs to metrics interface
Browse files Browse the repository at this point in the history
  • Loading branch information
@achingbrain
achingbrain committed Nov 28, 2023
1 parent fc21c52 commit 70941f5
Show file tree
Hide file tree
Showing 6 changed files with 147 additions and 208 deletions.
138 changes: 138 additions & 0 deletions packages/interface/src/metrics/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down
114 changes: 2 additions & 112 deletions packages/metrics-prometheus/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

Configure your libp2p node with Prometheus metrics:

```js
```typescript
import { createLibp2p } from 'libp2p'
import { prometheusMetrics } from '@libp2p/prometheus-metrics'

Expand All @@ -20,7 +20,7 @@ const node = await createLibp2p({

Then use the `prom-client` module to supply metrics to the Prometheus/Graphana client using your http framework:

```js
```typescript
import client from 'prom-client'

async handler (request, h) {
Expand Down Expand Up @@ -71,116 +71,6 @@ libp2p_kad_dht_lan_query_time_seconds
rate(libp2p_tcp_dialer_errors_total[30s])
```

## Example

```typescript
import { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { createLibp2p } from 'libp2p'

const node = createLibp2p({
metrics: prometheusMetrics()
//... other config
})

const myMetric = node.metrics?.registerMetric({
name: 'my_metric',
label: 'my_label',
help: 'my help text'
})

myMetric.update(1)
```

## Example

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 { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { createLibp2p } from 'libp2p'

const node = createLibp2p({
metrics: prometheusMetrics()
//... other config
})

const myMetric = node.metrics?.registerMetric({
name: 'my_metric',
label: 'my_label',
help: 'my help text',
calculate: async () => {
// do something expensive
return 1
}
})
```

## Example

If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:

```typescript
import { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { createLibp2p } from 'libp2p'

const node = createLibp2p({
metrics: prometheusMetrics()
//... other config
})

const myMetricGroup = metrics.registerMetricGroup({
name: 'my_metric_group',
label: 'my_label',
help: 'my help text'
})

myMetricGroup.increment({ my_label: 'my_value' })
```

There are specific metric groups for tracking libp2p connections and streams:

## Example

Track a newly opened multiaddr connection:

```typescript
import { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { createLibp2p } from 'libp2p'
import { defaultLogger } from '@libp2p/logger'

const metrics: Metrics = prometheusMetrics()({
logger: defaultLogger()
})

const libp2p = await createLibp2p({
metrics: metrics,
})
// set up a multiaddr connection
const connection = await libp2p.dial('multiaddr')
const connections = metrics.trackMultiaddrConnection(connection)
```

## Example

Track a newly opened stream:

```typescript
import { prometheusMetrics } from '@libp2p/prometheus-metrics'
import { createLibp2p } from 'libp2p'
import { defaultLogger } from '@libp2p/logger'

const metrics: Metrics = prometheusMetrics()({
logger: defaultLogger()
})

const libp2p = await createLibp2p({
metrics: metrics,
})

const stream = await connection.newStream('/my/protocol')
const streams = metrics.trackProtocolStream(stream)
```

# Install

```console
Expand Down
93 changes: 2 additions & 91 deletions packages/metrics-prometheus/src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
*
* Configure your libp2p node with Prometheus metrics:
*
* ```js
* ```typescript
* import { createLibp2p } from 'libp2p'
* import { prometheusMetrics } from '@libp2p/prometheus-metrics'
*
Expand All @@ -14,7 +14,7 @@
*
* Then use the `prom-client` module to supply metrics to the Prometheus/Graphana client using your http framework:
*
* ```js
* ```typescript
* import client from 'prom-client'
*
* async handler (request, h) {
Expand Down Expand Up @@ -64,95 +64,6 @@
* ```
* rate(libp2p_tcp_dialer_errors_total[30s])
* ```
*
* @example
*
* ```typescript
* import { prometheusMetrics } from '@libp2p/prometheus-metrics'
*
* const metrics = prometheusMetrics()()
* const myMetric = metrics.registerMetric({
* name: 'my_metric',
* label: 'my_label',
* help: 'my help text'
* })
*
* myMetric.update(1)
* ```
*
* @example
*
* 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 { prometheusMetrics } from '@libp2p/prometheus-metrics'
*
* const metrics = prometheusMetrics()()
* const myMetric = metrics.registerMetric({
* name: 'my_metric',
* label: 'my_label',
* help: 'my help text',
* calculate: async () => {
* // do something expensive
* return 1
* }
* })
* ```
*
* @example
*
* If several metrics should be grouped together (e.g. for graphing purposes) `registerMetricGroup` can be used instead:
*
* ```typescript
* import { prometheusMetrics } from '@libp2p/prometheus-metrics'
*
* const metrics = prometheusMetrics()()
* const myMetricGroup = metrics.registerMetricGroup({
* name: 'my_metric_group',
* label: 'my_label',
* help: 'my help text'
* })
*
* myMetricGroup.increment({ my_label: 'my_value' })
* ```
*
* There are specific metric groups for tracking libp2p connections and streams:
*
* @example
*
* Track a newly opened multiaddr connection:
*
* ```typescript
* import { prometheusMetrics } from '@libp2p/prometheus-metrics'
* import { createLibp2p } from 'libp2p'
*
* const metrics = prometheusMetrics()()
*
* const libp2p = await createLibp2p({
* metrics: metrics,
* })
* // set up a multiaddr connection
* const connection = await libp2p.dial('multiaddr')
* const connections = metrics.trackMultiaddrConnection(connection)
* ```
*
* @example
*
* Track a newly opened stream:
*
* ```typescript
* import { prometheusMetrics } from '@libp2p/prometheus-metrics'
* import { createLibp2p } from 'libp2p'
*
* const metrics = prometheusMetrics()()
*
* const libp2p = await createLibp2p({
* metrics: metrics,
* })
*
* const stream = await connection.newStream('/my/protocol')
* const streams = metrics.trackProtocolStream(stream)
* ```
*/

import each from 'it-foreach'
Expand Down
Loading

0 comments on commit 70941f5

Please sign in to comment.