@setu-ts/metrics-plugin

Prometheus metrics. Registers an IMetricsService under CAPABILITIES.METRICS ('metrics') and serves the scrape endpoint at /metrics.

Zero dependencies — the Prometheus text-format 0.0.4 renderer is implemented in this package.

Label values are escaped per text format 0.0.4 (backslash, double quote, line feed). Any other control character (carriage return, NUL, the rest of C0 and DEL) has no escape in that format and is encoded in label values and HELP text as U+FFFD followed by its two hex digits (a lone UTF-16 surrogate as U+FFFD, u and four hex digits; a literal U+FFFD as two of them), so an application-supplied value cannot split an exposition line and two distinct values never render as the same sample line.

Installation

import { MetricsPlugin } from '@setu-ts/metrics-plugin';

Usage

import { createApplication } from '@setu-ts/kernel';
import { RuntimePlugin } from '@setu-ts/runtime';
import { MetricsPlugin } from '@setu-ts/metrics-plugin';
import { CAPABILITIES, type IMetricsService } from '@setu-ts/common';

const app = createApplication({
  plugins: [RuntimePlugin(), MetricsPlugin({ endpoint: '/metrics', httpMetrics: true })],
});
await app.start({ port: 3000 });

const metrics = app.services.get<IMetricsService>(CAPABILITIES.METRICS);
const signups = metrics.counter('app_signups_total', { help: 'Completed signups' });
signups.inc(1);

Options

| Option | Type | Default | Description | | ------------------ | --------------------- | ----------------------------------------------------------- | ---------------------------------------------- | | endpoint | string | '/metrics' | Scrape endpoint path. | | defaultMetrics | boolean | true | Register the built-in metric set. | | httpMetrics | boolean | true | Register the HTTP request-tracking middleware. | | customMetrics | NamedMetricConfig[] | [] | Metrics pre-registered declaratively. | | defaultBuckets | number[] | [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10] | Histogram bucket boundaries. | | defaultQuantiles | number[] | [0.5, 0.9, 0.99] | Summary quantiles. |

Instruments

counter, gauge, histogram, and summary, all over a shared base.

HTTP collectors

The metrics middleware runs at priority 20 — outermost, so it observes all ingress and the final response status. The record path is wrapped in try/finally, so a request that throws still decrements the active-requests gauge rather than leaking it.

HTTP series use only method and status labels. The case-sensitive known methods are GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, and PATCH; every other method uses _OTHER, including on thrown-error paths. This bounds method-label cardinality.

Exports

| Export | Kind | | ---------------------- | --------- | | MetricsPlugin | function | | Counter | class | | Gauge | class | | Histogram | class | | MetricsService | class | | Summary | class | | ICounter | interface | | IGauge | interface | | IHistogram | interface | | IMetric | interface | | IMetricsService | interface | | ISummary | interface | | MetricConfig | interface | | MetricOptions | interface | | MetricsPluginOptions | interface | | NamedMetricConfig | interface |

Generated from the package barrel by pnpm run docs:exports; pnpm run check:docs fails when it drifts.

Full API

Every export and option is documented in PUBLIC_API.md.