# @well-known-components/metrics

> metrics component

Latest version **2.1.0** (published 2024-03-18) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @well-known-components/metrics
pnpm add @well-known-components/metrics
yarn add @well-known-components/metrics
bun add @well-known-components/metrics
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2024-03-18 |
| First published | 2021-02-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 32.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | well-known-components-publisher, menduz |

## Links

- npm: https://www.npmjs.com/package/@well-known-components/metrics
- Repository: https://github.com/well-known-components/metrics
- Homepage: https://github.com/well-known-components/metrics#readme
- Issues: https://github.com/well-known-components/metrics/issues
- npm.io page: https://npm.io/package/@well-known-components/metrics

## Dependencies (1)

- [prom-client](https://npm.io/package/prom-client.md) ^15.1.0

## Recent versions

- 2.1.0 (latest) — 2024-03-18
- 2.1.1-20240318121622.commit-357a93e (next) — 2024-03-18
- 2.0.2-20240318115652.commit-cd054ed — 2024-03-18
- 2.0.2-20240315125952.commit-847498c — 2024-03-15
- 2.0.2-20240314122215.commit-df469cb — 2024-03-14
- 2.0.2-20240314121817.commit-2a29945 — 2024-03-14
- 2.0.2-20240314121618.commit-1db6590 — 2024-03-14
- 2.0.2-20230904165714.commit-81901e5 — 2023-09-04
- 2.0.2-20230815175338.commit-046dbb0 — 2023-08-15
- 2.0.2-20230725173544.commit-f6bb53e — 2023-07-25
- 2.0.2-20230725173418.commit-aadf3a9 — 2023-07-25
- 2.0.2-20230725173301.commit-8395597 — 2023-07-25
- 2.0.2-20230628130145.commit-c9f072d — 2023-06-28
- 2.0.2-20230628121034.commit-ef205a4 — 2023-06-28
- 2.0.2-20230628120739.commit-19527df — 2023-06-28
- … 40 more at https://npm.io/package/@well-known-components/metrics/versions

## README

# metrics

`npm i @well-known-components/metrics`

## Configuration via config component

Here is a list of configuration keys that may be used by this component:

- `WKC_METRICS_PUBLIC_PATH`: `string` path to expose metrics, default: `/metrics`
- `WKC_METRICS_BEARER_TOKEN`: `string` bearer token to protect metrics, default: _not set_
- `WKC_METRICS_COLLECT_DEFAULT`: `"true" | "false"` collect default nodejs metrics, default: `true`
- `WKC_METRICS_RESET_AT_NIGHT`: `"true" | "false"` resets all user-defined metrics every day at 00.00 UTC, default: false

## Define your metrics in a static file

```ts
// src/metrics.ts

import { IMetricsComponent } from "@well-known-components/interfaces"
import { validateMetricsDeclaration } from "@well-known-components/metrics"

export const metricDeclarations = {
  // register all http-server metrics
  ...getDefaultHttpMetrics(),
  // IMetricsComponent.SummaryType
  // IMetricsComponent.HistogramType
  // IMetricsComponent.GaugeType
  // IMetricsComponent.CounterType
  user_counter: {
    type: IMetricsComponent.CounterType,
    help: "Count calls to /user/:userId",
    labelNames: ["userId"],
  },
}

// type assertions
validateMetricsDeclaration(metricDeclarations)
```

## Define the component

```ts
// src/components.ts

import { metricDeclarations } from "./metrics"

export async function initComponents(): Promise<AppComponents> {
  ...
  // const config
  // const server
  const metrics = await createMetricsComponent(metricDeclarations, {config})
  await instrumentHttpServerWithMetrics({ metrics, config, server })

  return { ...components, metrics }
}
```

## Register metrics

```ts
export async function userIdHandler(context: { components: Pick<AppComponents, "metrics"> }) {
  const {
    components: { metrics },
  } = context

  metrics.increment("user_counter", { userId: Math.random() })
  // metrics.decrement("user_counter", { userId: Math.random() })
  // metrics.observe("user_counter", { userId: Math.random() }, 1)
  // metrics.reset("user_counter")

  return {}
}
```

## Migrating from 1.0.0 to 2.0.0

A few things must be taken into account since it is a breaking change

- The metrics component does not automatically instrument an http server, it should be done manually via `instrumentHttpServerWithMetrics`
- And thus, the default metricsDeclaration also don't include the default http metrics, it can be composed with those metrics via `metricsDeclaration = { ...getDefaultHttpMetrics(), ...yourMetrics }`

---
_Source: https://npm.io/package/@well-known-components/metrics · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._