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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 IOTA Stiftung.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# 3Sixty Telemetry Processors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Route processors for recording telemetry metrics from the web server.
+
+## Installation
+
+```shell
+npm install @3sixty/telemetry-processors
+```
+
+## Examples
+
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
+
+## Reference
+
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
+
+## Changelog
+
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)
+
+## Origin
+
+This package is derived from the original [iotaledger/twin-telemetry](https://github.com/iotaledger/twin-telemetry/tree/next/packages/telemetry-processors) repository.

package/dist/es/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+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";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0CAA0C,CAAC;AACzD,cAAc,sDAAsD,CAAC;AACrE,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./metricsRouteProcessor.js\";\nexport * from \"./models/IMetricsRouteProcessorConfig.js\";\nexport * from \"./models/IMetricsRouteProcessorConstructorOptions.js\";\nexport * from \"./models/IPendingMetricRecording.js\";\nexport * from \"./models/restRequestsMetrics.js\";\nexport * from \"./models/telemetryMetricIds.js\";\n"]}

package/dist/es/metricsRouteProcessor.js

@@ -0,0 +1,320 @@
+import { ContextIdStore } from "@3sixty/context";
+import { BaseError, Coerce, ComponentFactory, Is, JsonHelper, ObjectHelper } from "@3sixty/core";
+import { MetricCounterOperation, MetricHelper } from "@3sixty/telemetry-models";
+import { RestRequestsMetrics } from "./models/restRequestsMetrics.js";
+import { TelemetryMetricIds } from "./models/telemetryMetricIds.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 class MetricsRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "MetricsRouteProcessor";
+    /**
+     * Default number of request values to retain.
+     */
+    static DEFAULT_MAX_HISTORY = 10000;
+    /**
+     * 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 DEFAULT_EXCLUDE_PATHS = [
+        "/",
+        "/favicon.ico",
+        "/spec",
+        "/livez",
+        "/readyz",
+        "/info",
+        "/health"
+    ];
+    /**
+     * Default number of recordings queued before new ones are dropped.
+     */
+    static DEFAULT_MAX_PENDING_RECORDINGS = 1000;
+    /**
+     * Default interval in milliseconds between drains of the queue.
+     */
+    static DEFAULT_DRAIN_INTERVAL_MS = 1000;
+    /**
+     * Resolved telemetry component.
+     * @internal
+     */
+    _telemetry;
+    /**
+     * The component for logging metric recording failures.
+     * @internal
+     */
+    _logging;
+    /**
+     * Paths excluded from metrics recording.
+     * @internal
+     */
+    _excludePaths;
+    /**
+     * Maximum number of request values retained; 0 retains everything.
+     * @internal
+     */
+    _maxHistory;
+    /**
+     * Maximum number of recordings queued off the response path; 0 queues everything.
+     * @internal
+     */
+    _maxPendingRecordings;
+    /**
+     * Interval in milliseconds between drains of the queue.
+     * @internal
+     */
+    _drainIntervalMs;
+    /**
+     * Recordings queued but not yet handed to the telemetry component.
+     * @internal
+     */
+    _pending;
+    /**
+     * The timer which drains the queue.
+     * @internal
+     */
+    _drainTimer;
+    /**
+     * Is a drain of the queue in progress.
+     * @internal
+     */
+    _isDraining;
+    /**
+     * Number of recordings dropped since the last one that was recorded.
+     * @internal
+     */
+    _droppedRecordings;
+    /**
+     * Create a new instance of MetricsRouteProcessor.
+     * @param options The options for the processor.
+     */
+    constructor(options) {
+        this._telemetry = ComponentFactory.getIfExists(options?.telemetryComponentType);
+        this._logging = ComponentFactory.getIfExists(options?.loggingComponentType);
+        this._excludePaths =
+            options?.config?.excludePaths ?? MetricsRouteProcessor.DEFAULT_EXCLUDE_PATHS;
+        const cfgMaxHistory = Coerce.integer(options?.config?.maxHistory) ?? MetricsRouteProcessor.DEFAULT_MAX_HISTORY;
+        this._maxHistory = cfgMaxHistory > 0 ? cfgMaxHistory : 0;
+        const cfgMaxPending = Coerce.integer(options?.config?.maxPendingRecordings) ??
+            MetricsRouteProcessor.DEFAULT_MAX_PENDING_RECORDINGS;
+        this._maxPendingRecordings = cfgMaxPending > 0 ? cfgMaxPending : 0;
+        const cfgDrainInterval = Coerce.integer(options?.config?.drainIntervalMs) ??
+            MetricsRouteProcessor.DEFAULT_DRAIN_INTERVAL_MS;
+        this._drainIntervalMs =
+            cfgDrainInterval > 0 ? cfgDrainInterval : MetricsRouteProcessor.DEFAULT_DRAIN_INTERVAL_MS;
+        this._pending = [];
+        this._isDraining = false;
+        this._droppedRecordings = 0;
+    }
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return MetricsRouteProcessor.CLASS_NAME;
+    }
+    /**
+     * 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.
+     */
+    async start() {
+        // Guarded so a second start cannot leave the first interval running.
+        if (Is.undefined(this._telemetry) || !Is.undefined(this._drainTimer)) {
+            return;
+        }
+        // A value is recorded for every request, so the history is capped.
+        await MetricHelper.createMetrics(this._telemetry, RestRequestsMetrics.map(metric => ({
+            ...metric,
+            maxHistory: this._maxHistory > 0 ? this._maxHistory : undefined
+        })));
+        this._drainTimer = globalThis.setInterval(async () => {
+            try {
+                await this.drainPending();
+            }
+            catch (err) {
+                await this.logDrainFailed(err);
+            }
+        }, this._drainIntervalMs);
+    }
+    /**
+     * 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.
+     */
+    async stop() {
+        if (!Is.undefined(this._drainTimer)) {
+            globalThis.clearInterval(this._drainTimer);
+            this._drainTimer = undefined;
+        }
+        await this.drainPending();
+    }
+    /**
+     * 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.
+     */
+    async post(request, response, route, contextIds, processorState) {
+        if (Is.undefined(this._telemetry)) {
+            return;
+        }
+        const routePath = route?.path ?? "unknown";
+        // Entries are prefixes, apart from the root which is matched in full.
+        if (this._excludePaths.some(p => (p === "/" ? routePath === "/" : routePath.startsWith(p)))) {
+            return;
+        }
+        if (this._maxPendingRecordings > 0 && this._pending.length >= this._maxPendingRecordings) {
+            this._droppedRecordings++;
+            return;
+        }
+        // The reply is sent once the post hooks resolve, so the recording is left for the drain
+        // timer rather than written here.
+        this._pending.push({
+            contextIds: ObjectHelper.clone(contextIds),
+            method: request.method ?? "unknown",
+            route: routePath,
+            statusCode: response.statusCode ?? 0,
+            statusClass: this.toStatusClass(response.statusCode ?? 0)
+        });
+    }
+    /**
+     * Hand the recordings queued so far to the telemetry component, batched by context.
+     * @returns A promise that resolves when those recordings have been handed over.
+     * @internal
+     */
+    async drainPending() {
+        // One drain at a time, so a telemetry component slower than the request rate is not
+        // called concurrently by every tick of the timer.
+        if (this._isDraining) {
+            return;
+        }
+        this._isDraining = true;
+        try {
+            // Only the recordings queued so far are written, so requests arriving during the
+            // drain extend the next one rather than this one.
+            const recordings = this._pending.splice(0, this._pending.length);
+            const dropped = this._droppedRecordings;
+            this._droppedRecordings = 0;
+            if (dropped > 0) {
+                await this.logRecordsDropped(dropped);
+            }
+            const batches = new Map();
+            for (const recording of recordings) {
+                // Canonical key, so the same context ids group whatever order their keys are in.
+                const key = JsonHelper.canonicalize(recording.contextIds);
+                let batch = batches.get(key);
+                if (Is.undefined(batch)) {
+                    batch = { contextIds: recording.contextIds, values: [] };
+                    batches.set(key, batch);
+                }
+                batch.values.push({
+                    id: TelemetryMetricIds.RestRequests,
+                    value: MetricCounterOperation.Increment,
+                    customData: {
+                        method: recording.method,
+                        route: recording.route,
+                        statusCode: recording.statusCode,
+                        statusClass: recording.statusClass
+                    }
+                });
+            }
+            for (const batch of batches.values()) {
+                // One call per context, so a tenant-less batch costs a single tenant query and
+                // fan-out instead of one per request. Recorded in the requests' own context, and
+                // a batch which fails is logged rather than re-queued, so nothing accumulates
+                // while the component is unavailable.
+                await ContextIdStore.run(batch.contextIds, async () => MetricHelper.metricValues(this._telemetry, batch.values, async (err) => this.logRecordsFailed(err, batch.values.length)));
+            }
+        }
+        finally {
+            this._isDraining = false;
+        }
+    }
+    /**
+     * Log that a batch of request metrics could not be recorded.
+     * @param err The error the telemetry component raised.
+     * @param count The number of metrics in the batch.
+     * @returns A promise that resolves when the entry has been logged.
+     * @internal
+     */
+    async logRecordsFailed(err, count) {
+        await this._logging?.log({
+            level: "warn",
+            source: MetricsRouteProcessor.CLASS_NAME,
+            ts: Date.now(),
+            message: "metricRecordsFailed",
+            error: BaseError.fromError(err),
+            data: { count }
+        });
+    }
+    /**
+     * Log that the queue could not be drained.
+     * @param err The error the drain raised.
+     * @returns A promise that resolves when the entry has been logged.
+     * @internal
+     */
+    async logDrainFailed(err) {
+        await this._logging?.log({
+            level: "warn",
+            source: MetricsRouteProcessor.CLASS_NAME,
+            ts: Date.now(),
+            message: "metricDrainFailed",
+            error: BaseError.fromError(err)
+        });
+    }
+    /**
+     * Log the recordings dropped because the queue was full.
+     * @param count The number of recordings dropped.
+     * @returns A promise that resolves when the entry has been logged.
+     * @internal
+     */
+    async logRecordsDropped(count) {
+        try {
+            await this._logging?.log({
+                level: "warn",
+                source: MetricsRouteProcessor.CLASS_NAME,
+                ts: Date.now(),
+                message: "metricRecordsDropped",
+                data: { count }
+            });
+        }
+        catch {
+            // Carried into the next recording rather than lost, and absorbed so a broken logging
+            // component cannot reject the drain.
+            this._droppedRecordings += count;
+        }
+    }
+    /**
+     * Derive the status class label from a numeric HTTP status code.
+     * @param statusCode The HTTP status code.
+     * @returns The status class label (1xx, 2xx, 3xx, 4xx, 5xx, or unknown).
+     * @internal
+     */
+    toStatusClass(statusCode) {
+        if (statusCode >= 500) {
+            return "5xx";
+        }
+        if (statusCode >= 400) {
+            return "4xx";
+        }
+        if (statusCode >= 300) {
+            return "3xx";
+        }
+        if (statusCode >= 200) {
+            return "2xx";
+        }
+        if (statusCode >= 100) {
+            return "1xx";
+        }
+        return "unknown";
+    }
+}
+//# sourceMappingURL=metricsRouteProcessor.js.map

