@futdevpro/nts-dynamo 1.15.156 → 1.15.157

package/src/_services/core/request-telemetry.control-service.ts

@@ -0,0 +1,381 @@
+import { randomUUID } from 'crypto';
+import { NextFunction, Request, RequestHandler, Response } from 'express';
+
+import { DyNTS_resolveExposeHeaders } from '../../_collections/app-version-header.util';
+import {
+  DyNTS_RequestTelemetry_Settings
+} from '../../_models/interfaces/request-telemetry-settings.interface';
+import {
+  DyNTS_RequestDurationBucket_Interface,
+  DyNTS_RequestRouteMetric_Interface,
+  DyNTS_RequestTelemetrySnapshot_Interface
+} from '../../_models/interfaces/request-telemetry-snapshot.interface';
+
+const correlationHeader: 'X-Correlation-Id' = 'X-Correlation-Id';
+const contractVersion: 'dynts-request-telemetry/1' = 'dynts-request-telemetry/1';
+const defaultDurationBuckets: number[] = [ 25, 100, 250, 1000, 5000 ];
+const defaultMaxRouteCardinality: number = 128;
+const otherRouteTemplate: string = '__other__';
+const unmatchedRouteTemplate: string = '__unmatched__';
+const allowedMethods: ReadonlySet<string> = new Set([ 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT' ]);
+const routeTemplatePattern: RegExp = /^\/[A-Za-z0-9_:/.*-]{0,159}$/;
+
+interface DyNTS_RequestTelemetryResolvedSettings_Interface {
+  enabled: boolean;
+  maxRouteCardinality: number;
+  durationBucketUpperBoundsMs: number[];
+}
+
+interface DyNTS_RequestTelemetryState_Interface {
+  startedAtMs: number;
+  routeTemplate: string;
+  correlationId: string;
+}
+
+interface DyNTS_RequestRouteAccumulator_Interface extends DyNTS_RequestRouteMetric_Interface {}
+
+interface DyNTS_RequestRouteObservation_Interface {
+  method: string;
+  routeTemplate: string;
+  statusCode: number;
+  durationMs: number;
+  aborted: boolean;
+}
+
+/**
+ * Event-driven, content-free request correlation and aggregate metrics.
+ *
+ * The service never reads or stores URL, query, headers, body, IP, user agent, account identity or error content.
+ * Route labels can only come from the framework's declared route templates. Caller-provided correlation values are
+ * ignored and replaced with a server-generated UUID.
+ */
+export class DyNTS_RequestTelemetry_ControlService {
+  private static instance: DyNTS_RequestTelemetry_ControlService;
+
+  /** Returns the process-wide request telemetry accumulator used by open and secure Express applications. */
+  public static getInstance(): DyNTS_RequestTelemetry_ControlService {
+    if (!DyNTS_RequestTelemetry_ControlService.instance) {
+      DyNTS_RequestTelemetry_ControlService.instance = new DyNTS_RequestTelemetry_ControlService();
+    }
+
+    return DyNTS_RequestTelemetry_ControlService.instance;
+  }
+
+  private settings: DyNTS_RequestTelemetryResolvedSettings_Interface = this.resolveSettings({});
+  private configurationFingerprint: string | null = null;
+  private requestStates: WeakMap<Request, DyNTS_RequestTelemetryState_Interface> = new WeakMap();
+  private readonly routeMetrics: Map<string, DyNTS_RequestRouteAccumulator_Interface> = new Map();
+  private readonly retainedRouteTemplates: Set<string> = new Set();
+  private durationCounts: number[] = this.settings.durationBucketUpperBoundsMs.map((): number => 0);
+  private overflowDurationCount: number = 0;
+  private readonly statusClassCounts: Record<string, number> = {
+    '1xx': 0,
+    '2xx': 0,
+    '3xx': 0,
+    '4xx': 0,
+    '5xx': 0,
+    other: 0,
+  };
+  private requestsStarted: number = 0;
+  private requestsCompleted: number = 0;
+  private requestsAborted: number = 0;
+  private inFlight: number = 0;
+  private droppedRouteTemplates: number = 0;
+
+  private constructor() {}
+
+  /** Installs one immutable configuration; repeated identical calls are idempotent. */
+  public configure(settings: DyNTS_RequestTelemetry_Settings): void {
+    const resolved: DyNTS_RequestTelemetryResolvedSettings_Interface = this.resolveSettings(settings);
+    const fingerprint: string = JSON.stringify(resolved);
+
+    if (this.configurationFingerprint && this.configurationFingerprint !== fingerprint) {
+      throw new Error('DYNTS|REQUEST_TELEMETRY|CONFIGURATION_CONFLICT');
+    }
+
+    if (this.configurationFingerprint === fingerprint) {
+      return;
+    }
+
+    this.settings = resolved;
+    this.configurationFingerprint = fingerprint;
+    this.durationCounts = resolved.durationBucketUpperBoundsMs.map((): number => 0);
+  }
+
+  /** Returns the early Express middleware that creates correlation and completion listeners. */
+  public createMiddleware(): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction): void => {
+      if (!this.settings.enabled) {
+        next();
+
+        return;
+      }
+
+      try {
+        this.beginRequest(req, res);
+      } catch {
+        // Telemetry is observation-only and must never change application response semantics.
+      }
+
+      next();
+    };
+  }
+
+  /** Returns a route-local middleware that labels only a framework-declared route template. */
+  public identifyRoute(routeTemplate: string): RequestHandler {
+    const safeRouteTemplate: string = this.normalizeRouteTemplate(routeTemplate);
+
+    return (req: Request, _res: Response, next: NextFunction): void => {
+      const state: DyNTS_RequestTelemetryState_Interface | undefined = this.requestStates.get(req);
+
+      if (state) {
+        state.routeTemplate = safeRouteTemplate;
+      }
+
+      next();
+    };
+  }
+
+  /** Returns the generated correlation ID for internal error/audit joins without reading request headers. */
+  public getCorrelationId(req: Request): string | undefined {
+    return this.requestStates.get(req)?.correlationId;
+  }
+
+  /** Returns a stable copy of all bounded aggregate counters. */
+  public snapshot(): DyNTS_RequestTelemetrySnapshot_Interface {
+    const durationBuckets: DyNTS_RequestDurationBucket_Interface[] = this.settings.durationBucketUpperBoundsMs.map(
+      (upperBoundMs: number, index: number): DyNTS_RequestDurationBucket_Interface => ({
+        upperBoundMs: upperBoundMs,
+        count: this.durationCounts[index],
+      })
+    );
+
+    durationBuckets.push({ upperBoundMs: null, count: this.overflowDurationCount });
+
+    return {
+      contractVersion: contractVersion,
+      correlationHeader: correlationHeader,
+      requestsStarted: this.requestsStarted,
+      requestsCompleted: this.requestsCompleted,
+      requestsAborted: this.requestsAborted,
+      inFlight: this.inFlight,
+      droppedRouteTemplates: this.droppedRouteTemplates,
+      statusClasses: { ...this.statusClassCounts },
+      durationBuckets: durationBuckets,
+      routes: [ ...this.routeMetrics.values() ]
+        .map((metric: DyNTS_RequestRouteAccumulator_Interface): DyNTS_RequestRouteMetric_Interface => ({
+          ...metric,
+        }))
+        .sort((first: DyNTS_RequestRouteMetric_Interface, second: DyNTS_RequestRouteMetric_Interface): number =>
+          `${first.method}:${first.routeTemplate}`.localeCompare(`${second.method}:${second.routeTemplate}`)
+        ),
+    };
+  }
+
+  /** Test-only reset for the process-wide singleton. */
+  public _resetForTesting(): void {
+    this.settings = this.resolveSettings({});
+    this.configurationFingerprint = null;
+    this.requestStates = new WeakMap();
+    this.routeMetrics.clear();
+    this.retainedRouteTemplates.clear();
+    this.durationCounts = this.settings.durationBucketUpperBoundsMs.map((): number => 0);
+    this.overflowDurationCount = 0;
+    Object.keys(this.statusClassCounts).forEach((key: string): void => {
+      this.statusClassCounts[key] = 0;
+    });
+    this.requestsStarted = 0;
+    this.requestsCompleted = 0;
+    this.requestsAborted = 0;
+    this.inFlight = 0;
+    this.droppedRouteTemplates = 0;
+  }
+
+  private beginRequest(req: Request, res: Response): void {
+    const state: DyNTS_RequestTelemetryState_Interface = {
+      startedAtMs: Date.now(),
+      routeTemplate: unmatchedRouteTemplate,
+      correlationId: randomUUID(),
+    };
+    const existingExposeHeader: string | number | string[] | undefined =
+      res.getHeader('Access-Control-Expose-Headers');
+
+    res.setHeader(correlationHeader, state.correlationId);
+    res.setHeader(
+      'Access-Control-Expose-Headers',
+      DyNTS_resolveExposeHeaders(
+        typeof existingExposeHeader === 'string' ? existingExposeHeader : undefined,
+        correlationHeader
+      )
+    );
+
+    let settled: boolean = false;
+    /** Settles one response exactly once and removes both lifecycle listeners. */
+    const settle: (aborted: boolean) => void = (aborted: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      res.off('finish', onFinish);
+      res.off('close', onClose);
+
+      try {
+        this.completeRequest(req, res, aborted);
+      } catch {
+        // Telemetry is observation-only and must never surface a response-lifecycle failure.
+      }
+    };
+    /** Records a normally completed response. */
+    const onFinish: () => void = (): void => settle(false);
+    /** Records a connection closed before a normal finish. */
+    const onClose: () => void = (): void => settle(true);
+
+    try {
+      res.once('finish', onFinish);
+      res.once('close', onClose);
+    } catch (error: unknown) {
+      res.off('finish', onFinish);
+      res.off('close', onClose);
+
+      throw error;
+    }
+
+    this.requestStates.set(req, state);
+    this.requestsStarted = this.safeIncrement(this.requestsStarted);
+    this.inFlight = this.safeIncrement(this.inFlight);
+  }
+
+  private completeRequest(req: Request, res: Response, aborted: boolean): void {
+    const state: DyNTS_RequestTelemetryState_Interface | undefined = this.requestStates.get(req);
+
+    if (!state) {
+      return;
+    }
+
+    this.requestStates.delete(req);
+    this.inFlight = Math.max(0, this.inFlight - 1);
+    const durationMs: number = Math.max(0, Date.now() - state.startedAtMs);
+
+    this.recordDuration(durationMs);
+
+    if (aborted) {
+      this.requestsAborted = this.safeIncrement(this.requestsAborted);
+    } else {
+      this.requestsCompleted = this.safeIncrement(this.requestsCompleted);
+      this.recordStatusClass(res.statusCode);
+    }
+
+    this.recordRouteMetric({
+      method: req.method,
+      routeTemplate: state.routeTemplate,
+      statusCode: res.statusCode,
+      durationMs: durationMs,
+      aborted: aborted,
+    });
+  }
+
+  private recordDuration(durationMs: number): void {
+    const bucketIndex: number = this.settings.durationBucketUpperBoundsMs.findIndex(
+      (upperBoundMs: number): boolean => durationMs <= upperBoundMs
+    );
+
+    if (bucketIndex === -1) {
+      this.overflowDurationCount = this.safeIncrement(this.overflowDurationCount);
+
+      return;
+    }
+
+    this.durationCounts[bucketIndex] = this.safeIncrement(this.durationCounts[bucketIndex]);
+  }
+
+  private recordStatusClass(statusCode: number): void {
+    const statusClass: string = Number.isInteger(statusCode) && statusCode >= 100 && statusCode <= 599
+      ? `${Math.floor(statusCode / 100)}xx`
+      : 'other';
+
+    this.statusClassCounts[statusClass] = this.safeIncrement(this.statusClassCounts[statusClass]);
+  }
+
+  private recordRouteMetric(observation: DyNTS_RequestRouteObservation_Interface): void {
+    const safeMethod: string = allowedMethods.has(observation.method) ? observation.method : 'OTHER';
+    let safeRouteTemplate: string = observation.routeTemplate;
+    let routeKey: string = `${safeMethod}:${safeRouteTemplate}`;
+    let metric: DyNTS_RequestRouteAccumulator_Interface | undefined = this.routeMetrics.get(routeKey);
+
+    if (safeRouteTemplate === otherRouteTemplate) {
+      this.droppedRouteTemplates = this.safeIncrement(this.droppedRouteTemplates);
+    } else if (safeRouteTemplate !== unmatchedRouteTemplate && !this.retainedRouteTemplates.has(safeRouteTemplate)) {
+      if (this.retainedRouteTemplates.size >= this.settings.maxRouteCardinality) {
+        this.droppedRouteTemplates = this.safeIncrement(this.droppedRouteTemplates);
+        safeRouteTemplate = otherRouteTemplate;
+        routeKey = `${safeMethod}:${safeRouteTemplate}`;
+        metric = this.routeMetrics.get(routeKey);
+      } else {
+        this.retainedRouteTemplates.add(safeRouteTemplate);
+      }
+    }
+
+    if (!metric) {
+      metric = {
+        method: safeMethod,
+        routeTemplate: safeRouteTemplate,
+        count: 0,
+        abortedCount: 0,
+        serverErrorCount: 0,
+        totalDurationMs: 0,
+        maxDurationMs: 0,
+      };
+      this.routeMetrics.set(routeKey, metric);
+    }
+
+    metric.count = this.safeIncrement(metric.count);
+    metric.abortedCount = observation.aborted ? this.safeIncrement(metric.abortedCount) : metric.abortedCount;
+    metric.serverErrorCount = !observation.aborted && observation.statusCode >= 500 && observation.statusCode <= 599
+      ? this.safeIncrement(metric.serverErrorCount)
+      : metric.serverErrorCount;
+    metric.totalDurationMs = this.safeAdd(metric.totalDurationMs, observation.durationMs);
+    metric.maxDurationMs = Math.max(metric.maxDurationMs, observation.durationMs);
+  }
+
+  private normalizeRouteTemplate(routeTemplate: string): string {
+    return routeTemplatePattern.test(routeTemplate) ? routeTemplate : otherRouteTemplate;
+  }
+
+  private resolveSettings(
+    settings: DyNTS_RequestTelemetry_Settings
+  ): DyNTS_RequestTelemetryResolvedSettings_Interface {
+    const maxRouteCardinality: number = settings.maxRouteCardinality ?? defaultMaxRouteCardinality;
+    const durationBucketUpperBoundsMs: number[] = settings.durationBucketUpperBoundsMs ?? defaultDurationBuckets;
+
+    if (!Number.isInteger(maxRouteCardinality) || maxRouteCardinality < 1 || maxRouteCardinality > 1000) {
+      throw new Error('DYNTS|REQUEST_TELEMETRY|MAX_ROUTE_CARDINALITY_INVALID');
+    }
+
+    if (
+      !durationBucketUpperBoundsMs.length ||
+      durationBucketUpperBoundsMs.length > 16 ||
+      durationBucketUpperBoundsMs.some(
+        (value: number): boolean => !Number.isInteger(value) || value < 1 || value > 3_600_000
+      ) ||
+      durationBucketUpperBoundsMs.some(
+        (value: number, index: number): boolean => index > 0 && value <= durationBucketUpperBoundsMs[index - 1]
+      )
+    ) {
+      throw new Error('DYNTS|REQUEST_TELEMETRY|DURATION_BUCKETS_INVALID');
+    }
+
+    return {
+      enabled: settings.enabled === true,
+      maxRouteCardinality: maxRouteCardinality,
+      durationBucketUpperBoundsMs: [ ...durationBucketUpperBoundsMs ],
+    };
+  }
+
+  private safeIncrement(value: number): number {
+    return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
+  }
+
+  private safeAdd(first: number, second: number): number {
+    return first >= Number.MAX_SAFE_INTEGER - second ? Number.MAX_SAFE_INTEGER : first + second;
+  }
+}

