https://github.com/alphagov/pay-js-metrics
Node.js library for metric instrumentation in GOV.UK Pay
https://github.com/alphagov/pay-js-metrics
govuk-pay portfolio
Last synced: about 1 month ago
JSON representation
Node.js library for metric instrumentation in GOV.UK Pay
- Host: GitHub
- URL: https://github.com/alphagov/pay-js-metrics
- Owner: alphagov
- License: mit
- Created: 2023-07-14T09:53:42.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-23T12:33:21.000Z (about 2 months ago)
- Last Synced: 2025-04-23T13:51:12.673Z (about 2 months ago)
- Topics: govuk-pay, portfolio
- Language: TypeScript
- Homepage:
- Size: 350 KB
- Stars: 1
- Watchers: 16
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# pay-js-metrics
GOV.UK Pay Express middleware for prometheus metrics instrumentation
## Usage instructions
### Setting up
To enable `pay-js-metrics` in your Express app, use the middleware like so:
```js
const express = require('express')
const metrics = require('pay-js-metrics')
const app = express()
app.use(metrics.initialise())
```
`pay-js-metrics` will begin collecting the following baseline metrics automatically:
- Node runtime metrics
- Process CPU and memory metrics
- Express HTTP request metrics
These metrics will be published on `your.app/metrics`
### Initialisation
### Registering custom metrics
`pay-js-metrics` supports the following metric types:
- Histograms
- A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets
- Counters
- A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart
- Gauges
- A gauge is a metric that represents a single numerical value that can arbitrarily go up and down
Custom metrics can be registered via the exported helper functions:
```
metrics.registerCounter(name: string, help: string, labelNames: string[])
metrics.registerGauge(name: string, help: string, labelNames: string[])
metrics.registerHistogram(name: string, help: string, labelNames: string[], buckets?: number[])
```
Example registration of a custom Counter metric:
```js
const hello_counter = metrics.registerCounter('hello_counter', '/hello example counter metric', ['http_method'])
```
`name` is the name of your metric, it is exported as
```
# TYPE hello_counter counter
```
`help` is the description of your metric, it is exported as
```
# HELP hello_counter /hello example counter metric
```
`labelNames` is an array of label keys that are assigned values when your metric is observed, for example:
```js
hello_counter.labels({ http_method: 'GET' }).inc(1)
```
would be exported as:
```
hello_counter{http_method="GET"} 2
```
Histogram metrics take an additional optional `buckets` parameter that customises the bucket values for observed events, this is an array of type `number`
__IMPORTANT__: Custom metrics are not viewable before they have been observed at least once
For more examples of how metrics can be registered and used, see the [demo code](ecs_metadata/demo.ts).
## Contributing
`npm run test` checks the code formatting and executes the Jest test suite
`npm run build` complies the project to CommonJS, outputs to `dist`
`npm run format` runs the formatter rule set and will automatically update any src files that are failing
`npm run demo` starts the demo express app where you can query `/metrics` to see the metrics, `/hello` and
`/hello/` to generate more metrics and view the test page output.
## Releasing
After a pull request is merged, Concourse will automatically create a new release pull request that increments the package version.
This pull request must be reviewed and merged by a developer.
Once the release pull request is merged, GitHub Actions will publish the new versioned package to NPM.
__IMPORTANT__: Other pull requests will be blocked from merging until the release pull request is merged or closed.
## Licence
[MIT License](LICENSE)
## Vulnerability Disclosure
GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. Please refer to our [vulnerability disclosure policy](https://www.gov.uk/help/report-vulnerability) and our [security.txt](https://vdp.cabinetoffice.gov.uk/.well-known/security.txt) file for details.