package/dist/es/metricsRouteProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metricsRouteProcessor.js","sourceRoot":"","sources":["../../src/metricsRouteProcessor.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type {\n\tIBaseRoute,\n\tIBaseRouteProcessor,\n\tIHttpResponse,\n\tIHttpServerRequest\n} from \"@3sixty/api-models\";\nimport { ContextIdStore, type IContextIds } from \"@3sixty/context\";\nimport { BaseError, Coerce, ComponentFactory, Is, JsonHelper, ObjectHelper } from \"@3sixty/core\";\nimport type { ILoggingComponent } from \"@3sixty/logging-models\";\nimport { nameof } from \"@3sixty/nameof\";\nimport {\n\tMetricCounterOperation,\n\tMetricHelper,\n\ttype ITelemetryComponent,\n\ttype ITelemetryMetricValueEntry\n} from \"@3sixty/telemetry-models\";\nimport type { IMetricsRouteProcessorConstructorOptions } from \"./models/IMetricsRouteProcessorConstructorOptions.js\";\nimport type { IPendingMetricRecording } from \"./models/IPendingMetricRecording.js\";\nimport { RestRequestsMetrics } from \"./models/restRequestsMetrics.js\";\nimport { TelemetryMetricIds } from \"./models/telemetryMetricIds.js\";\n\n/**\n * Route processor that records HTTP request counts after each request completes.\n * Emits a single counter labelled with the HTTP method, route template, and status class.\n * Raw request URLs are never used as labels to keep cardinality bounded.\n * Recording is queued off the response path, so the reply never waits for telemetry storage.\n */\nexport class MetricsRouteProcessor implements IBaseRouteProcessor {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<MetricsRouteProcessor>();\n\n\t/**\n\t * Default number of request values to retain.\n\t */\n\tpublic static readonly DEFAULT_MAX_HISTORY: number = 10000;\n\n\t/**\n\t * Default path prefixes excluded from metrics recording, the probe and info routes.\n\t * The root entry is matched in full, so the routes below it are still recorded.\n\t */\n\tpublic static readonly DEFAULT_EXCLUDE_PATHS: string[] = [\n\t\t\"/\",\n\t\t\"/favicon.ico\",\n\t\t\"/spec\",\n\t\t\"/livez\",\n\t\t\"/readyz\",\n\t\t\"/info\",\n\t\t\"/health\"\n\t];\n\n\t/**\n\t * Default number of recordings queued before new ones are dropped.\n\t */\n\tpublic static readonly DEFAULT_MAX_PENDING_RECORDINGS: number = 1000;\n\n\t/**\n\t * Default interval in milliseconds between drains of the queue.\n\t */\n\tpublic static readonly DEFAULT_DRAIN_INTERVAL_MS: number = 1000;\n\n\t/**\n\t * Resolved telemetry component.\n\t * @internal\n\t */\n\tprivate readonly _telemetry?: ITelemetryComponent;\n\n\t/**\n\t * The component for logging metric recording failures.\n\t * @internal\n\t */\n\tprivate readonly _logging?: ILoggingComponent;\n\n\t/**\n\t * Paths excluded from metrics recording.\n\t * @internal\n\t */\n\tprivate readonly _excludePaths: string[];\n\n\t/**\n\t * Maximum number of request values retained; 0 retains everything.\n\t * @internal\n\t */\n\tprivate readonly _maxHistory: number;\n\n\t/**\n\t * Maximum number of recordings queued off the response path; 0 queues everything.\n\t * @internal\n\t */\n\tprivate readonly _maxPendingRecordings: number;\n\n\t/**\n\t * Interval in milliseconds between drains of the queue.\n\t * @internal\n\t */\n\tprivate readonly _drainIntervalMs: number;\n\n\t/**\n\t * Recordings queued but not yet handed to the telemetry component.\n\t * @internal\n\t */\n\tprivate readonly _pending: IPendingMetricRecording[];\n\n\t/**\n\t * The timer which drains the queue.\n\t * @internal\n\t */\n\tprivate _drainTimer?: ReturnType<typeof setInterval>;\n\n\t/**\n\t * Is a drain of the queue in progress.\n\t * @internal\n\t */\n\tprivate _isDraining: boolean;\n\n\t/**\n\t * Number of recordings dropped since the last one that was recorded.\n\t * @internal\n\t */\n\tprivate _droppedRecordings: number;\n\n\t/**\n\t * Create a new instance of MetricsRouteProcessor.\n\t * @param options The options for the processor.\n\t */\n\tconstructor(options?: IMetricsRouteProcessorConstructorOptions) {\n\t\tthis._telemetry = ComponentFactory.getIfExists<ITelemetryComponent>(\n\t\t\toptions?.telemetryComponentType\n\t\t);\n\t\tthis._logging = ComponentFactory.getIfExists<ILoggingComponent>(options?.loggingComponentType);\n\t\tthis._excludePaths =\n\t\t\toptions?.config?.excludePaths ?? MetricsRouteProcessor.DEFAULT_EXCLUDE_PATHS;\n\n\t\tconst cfgMaxHistory =\n\t\t\tCoerce.integer(options?.config?.maxHistory) ?? MetricsRouteProcessor.DEFAULT_MAX_HISTORY;\n\t\tthis._maxHistory = cfgMaxHistory > 0 ? cfgMaxHistory : 0;\n\n\t\tconst cfgMaxPending =\n\t\t\tCoerce.integer(options?.config?.maxPendingRecordings) ??\n\t\t\tMetricsRouteProcessor.DEFAULT_MAX_PENDING_RECORDINGS;\n\t\tthis._maxPendingRecordings = cfgMaxPending > 0 ? cfgMaxPending : 0;\n\n\t\tconst cfgDrainInterval =\n\t\t\tCoerce.integer(options?.config?.drainIntervalMs) ??\n\t\t\tMetricsRouteProcessor.DEFAULT_DRAIN_INTERVAL_MS;\n\t\tthis._drainIntervalMs =\n\t\t\tcfgDrainInterval > 0 ? cfgDrainInterval : MetricsRouteProcessor.DEFAULT_DRAIN_INTERVAL_MS;\n\n\t\tthis._pending = [];\n\t\tthis._isDraining = false;\n\t\tthis._droppedRecordings = 0;\n\t}\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn MetricsRouteProcessor.CLASS_NAME;\n\t}\n\n\t/**\n\t * Register all REST request metrics and start the timer which drains the queued recordings.\n\t * @returns A promise that resolves when all metrics have been registered.\n\t */\n\tpublic async start(): Promise<void> {\n\t\t// Guarded so a second start cannot leave the first interval running.\n\t\tif (Is.undefined(this._telemetry) || !Is.undefined(this._drainTimer)) {\n\t\t\treturn;\n\t\t}\n\n\t\t// A value is recorded for every request, so the history is capped.\n\t\tawait MetricHelper.createMetrics(\n\t\t\tthis._telemetry,\n\t\t\tRestRequestsMetrics.map(metric => ({\n\t\t\t\t...metric,\n\t\t\t\tmaxHistory: this._maxHistory > 0 ? this._maxHistory : undefined\n\t\t\t}))\n\t\t);\n\n\t\tthis._drainTimer = globalThis.setInterval(async () => {\n\t\t\ttry {\n\t\t\t\tawait this.drainPending();\n\t\t\t} catch (err) {\n\t\t\t\tawait this.logDrainFailed(err);\n\t\t\t}\n\t\t}, this._drainIntervalMs);\n\t}\n\n\t/**\n\t * Clear the drain timer and hand over the recordings which are still queued.\n\t * When a drain is already running it finishes the batch it took, and anything queued after\n\t * that is left unwritten rather than holding the shutdown open.\n\t * @returns A promise that resolves when the queued recordings have been handed over.\n\t */\n\tpublic async stop(): Promise<void> {\n\t\tif (!Is.undefined(this._drainTimer)) {\n\t\t\tglobalThis.clearInterval(this._drainTimer);\n\t\t\tthis._drainTimer = undefined;\n\t\t}\n\n\t\tawait this.drainPending();\n\t}\n\n\t/**\n\t * Queue a counter increment after the request completes.\n\t * @param request The HTTP request.\n\t * @param response The HTTP response.\n\t * @param route The matched route definition, if any.\n\t * @param contextIds The context IDs for the request.\n\t * @param processorState Shared state for the current request processor chain.\n\t */\n\tpublic async post(\n\t\trequest: IHttpServerRequest,\n\t\tresponse: IHttpResponse,\n\t\troute: IBaseRoute | undefined,\n\t\tcontextIds: IContextIds,\n\t\tprocessorState: { [id: string]: unknown }\n\t): Promise<void> {\n\t\tif (Is.undefined(this._telemetry)) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst routePath = route?.path ?? \"unknown\";\n\n\t\t// Entries are prefixes, apart from the root which is matched in full.\n\t\tif (this._excludePaths.some(p => (p === \"/\" ? routePath === \"/\" : routePath.startsWith(p)))) {\n\t\t\treturn;\n\t\t}\n\n\t\tif (this._maxPendingRecordings > 0 && this._pending.length >= this._maxPendingRecordings) {\n\t\t\tthis._droppedRecordings++;\n\t\t\treturn;\n\t\t}\n\n\t\t// The reply is sent once the post hooks resolve, so the recording is left for the drain\n\t\t// timer rather than written here.\n\t\tthis._pending.push({\n\t\t\tcontextIds: ObjectHelper.clone(contextIds),\n\t\t\tmethod: request.method ?? \"unknown\",\n\t\t\troute: routePath,\n\t\t\tstatusCode: response.statusCode ?? 0,\n\t\t\tstatusClass: this.toStatusClass(response.statusCode ?? 0)\n\t\t});\n\t}\n\n\t/**\n\t * Hand the recordings queued so far to the telemetry component, batched by context.\n\t * @returns A promise that resolves when those recordings have been handed over.\n\t * @internal\n\t */\n\tprivate async drainPending(): Promise<void> {\n\t\t// One drain at a time, so a telemetry component slower than the request rate is not\n\t\t// called concurrently by every tick of the timer.\n\t\tif (this._isDraining) {\n\t\t\treturn;\n\t\t}\n\t\tthis._isDraining = true;\n\n\t\ttry {\n\t\t\t// Only the recordings queued so far are written, so requests arriving during the\n\t\t\t// drain extend the next one rather than this one.\n\t\t\tconst recordings = this._pending.splice(0, this._pending.length);\n\n\t\t\tconst dropped = this._droppedRecordings;\n\t\t\tthis._droppedRecordings = 0;\n\t\t\tif (dropped > 0) {\n\t\t\t\tawait this.logRecordsDropped(dropped);\n\t\t\t}\n\n\t\t\tconst batches = new Map<\n\t\t\t\tstring,\n\t\t\t\t{ contextIds: IContextIds; values: ITelemetryMetricValueEntry[] }\n\t\t\t>();\n\t\t\tfor (const recording of recordings) {\n\t\t\t\t// Canonical key, so the same context ids group whatever order their keys are in.\n\t\t\t\tconst key = JsonHelper.canonicalize(recording.contextIds);\n\t\t\t\tlet batch = batches.get(key);\n\t\t\t\tif (Is.undefined(batch)) {\n\t\t\t\t\tbatch = { contextIds: recording.contextIds, values: [] };\n\t\t\t\t\tbatches.set(key, batch);\n\t\t\t\t}\n\t\t\t\tbatch.values.push({\n\t\t\t\t\tid: TelemetryMetricIds.RestRequests,\n\t\t\t\t\tvalue: MetricCounterOperation.Increment,\n\t\t\t\t\tcustomData: {\n\t\t\t\t\t\tmethod: recording.method,\n\t\t\t\t\t\troute: recording.route,\n\t\t\t\t\t\tstatusCode: recording.statusCode,\n\t\t\t\t\t\tstatusClass: recording.statusClass\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tfor (const batch of batches.values()) {\n\t\t\t\t// One call per context, so a tenant-less batch costs a single tenant query and\n\t\t\t\t// fan-out instead of one per request. Recorded in the requests' own context, and\n\t\t\t\t// a batch which fails is logged rather than re-queued, so nothing accumulates\n\t\t\t\t// while the component is unavailable.\n\t\t\t\tawait ContextIdStore.run(batch.contextIds, async () =>\n\t\t\t\t\tMetricHelper.metricValues(this._telemetry, batch.values, async err =>\n\t\t\t\t\t\tthis.logRecordsFailed(err, batch.values.length)\n\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\t\t} finally {\n\t\t\tthis._isDraining = false;\n\t\t}\n\t}\n\n\t/**\n\t * Log that a batch of request metrics could not be recorded.\n\t * @param err The error the telemetry component raised.\n\t * @param count The number of metrics in the batch.\n\t * @returns A promise that resolves when the entry has been logged.\n\t * @internal\n\t */\n\tprivate async logRecordsFailed(err: unknown, count: number): Promise<void> {\n\t\tawait this._logging?.log({\n\t\t\tlevel: \"warn\",\n\t\t\tsource: MetricsRouteProcessor.CLASS_NAME,\n\t\t\tts: Date.now(),\n\t\t\tmessage: \"metricRecordsFailed\",\n\t\t\terror: BaseError.fromError(err),\n\t\t\tdata: { count }\n\t\t});\n\t}\n\n\t/**\n\t * Log that the queue could not be drained.\n\t * @param err The error the drain raised.\n\t * @returns A promise that resolves when the entry has been logged.\n\t * @internal\n\t */\n\tprivate async logDrainFailed(err: unknown): Promise<void> {\n\t\tawait this._logging?.log({\n\t\t\tlevel: \"warn\",\n\t\t\tsource: MetricsRouteProcessor.CLASS_NAME,\n\t\t\tts: Date.now(),\n\t\t\tmessage: \"metricDrainFailed\",\n\t\t\terror: BaseError.fromError(err)\n\t\t});\n\t}\n\n\t/**\n\t * Log the recordings dropped because the queue was full.\n\t * @param count The number of recordings dropped.\n\t * @returns A promise that resolves when the entry has been logged.\n\t * @internal\n\t */\n\tprivate async logRecordsDropped(count: number): Promise<void> {\n\t\ttry {\n\t\t\tawait this._logging?.log({\n\t\t\t\tlevel: \"warn\",\n\t\t\t\tsource: MetricsRouteProcessor.CLASS_NAME,\n\t\t\t\tts: Date.now(),\n\t\t\t\tmessage: \"metricRecordsDropped\",\n\t\t\t\tdata: { count }\n\t\t\t});\n\t\t} catch {\n\t\t\t// Carried into the next recording rather than lost, and absorbed so a broken logging\n\t\t\t// component cannot reject the drain.\n\t\t\tthis._droppedRecordings += count;\n\t\t}\n\t}\n\n\t/**\n\t * Derive the status class label from a numeric HTTP status code.\n\t * @param statusCode The HTTP status code.\n\t * @returns The status class label (1xx, 2xx, 3xx, 4xx, 5xx, or unknown).\n\t * @internal\n\t */\n\tprivate toStatusClass(statusCode: number): string {\n\t\tif (statusCode >= 500) {\n\t\t\treturn \"5xx\";\n\t\t}\n\t\tif (statusCode >= 400) {\n\t\t\treturn \"4xx\";\n\t\t}\n\t\tif (statusCode >= 300) {\n\t\t\treturn \"3xx\";\n\t\t}\n\t\tif (statusCode >= 200) {\n\t\t\treturn \"2xx\";\n\t\t}\n\t\tif (statusCode >= 100) {\n\t\t\treturn \"1xx\";\n\t\t}\n\t\treturn \"unknown\";\n\t}\n}\n"]}

