@3sixty/telemetry-processors 0.0.0-stage → 0.20.0-next.0

package/dist/es/models/telemetryMetricIds.js

@@ -0,0 +1,13 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Metric IDs emitted by telemetry-processors.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TelemetryMetricIds = {
+    /**
+     * Total number of REST requests received.
+     */
+    RestRequests: "rest_requests"
+};
+//# sourceMappingURL=telemetryMetricIds.js.map

package/dist/es/models/telemetryMetricIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetryMetricIds.js","sourceRoot":"","sources":["../../../src/models/telemetryMetricIds.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC;;OAEG;IACH,YAAY,EAAE,eAAe;CACpB,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Metric IDs emitted by telemetry-processors.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const TelemetryMetricIds = {\n\t/**\n\t * Total number of REST requests received.\n\t */\n\tRestRequests: \"rest_requests\"\n} as const;\n\n/**\n * Metric IDs emitted by telemetry-processors.\n */\nexport type TelemetryMetricIds = (typeof TelemetryMetricIds)[keyof typeof TelemetryMetricIds];\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./metricsRouteProcessor.js";
+export * from "./models/IMetricsRouteProcessorConfig.js";
+export * from "./models/IMetricsRouteProcessorConstructorOptions.js";
+export * from "./models/IPendingMetricRecording.js";
+export * from "./models/restRequestsMetrics.js";
+export * from "./models/telemetryMetricIds.js";

package/dist/types/metricsRouteProcessor.d.ts

@@ -0,0 +1,65 @@
+import type { IBaseRoute, IBaseRouteProcessor, IHttpResponse, IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { IMetricsRouteProcessorConstructorOptions } from "./models/IMetricsRouteProcessorConstructorOptions.js";
+/**
+ * Route processor that records HTTP request counts after each request completes.
+ * Emits a single counter labelled with the HTTP method, route template, and status class.
+ * Raw request URLs are never used as labels to keep cardinality bounded.
+ * Recording is queued off the response path, so the reply never waits for telemetry storage.
+ */
+export declare class MetricsRouteProcessor implements IBaseRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Default number of request values to retain.
+     */
+    static readonly DEFAULT_MAX_HISTORY: number;
+    /**
+     * Default path prefixes excluded from metrics recording, the probe and info routes.
+     * The root entry is matched in full, so the routes below it are still recorded.
+     */
+    static readonly DEFAULT_EXCLUDE_PATHS: string[];
+    /**
+     * Default number of recordings queued before new ones are dropped.
+     */
+    static readonly DEFAULT_MAX_PENDING_RECORDINGS: number;
+    /**
+     * Default interval in milliseconds between drains of the queue.
+     */
+    static readonly DEFAULT_DRAIN_INTERVAL_MS: number;
+    /**
+     * Create a new instance of MetricsRouteProcessor.
+     * @param options The options for the processor.
+     */
+    constructor(options?: IMetricsRouteProcessorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Register all REST request metrics and start the timer which drains the queued recordings.
+     * @returns A promise that resolves when all metrics have been registered.
+     */
+    start(): Promise<void>;
+    /**
+     * Clear the drain timer and hand over the recordings which are still queued.
+     * When a drain is already running it finishes the batch it took, and anything queued after
+     * that is left unwritten rather than holding the shutdown open.
+     * @returns A promise that resolves when the queued recordings have been handed over.
+     */
+    stop(): Promise<void>;
+    /**
+     * Queue a counter increment after the request completes.
+     * @param request The HTTP request.
+     * @param response The HTTP response.
+     * @param route The matched route definition, if any.
+     * @param contextIds The context IDs for the request.
+     * @param processorState Shared state for the current request processor chain.
+     */
+    post(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/models/IMetricsRouteProcessorConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Configuration for the MetricsRouteProcessor.
+ */
+export interface IMetricsRouteProcessorConfig {
+    /**
+     * URL path prefixes that should not be recorded as metrics, with the root path "/" matched in
+     * full so the routes below it are still recorded.
+     * Useful for suppressing noise from health-check or metrics-scrape endpoints. Supplying this
+     * replaces the defaults rather than adding to them, so include the probe paths to keep them
+     * excluded, or an empty array to record every route.
+     * @default ["/", "/favicon.ico", "/spec", "/livez", "/readyz", "/info", "/health"].
+     */
+    excludePaths?: string[];
+    /**
+     * Maximum number of request values to retain. A value is recorded for every request that
+     * is not excluded, so without a cap the history grows for as long as the node serves
+     * traffic; values <= 0 retain everything.
+     * @default 10000.
+     */
+    maxHistory?: number;
+    /**
+     * Maximum number of recordings queued off the response path before new ones are dropped.
+     * Recording never blocks the response, so without a cap a telemetry component slower than the
+     * request rate would queue values without bound; values <= 0 queue everything.
+     * @default 1000.
+     */
+    maxPendingRecordings?: number;
+    /**
+     * Interval in milliseconds between drains of the queued recordings; values <= 0 use the
+     * default.
+     * @default 1000.
+     */
+    drainIntervalMs?: number;
+}

package/dist/types/models/IMetricsRouteProcessorConstructorOptions.d.ts

@@ -0,0 +1,18 @@
+import type { IMetricsRouteProcessorConfig } from "./IMetricsRouteProcessorConfig.js";
+/**
+ * Constructor options for the MetricsRouteProcessor.
+ */
+export interface IMetricsRouteProcessorConstructorOptions {
+    /**
+     * The component type to use for the telemetry component.
+     */
+    telemetryComponentType?: string;
+    /**
+     * The component type to use for logging metric recording failures.
+     */
+    loggingComponentType?: string;
+    /**
+     * Optional processor configuration.
+     */
+    config?: IMetricsRouteProcessorConfig;
+}

package/dist/types/models/IPendingMetricRecording.d.ts

@@ -0,0 +1,27 @@
+import type { IContextIds } from "@3sixty/context";
+/**
+ * A request metric queued by the metrics route processor, waiting to be handed to the
+ * telemetry component.
+ */
+export interface IPendingMetricRecording {
+    /**
+     * The context IDs of the request, used to record the metric in that request's context.
+     */
+    contextIds: IContextIds;
+    /**
+     * The HTTP method of the request.
+     */
+    method: string;
+    /**
+     * The route template path of the request.
+     */
+    route: string;
+    /**
+     * The HTTP status code of the response.
+     */
+    statusCode: number;
+    /**
+     * The status class of the response.
+     */
+    statusClass: string;
+}

package/dist/types/models/restRequestsMetrics.d.ts

@@ -0,0 +1,5 @@
+import { type ITelemetryMetric } from "@3sixty/telemetry-models";
+/**
+ * Metrics registered by the metrics route processor.
+ */
+export declare const RestRequestsMetrics: ITelemetryMetric[];

package/dist/types/models/telemetryMetricIds.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Metric IDs emitted by telemetry-processors.
+ */
+export declare const TelemetryMetricIds: {
+    /**
+     * Total number of REST requests received.
+     */
+    readonly RestRequests: "rest_requests";
+};
+/**
+ * Metric IDs emitted by telemetry-processors.
+ */
+export type TelemetryMetricIds = (typeof TelemetryMetricIds)[keyof typeof TelemetryMetricIds];

package/docs/examples.md

@@ -0,0 +1,37 @@
+# Telemetry Processors Examples
+
+These examples show how to register the request counter and record route metrics after an HTTP request completes.
+
+## MetricsRouteProcessor
+
+```typescript
+import { ComponentFactory } from '@3sixty/core';
+import { SilentTelemetryConnector } from '@3sixty/telemetry-models';
+import { MetricsRouteProcessor } from '@3sixty/telemetry-processors';
+
+ComponentFactory.register('telemetry', () => new SilentTelemetryConnector());
+
+// The probe and info routes are excluded by default; supplying excludePaths replaces that
+// list, so include them to keep them excluded.
+const processor = new MetricsRouteProcessor({
+  telemetryComponentType: 'telemetry',
+  config: { excludePaths: ['/livez', '/readyz', '/info', '/metrics'] }
+});
+
+console.log(processor.className()); // metricsRouteProcessor
+
+// start also starts the timer which drains the queued recordings.
+await processor.start();
+
+// post only queues the recording, so the response is not charged with storage latency.
+await processor.post(
+  { method: 'GET', url: '/api/v1/items/abc123' },
+  { statusCode: 200 },
+  { operationId: 'getItem', path: '/api/v1/items/:id' },
+  {},
+  {}
+);
+
+// stop clears the timer and hands over anything still queued.
+await processor.stop();
+```

package/docs/reference/classes/MetricsRouteProcessor.md

@@ -0,0 +1,173 @@
+# Class: MetricsRouteProcessor
+
+Route processor that records HTTP request counts after each request completes.
+Emits a single counter labelled with the HTTP method, route template, and status class.
+Raw request URLs are never used as labels to keep cardinality bounded.
+Recording is queued off the response path, so the reply never waits for telemetry storage.
+
+## Implements
+
+- `IBaseRouteProcessor`
+
+## Constructors
+
+### Constructor
+
+> **new MetricsRouteProcessor**(`options?`): `MetricsRouteProcessor`
+
+Create a new instance of MetricsRouteProcessor.
+
+#### Parameters
+
+##### options?
+
+[`IMetricsRouteProcessorConstructorOptions`](../interfaces/IMetricsRouteProcessorConstructorOptions.md)
+
+The options for the processor.
+
+#### Returns
+
+`MetricsRouteProcessor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### DEFAULT\_MAX\_HISTORY {#default_max_history}
+
+> `readonly` `static` **DEFAULT\_MAX\_HISTORY**: `number` = `10000`
+
+Default number of request values to retain.
+
+***
+
+### DEFAULT\_EXCLUDE\_PATHS {#default_exclude_paths}
+
+> `readonly` `static` **DEFAULT\_EXCLUDE\_PATHS**: `string`[]
+
+Default path prefixes excluded from metrics recording, the probe and info routes.
+The root entry is matched in full, so the routes below it are still recorded.
+
+***
+
+### DEFAULT\_MAX\_PENDING\_RECORDINGS {#default_max_pending_recordings}
+
+> `readonly` `static` **DEFAULT\_MAX\_PENDING\_RECORDINGS**: `number` = `1000`
+
+Default number of recordings queued before new ones are dropped.
+
+***
+
+### DEFAULT\_DRAIN\_INTERVAL\_MS {#default_drain_interval_ms}
+
+> `readonly` `static` **DEFAULT\_DRAIN\_INTERVAL\_MS**: `number` = `1000`
+
+Default interval in milliseconds between drains of the queue.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IBaseRouteProcessor.className`
+
+***
+
+### start() {#start}
+
+> **start**(): `Promise`\<`void`\>
+
+Register all REST request metrics and start the timer which drains the queued recordings.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when all metrics have been registered.
+
+#### Implementation of
+
+`IBaseRouteProcessor.start`
+
+***
+
+### stop() {#stop}
+
+> **stop**(): `Promise`\<`void`\>
+
+Clear the drain timer and hand over the recordings which are still queued.
+When a drain is already running it finishes the batch it took, and anything queued after
+that is left unwritten rather than holding the shutdown open.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the queued recordings have been handed over.
+
+#### Implementation of
+
+`IBaseRouteProcessor.stop`
+
+***
+
+### post() {#post}
+
+> **post**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
+
+Queue a counter increment after the request completes.
+
+#### Parameters
+
+##### request
+
+`IHttpServerRequest`
+
+The HTTP request.
+
+##### response
+
+`IHttpResponse`
+
+The HTTP response.
+
+##### route
+
+`IBaseRoute` \| `undefined`
+
+The matched route definition, if any.
+
+##### contextIds
+
+`IContextIds`
+
+The context IDs for the request.
+
+##### processorState
+
+Shared state for the current request processor chain.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IBaseRouteProcessor.post`

package/docs/reference/index.md

@@ -0,0 +1,20 @@
+# @3sixty/telemetry-processors
+
+## Classes
+
+- [MetricsRouteProcessor](classes/MetricsRouteProcessor.md)
+
+## Interfaces
+
+- [IMetricsRouteProcessorConfig](interfaces/IMetricsRouteProcessorConfig.md)
+- [IMetricsRouteProcessorConstructorOptions](interfaces/IMetricsRouteProcessorConstructorOptions.md)
+- [IPendingMetricRecording](interfaces/IPendingMetricRecording.md)
+
+## Type Aliases
+
+- [TelemetryMetricIds](type-aliases/TelemetryMetricIds.md)
+
+## Variables
+
+- [RestRequestsMetrics](variables/RestRequestsMetrics.md)
+- [TelemetryMetricIds](variables/TelemetryMetricIds.md)

package/docs/reference/interfaces/IMetricsRouteProcessorConfig.md

@@ -0,0 +1,68 @@
+# Interface: IMetricsRouteProcessorConfig
+
+Configuration for the MetricsRouteProcessor.
+
+## Properties
+
+### excludePaths? {#excludepaths}
+
+> `optional` **excludePaths?**: `string`[]
+
+URL path prefixes that should not be recorded as metrics, with the root path "/" matched in
+full so the routes below it are still recorded.
+Useful for suppressing noise from health-check or metrics-scrape endpoints. Supplying this
+replaces the defaults rather than adding to them, so include the probe paths to keep them
+excluded, or an empty array to record every route.
+
+#### Default
+
+```ts
+["/", "/favicon.ico", "/spec", "/livez", "/readyz", "/info", "/health"].
+```
+
+***
+
+### maxHistory? {#maxhistory}
+
+> `optional` **maxHistory?**: `number`
+
+Maximum number of request values to retain. A value is recorded for every request that
+is not excluded, so without a cap the history grows for as long as the node serves
+traffic; values <= 0 retain everything.
+
+#### Default
+
+```ts
+10000.
+```
+
+***
+
+### maxPendingRecordings? {#maxpendingrecordings}
+
+> `optional` **maxPendingRecordings?**: `number`
+
+Maximum number of recordings queued off the response path before new ones are dropped.
+Recording never blocks the response, so without a cap a telemetry component slower than the
+request rate would queue values without bound; values <= 0 queue everything.
+
+#### Default
+
+```ts
+1000.
+```
+
+***
+
+### drainIntervalMs? {#drainintervalms}
+
+> `optional` **drainIntervalMs?**: `number`
+
+Interval in milliseconds between drains of the queued recordings; values <= 0 use the
+default.
+
+#### Default
+
+```ts
+1000.
+```

package/docs/reference/interfaces/IMetricsRouteProcessorConstructorOptions.md

@@ -0,0 +1,27 @@
+# Interface: IMetricsRouteProcessorConstructorOptions
+
+Constructor options for the MetricsRouteProcessor.
+
+## Properties
+
+### telemetryComponentType? {#telemetrycomponenttype}
+
+> `optional` **telemetryComponentType?**: `string`
+
+The component type to use for the telemetry component.
+
+***
+
+### loggingComponentType? {#loggingcomponenttype}
+
+> `optional` **loggingComponentType?**: `string`
+
+The component type to use for logging metric recording failures.
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`IMetricsRouteProcessorConfig`](IMetricsRouteProcessorConfig.md)
+
+Optional processor configuration.

package/docs/reference/interfaces/IPendingMetricRecording.md

@@ -0,0 +1,44 @@
+# Interface: IPendingMetricRecording
+
+A request metric queued by the metrics route processor, waiting to be handed to the
+telemetry component.
+
+## Properties
+
+### contextIds {#contextids}
+
+> **contextIds**: `IContextIds`
+
+The context IDs of the request, used to record the metric in that request's context.
+
+***
+
+### method {#method}
+
+> **method**: `string`
+
+The HTTP method of the request.
+
+***
+
+### route {#route}
+
+> **route**: `string`
+
+The route template path of the request.
+
+***
+
+### statusCode {#statuscode}
+
+> **statusCode**: `number`
+
+The HTTP status code of the response.
+
+***
+
+### statusClass {#statusclass}
+
+> **statusClass**: `string`
+
+The status class of the response.

package/docs/reference/type-aliases/TelemetryMetricIds.md

@@ -0,0 +1,5 @@
+# Type Alias: TelemetryMetricIds
+
+> **TelemetryMetricIds** = *typeof* [`TelemetryMetricIds`](../variables/TelemetryMetricIds.md)\[keyof *typeof* [`TelemetryMetricIds`](../variables/TelemetryMetricIds.md)\]
+
+Metric IDs emitted by telemetry-processors.

package/docs/reference/variables/RestRequestsMetrics.md

@@ -0,0 +1,5 @@
+# Variable: RestRequestsMetrics
+
+> `const` **RestRequestsMetrics**: `ITelemetryMetric`[]
+
+Metrics registered by the metrics route processor.

package/docs/reference/variables/TelemetryMetricIds.md

@@ -0,0 +1,13 @@
+# Variable: TelemetryMetricIds
+
+> `const` **TelemetryMetricIds**: `object`
+
+Metric IDs emitted by telemetry-processors.
+
+## Type Declaration
+
+### RestRequests {#restrequests}
+
+> `readonly` **RestRequests**: `"rest_requests"` = `"rest_requests"`
+
+Total number of REST requests received.

package/locales/en.json

@@ -0,0 +1,9 @@
+{
+	"warn": {
+		"metricsRouteProcessor": {
+			"metricRecordsFailed": "Failed to record \"{count}\" request metrics",
+			"metricDrainFailed": "Failed to hand the queued request metrics to the telemetry component",
+			"metricRecordsDropped": "Dropped \"{count}\" request metrics because the recording queue was full"
+		}
+	}
+}

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "@3sixty/telemetry-processors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@3sixty/telemetry-processors",
+	"version": "0.20.0-next.0",
+	"description": "Route processors for recording telemetry metrics.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/3sixtyglobal/telemetry.git",
+		"directory": "packages/telemetry-processors"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"dependencies": {
+		"@3sixty/api-models": "next",
+		"@3sixty/context": "next",
+		"@3sixty/core": "next",
+		"@3sixty/logging-models": "next",
+		"@3sixty/nameof": "next",
+		"@3sixty/telemetry-models": "0.20.0-next.0"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	]
+}