package/src/_services/route/routing-module.service.ts

@@ -16,7 +16,8 @@ import {
 import {
   DyNTS_RoutingModule_Settings
 } from '../../_models/interfaces/routing-module-settings.interface';
-import { DyNTS_Controller } from './controller.service';
+import { DyNTS_Controller } from './controller.service';
+import { DyNTS_RequestTelemetry_ControlService } from '../core/request-telemetry.control-service';
 
 /**
  * Routing Module
@@ -226,26 +227,30 @@ export class DyNTS_RoutingModule {
    * 
    * @param endpointParams 
    */
-  private mountOpenRoute(endpointParams: DyNTS_Endpoint_Params): void {
-    switch (endpointParams.type) {
-      case DyFM_HttpCallType.get:
-        this.openRouter.get(endpointParams.endpoint, endpointParams.getFullExecution());
-        break;
+  private mountOpenRoute(endpointParams: DyNTS_Endpoint_Params): void {
+    const routeIdentity = DyNTS_RequestTelemetry_ControlService.getInstance().identifyRoute(
+      `${this.route}${endpointParams.endpoint}`
+    );
+
+    switch (endpointParams.type) {
+      case DyFM_HttpCallType.get:
+        this.openRouter.get(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
+        break;
 
       case DyFM_HttpCallType.post:
-        this.openRouter.post(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.openRouter.post(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.put:
-        this.openRouter.put(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.openRouter.put(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.patch:
-        this.openRouter.patch(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.openRouter.patch(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.delete:
-        this.openRouter.delete(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.openRouter.delete(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       default:
@@ -269,26 +274,30 @@ export class DyNTS_RoutingModule {
    * 
    * @param endpointParams 
    */
-  private mountSecureRoute(endpointParams: DyNTS_Endpoint_Params): void {
-    switch (endpointParams.type) {
-      case DyFM_HttpCallType.get:
-        this.secureRouter.get(endpointParams.endpoint, endpointParams.getFullExecution());
+  private mountSecureRoute(endpointParams: DyNTS_Endpoint_Params): void {
+    const routeIdentity = DyNTS_RequestTelemetry_ControlService.getInstance().identifyRoute(
+      `${this.route}${endpointParams.endpoint}`
+    );
+
+    switch (endpointParams.type) {
+      case DyFM_HttpCallType.get:
+        this.secureRouter.get(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.post:
-        this.secureRouter.post(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.secureRouter.post(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.put:
-        this.secureRouter.put(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.secureRouter.put(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.patch:
-        this.secureRouter.patch(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.secureRouter.patch(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       case DyFM_HttpCallType.delete:
-        this.secureRouter.delete(endpointParams.endpoint, endpointParams.getFullExecution());
+        this.secureRouter.delete(endpointParams.endpoint, routeIdentity, endpointParams.getFullExecution());
         break;
 
       default:

package/src/_services/server/app.server.ts

@@ -35,7 +35,8 @@ import { DyNTS_getEnvironment_settings } from '../../_collections/get-environmen
 import { DyNTS_createSecurityHeadersMiddleware } from '../../_collections/security-headers.util';
 import { DyNTS_createLoadShedMiddleware } from '../../_collections/load-shed.util';
 import { DyNTS_createAppVersionHeaderMiddleware } from '../../_collections/app-version-header.util';
-import { DyNTS_AppVersionHeader_Settings } from '../../_models/interfaces/app-version-header-settings.interface';
+import { DyNTS_AppVersionHeader_Settings } from '../../_models/interfaces/app-version-header-settings.interface';
+import { DyNTS_RequestTelemetry_Settings } from '../../_models/interfaces/request-telemetry-settings.interface';
 import { DyNTS_SecurityHeaders_Settings } from '../../_models/interfaces/security-headers-settings.interface';
 import { startMongoReconnectGuard } from '../../_collections/mongo-reconnect-guard.util';
 import { DyNTS_resolveStaticCacheControlHeader } from '../../_collections/static-cache-control.util';
@@ -65,7 +66,8 @@ import { DyNTS_SingletonService } from '../base/singleton.service';
 import { DyNTS_GlobalService } from '../core/global.service';
 import { DyNTS_CollectionGrowthMonitor } from '../core/collection-growth-monitor.service';
 import { DyNTS_MemoryGuard } from '../core/memory-guard.service';
-import { DyNTS_EventLoopDiag } from '../core/event-loop-diag.service';
+import { DyNTS_EventLoopDiag } from '../core/event-loop-diag.service';
+import { DyNTS_RequestTelemetry_ControlService } from '../core/request-telemetry.control-service';
 import { DyNTS_RoutingModule } from '../route/routing-module.service';
 import { DyNTS_getStarRoute } from '../../_collections/star.controller';
 import { DyNTS_SafeDiagnosticStage_Type } from '../../_modules/server/safe-diagnostic/safe-diagnostic-stage.type-enum';
@@ -1261,7 +1263,8 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     this.mountCors(this.openExpress);
     // FR-292 — a deployolt app-verzio minden valaszon. A CORS UTAN kell, mert az
     // `Access-Control-Expose-Headers`-hoz HOZZAFUZ (kulonben a CORS felulirna).
-    this.mountAppVersionHeader(this.openExpress);
+    this.mountAppVersionHeader(this.openExpress);
+    this.mountRequestTelemetry(this.openExpress);
     // BFR-OVERSEER-009 — opt-in auto-load-shed 503 CRITICAL memória-nyomásnál (esszenciális utak kivételével).
     if (DyNTS_global_settings.memoryGuard?.loadShedEnabled) {
       this.openExpress.use(DyNTS_createLoadShedMiddleware());
@@ -1281,7 +1284,8 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     // FR-041 — CORS allowlist enforcement (same as open express).
     this.mountCors(this.secureExpress);
     // FR-292 — a deployolt app-verzio minden valaszon (mint az open expressen).
-    this.mountAppVersionHeader(this.secureExpress);
+    this.mountAppVersionHeader(this.secureExpress);
+    this.mountRequestTelemetry(this.secureExpress);
     // BFR-OVERSEER-009 — opt-in auto-load-shed 503 (mint az open expressen).
     if (DyNTS_global_settings.memoryGuard?.loadShedEnabled) {
       this.secureExpress.use(DyNTS_createLoadShedMiddleware());
@@ -1299,7 +1303,7 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
   /**
    * 
    */
-  private async startExpresses(): Promise<void> {
+  private async startExpresses(): Promise<void> {
     if (this.fnLogs && this.deepLog) DyFM_Log.log('\nfn:. startExpresses');
 
     try {
@@ -1644,7 +1648,7 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
    * informativ response-header, ami se PII-t, se belso reszletet nem szivarogtat, viszont
    * enelkul minden app kulon-kulon epitene ugyanezt.
    */
-  protected mountAppVersionHeader(express: Express.Application): void {
+  protected mountAppVersionHeader(express: Express.Application): void {
     const settings: DyNTS_AppVersionHeader_Settings | undefined = DyNTS_global_settings.appVersionHeader;
     if (settings?.enabled === false) {
       return;
@@ -1652,8 +1656,21 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     express.use(DyNTS_createAppVersionHeaderMiddleware(
       (): string => DyNTS_global_settings.systemVersion,
       settings?.headerName,
-    ));
-  }
+    ));
+  }
+
+  /** Mounts opt-in correlation and aggregate metrics before load shedding and every API route. */
+  protected mountRequestTelemetry(express: Express.Application): void {
+    const settings: DyNTS_RequestTelemetry_Settings | undefined = this.getRequestTelemetrySettings?.();
+    if (settings?.enabled !== true) {
+      return;
+    }
+
+    const telemetry: DyNTS_RequestTelemetry_ControlService =
+      DyNTS_RequestTelemetry_ControlService.getInstance();
+    telemetry.configure(settings);
+    express.use(telemetry.createMiddleware());
+  }
 
   protected mountCors(express: Express.Application): void {
     const settings: DyNTS_Cors_Settings | undefined = this.getCorsSettings?.();
@@ -1932,7 +1949,10 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
    * cross-domain auth flow miatt. OPTIONS preflight 204-gyel rövidre záródik.
    * Ha undefined → no CORS headers, no preflight handling — back-compat.
    */
-  getCorsSettings?(): DyNTS_Cors_Settings | undefined;
+  getCorsSettings?(): DyNTS_Cors_Settings | undefined;
+
+  /** Enables content-free request correlation and event-driven aggregate metrics before API routing. */
+  getRequestTelemetrySettings?(): DyNTS_RequestTelemetry_Settings | undefined;
 
   /**
    * Opcionális generikus hook: custom Express middleware regisztrálása az API route-ok

package/src/index.ts

@@ -54,7 +54,9 @@ export * from './_models/interfaces/signed-url-verify-result.interface';
 export * from './_models/interfaces/static-client-settings.interface';
 export * from './_models/interfaces/cors-settings.interface';
 export * from './_models/interfaces/security-headers-settings.interface';
-export * from './_models/interfaces/app-version-header-settings.interface';
+export * from './_models/interfaces/app-version-header-settings.interface';
+export * from './_models/interfaces/request-telemetry-settings.interface';
+export * from './_models/interfaces/request-telemetry-snapshot.interface';
 export * from './_models/interfaces/db-query-options.interface';
 export * from './_models/interfaces/migration-entry.interface';
 export * from './_models/interfaces/mongo-transaction-settings.interface';
@@ -92,7 +94,8 @@ export * from './_services/core/auth.service';
 export * from './_services/core/email.service';
 export * from './_services/core/collection-growth-monitor.service';
 export * from './_services/core/global.service';
-export * from './_services/core/memory-guard.service';
+export * from './_services/core/memory-guard.service';
+export * from './_services/core/request-telemetry.control-service';
 
 export * from './_services/core/service-collection.service';
 export * from './_services/core/migration-runner.service';