package/dist/es/models/IMetricsRouteProcessorConfig.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMetricsRouteProcessorConfig.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IMetricsRouteProcessorConfig.js","sourceRoot":"","sources":["../../../src/models/IMetricsRouteProcessorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the MetricsRouteProcessor.\n */\nexport interface IMetricsRouteProcessorConfig {\n\t/**\n\t * URL path prefixes that should not be recorded as metrics, with the root path \"/\" matched in\n\t * full so the routes below it are still recorded.\n\t * Useful for suppressing noise from health-check or metrics-scrape endpoints. Supplying this\n\t * replaces the defaults rather than adding to them, so include the probe paths to keep them\n\t * excluded, or an empty array to record every route.\n\t * @default [\"/\", \"/favicon.ico\", \"/spec\", \"/livez\", \"/readyz\", \"/info\", \"/health\"].\n\t */\n\texcludePaths?: string[];\n\n\t/**\n\t * Maximum number of request values to retain. A value is recorded for every request that\n\t * is not excluded, so without a cap the history grows for as long as the node serves\n\t * traffic; values <= 0 retain everything.\n\t * @default 10000.\n\t */\n\tmaxHistory?: number;\n\n\t/**\n\t * Maximum number of recordings queued off the response path before new ones are dropped.\n\t * Recording never blocks the response, so without a cap a telemetry component slower than the\n\t * request rate would queue values without bound; values <= 0 queue everything.\n\t * @default 1000.\n\t */\n\tmaxPendingRecordings?: number;\n\n\t/**\n\t * Interval in milliseconds between drains of the queued recordings; values <= 0 use the\n\t * default.\n\t * @default 1000.\n\t */\n\tdrainIntervalMs?: number;\n}\n"]}

package/dist/es/models/IMetricsRouteProcessorConstructorOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMetricsRouteProcessorConstructorOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IMetricsRouteProcessorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IMetricsRouteProcessorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMetricsRouteProcessorConfig } from \"./IMetricsRouteProcessorConfig.js\";\n\n/**\n * Constructor options for the MetricsRouteProcessor.\n */\nexport interface IMetricsRouteProcessorConstructorOptions {\n\t/**\n\t * The component type to use for the telemetry component.\n\t */\n\ttelemetryComponentType?: string;\n\n\t/**\n\t * The component type to use for logging metric recording failures.\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * Optional processor configuration.\n\t */\n\tconfig?: IMetricsRouteProcessorConfig;\n}\n"]}

package/dist/es/models/IPendingMetricRecording.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IPendingMetricRecording.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IPendingMetricRecording.js","sourceRoot":"","sources":["../../../src/models/IPendingMetricRecording.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IContextIds } from \"@3sixty/context\";\n\n/**\n * A request metric queued by the metrics route processor, waiting to be handed to the\n * telemetry component.\n */\nexport interface IPendingMetricRecording {\n\t/**\n\t * The context IDs of the request, used to record the metric in that request's context.\n\t */\n\tcontextIds: IContextIds;\n\n\t/**\n\t * The HTTP method of the request.\n\t */\n\tmethod: string;\n\n\t/**\n\t * The route template path of the request.\n\t */\n\troute: string;\n\n\t/**\n\t * The HTTP status code of the response.\n\t */\n\tstatusCode: number;\n\n\t/**\n\t * The status class of the response.\n\t */\n\tstatusClass: string;\n}\n"]}

package/dist/es/models/restRequestsMetrics.js

@@ -0,0 +1,12 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { MetricType } from "@3sixty/telemetry-models";
+import { TelemetryMetricIds } from "./telemetryMetricIds.js";
+/**
+ * Metrics registered by the metrics route processor.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const RestRequestsMetrics = [
+    { id: TelemetryMetricIds.RestRequests, label: "REST requests", type: MetricType.Counter }
+];
+//# sourceMappingURL=restRequestsMetrics.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"restRequestsMetrics.js","sourceRoot":"","sources":["../../../src/models/restRequestsMetrics.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,UAAU,EAAyB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAuB;IACtD,EAAE,EAAE,EAAE,kBAAkB,CAAC,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE;CACzF,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { MetricType, type ITelemetryMetric } from \"@3sixty/telemetry-models\";\nimport { TelemetryMetricIds } from \"./telemetryMetricIds.js\";\n\n/**\n * Metrics registered by the metrics route processor.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const RestRequestsMetrics: ITelemetryMetric[] = [\n\t{ id: TelemetryMetricIds.RestRequests, label: \"REST requests\", type: MetricType.Counter }\n];\n"]}