@fluojs/metrics 1.0.4 → 3.0.0

package/dist/metrics-module.js

@@ -3,15 +3,19 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { Inject } from '@fluojs/core';
 import { ContainerResolutionError } from '@fluojs/di';
-import { Controller, Get, forRoutes } from '@fluojs/http';
+import { Controller, forRoutes, Get } from '@fluojs/http';
 import { defineModule, PLATFORM_SHELL } from '@fluojs/runtime';
+import { BOOTSTRAP_PROVIDER_TOKENS, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { collectDefaultMetrics, Gauge, Registry as PrometheusRegistry } from 'prom-client';
 import { HttpMetricsMiddleware } from './http-metrics-middleware.js';
-import { METER_PROVIDER } from './providers/meter-provider.js';
 import { MetricsService } from './metrics-service.js';
+import { METER_PROVIDER } from './providers/meter-provider.js';
 import { PrometheusMeterProvider } from './providers/prometheus-meter-provider.js';
+import { SerializedScrapeQueue } from './serialized-scrape-queue.js';
 
 /** HTTP-specific metric labeling options exposed by `MetricsModule.forRoot(...)`. */
 
@@ -19,6 +23,9 @@ import { PrometheusMeterProvider } from './providers/prometheus-meter-provider.j
  * Module options for exposing Prometheus metrics and runtime platform telemetry.
  */
 
+/** Bootstrap provider token for a Registry shared by metrics module instances. */
+export const METRICS_REGISTRY = Symbol.for('fluo.metrics.registry');
+
 /** Module entry point that exposes `/metrics` and optional HTTP/runtime telemetry. */
 export class MetricsModule {
   static registeredRegistries = new WeakSet();
@@ -30,11 +37,10 @@ export class MetricsModule {
    * ```ts
    * MetricsModule.forRoot({
    *   http: { pathLabelMode: 'template' },
-   *   registry: new Registry(),
    * });
    * ```
    *
-   * @param options Metrics endpoint, registry, HTTP middleware, and runtime telemetry configuration.
+   * @param options Metrics endpoint, HTTP middleware, and runtime telemetry configuration.
    * @returns A runtime module that exposes metrics through the configured path.
    */
   static forRoot(options = {}) {
@@ -48,13 +54,31 @@ export class MetricsModule {
     const platformTelemetryToken = Symbol('MetricsModule.platformTelemetry');
     const httpMetricsMiddleware = httpOptions ? createHttpMetricsMiddleware(registryToken, httpOptions) : undefined;
     const endpointMiddleware = typeof metricsPath === 'string' ? (options.endpointMiddleware ?? []).map(middlewareClass => forRoutes(middlewareClass, metricsPath)) : [];
-    const middleware = [...(httpMetricsMiddleware ? [httpMetricsMiddleware] : []), ...endpointMiddleware, ...(options.middleware ?? [])];
-    const providers = [...(httpMetricsMiddleware ? [httpMetricsMiddleware] : []), {
+    const middleware = [...endpointMiddleware, ...(options.middleware ?? [])];
+    const registryProvider = {
       provide: registryToken,
-      useFactory: () => MetricsModule.createRegistry(options)
-    }, {
+      inject: [RUNTIME_CONTAINER, BOOTSTRAP_PROVIDER_TOKENS],
+      useFactory: async (container, bootstrapProviderTokens) => {
+        const runtimeContainer = assertRuntimeContainer(container);
+        const configuredRegistry = assertBootstrapProviderTokens(bootstrapProviderTokens).has(METRICS_REGISTRY) ? assertPrometheusRegistry(await runtimeContainer.resolve(METRICS_REGISTRY)) : undefined;
+        return MetricsModule.createRegistry(options, configuredRegistry);
+      }
+    };
+    const imports = [];
+    const includeRuntimeRegistryProvider = httpMetricsMiddleware === undefined;
+    if (httpOptions && httpMetricsMiddleware) {
+      class MetricsHttpInstrumentationModule {}
+      defineModule(MetricsHttpInstrumentationModule, {
+        exports: [registryToken],
+        global: true,
+        middleware: [httpMetricsMiddleware],
+        providers: [registryProvider, httpMetricsMiddleware]
+      });
+      imports.push(MetricsHttpInstrumentationModule);
+    }
+    const providers = [...(includeRuntimeRegistryProvider ? [registryProvider] : []), {
       provide: MetricsService,
-      inject: [registryToken],
+      inject: [registryToken, platformTelemetryToken],
       useFactory: registry => new MetricsService(assertPrometheusRegistry(registry))
     }, {
       provide: METER_PROVIDER,
@@ -62,8 +86,8 @@ export class MetricsModule {
       useFactory: registry => new PrometheusMeterProvider(assertPrometheusRegistry(registry))
     }, {
       provide: platformTelemetryToken,
-      inject: [registryToken],
-      useFactory: registry => new RuntimePlatformTelemetry(assertPrometheusRegistry(registry), options.registry ? 'shared' : 'isolated', options.platformTelemetry)
+      inject: [registryToken, RUNTIME_CONTAINER, BOOTSTRAP_PROVIDER_TOKENS],
+      useFactory: (registry, container, bootstrapProviderTokens) => new RuntimePlatformTelemetry(assertPrometheusRegistry(registry), assertRuntimeContainer(container), resolveRegistryMode(options, assertBootstrapProviderTokens(bootstrapProviderTokens)), options.platformTelemetry)
     }];
     const controllers = [];
     if (typeof metricsPath === 'string') {
@@ -78,13 +102,13 @@ export class MetricsModule {
           } = _applyDecs(this, [Inject(registryToken, platformTelemetryToken), Controller('')], [[Get(metricsRoutePath), 2, "getMetrics"]]));
         }
         constructor(registry, platformTelemetry) {
+          _initProto(this);
           this.registry = registry;
           this.platformTelemetry = platformTelemetry;
-          _initProto(this);
         }
         async getMetrics(_input, ctx) {
           ctx.response.setHeader('content-type', this.registry.contentType);
-          return this.platformTelemetry.collectMetrics(ctx, this.registry);
+          return this.platformTelemetry.collectMetrics(this.registry);
         }
         static {
           _initClass();
@@ -95,42 +119,74 @@ export class MetricsModule {
     class MetricsRuntimeModule {}
     defineModule(MetricsRuntimeModule, {
       controllers,
+      exports: [MetricsService, METER_PROVIDER],
+      imports,
       middleware,
       providers
     });
     return MetricsRuntimeModule;
   }
-  static createRegistry(options) {
-    const registry = options.registry ?? new PrometheusRegistry();
+  static createRegistry(options, configuredRegistry) {
+    const registry = configuredRegistry ?? options.registry ?? new PrometheusRegistry();
     if (options.defaultMetrics !== false && !MetricsModule.registeredRegistries.has(registry)) {
+      assertNoDefaultMetricCollisions(registry);
+      const existingMetricNames = new Set(registry.getMetricsAsArray().map(metric => metric.name));
+      try {
+        collectDefaultMetrics({
+          register: registry
+        });
+      } catch (error) {
+        for (const metric of registry.getMetricsAsArray()) {
+          if (!existingMetricNames.has(metric.name)) {
+            registry.removeSingleMetric(metric.name);
+          }
+        }
+        throw error;
+      }
       MetricsModule.registeredRegistries.add(registry);
-      collectDefaultMetrics({
-        register: registry
-      });
     }
     return registry;
   }
 }
 const PLATFORM_COMPONENT_LABELS = ['component_id', 'component_kind', 'operation', 'result', 'env', 'instance'];
 const REGISTRY_MODE_LABELS = ['mode'];
+const require = createRequire(import.meta.url);
+// prom-client exposes collector IDs publicly but not their metric names. This v15.1.3-only
+// private metadata seam keeps collision preflight side-effect-free; the exact package pin and
+// runtime-support regression must be updated together before changing prom-client.
+const DEFAULT_METRIC_COLLECTORS = collectDefaultMetrics.metricsList.map(collectorName => {
+  const collector = require(`prom-client/lib/metrics/${collectorName}`);
+  if (!hasDefaultMetricNames(collector)) {
+    throw new Error(`prom-client default collector "${collectorName}" does not expose metricNames.`);
+  }
+  return {
+    collectorName,
+    metricNames: collector.metricNames
+  };
+});
 const FRAMEWORK_PLATFORM_GAUGES = new WeakSet();
+const PLATFORM_TELEMETRY_REGISTRY_STATES = new WeakMap();
+const HTTP_INSTRUMENTATION_OWNERS = new WeakMap();
 const HEALTH_STATUSES = ['healthy', 'unhealthy', 'degraded'];
 const READINESS_STATUSES = ['ready', 'not-ready', 'degraded'];
-const PLATFORM_SHELL_TOKEN_NAME = 'PLATFORM_SHELL';
-const PLATFORM_SHELL_TOKEN_NAMES = new Set([PLATFORM_SHELL_TOKEN_NAME, String(PLATFORM_SHELL)]);
+const PLATFORM_SHELL_TOKEN_NAMES = new Set([String(PLATFORM_SHELL)]);
 function createHttpMetricsMiddleware(registryToken, httpOptions) {
   let _initClass2;
   let _MetricsHttpMiddlewar;
   class MetricsHttpMiddleware {
     static {
-      [_MetricsHttpMiddlewar, _initClass2] = _applyDecs(this, [Inject(registryToken)], []).c;
+      [_MetricsHttpMiddlewar, _initClass2] = _applyDecs(this, [Inject(registryToken, RUNTIME_CONTAINER)], []).c;
     }
     delegate;
-    constructor(registry) {
-      this.delegate = new HttpMetricsMiddleware(registry, httpOptions);
+    constructor(registry, container) {
+      const httpMetricsMiddleware = new HttpMetricsMiddleware(registry, httpOptions);
+      const runtimeContainer = assertRuntimeContainer(container);
+      if (claimsHttpInstrumentationOwnership(runtimeContainer, registry)) {
+        this.delegate = httpMetricsMiddleware;
+      }
     }
     handle(context, next) {
-      return this.delegate.handle(context, next);
+      return this.delegate ? this.delegate.handle(context, next) : next();
     }
     static {
       _initClass2();
@@ -138,12 +194,93 @@ function createHttpMetricsMiddleware(registryToken, httpOptions) {
   }
   return _MetricsHttpMiddlewar;
 }
+function claimsHttpInstrumentationOwnership(container, registry) {
+  let registryOwners = HTTP_INSTRUMENTATION_OWNERS.get(container);
+  if (!registryOwners) {
+    registryOwners = new WeakSet();
+    HTTP_INSTRUMENTATION_OWNERS.set(container, registryOwners);
+  }
+  if (registryOwners.has(registry)) {
+    return false;
+  }
+  registryOwners.add(registry);
+  return true;
+}
 function assertPrometheusRegistry(value) {
   if (!(value instanceof PrometheusRegistry)) {
     throw new Error('MetricsModule registry provider resolved an invalid Prometheus registry.');
   }
   return value;
 }
+function hasDefaultMetricNames(value) {
+  return typeof value === 'function' && 'metricNames' in value && Array.isArray(value.metricNames) && value.metricNames.every(metricName => typeof metricName === 'string');
+}
+function assertNoDefaultMetricCollisions(registry) {
+  for (const {
+    collectorName,
+    metricNames
+  } of DEFAULT_METRIC_COLLECTORS) {
+    if (!isDefaultCollectorActive(collectorName)) {
+      continue;
+    }
+    for (const metricName of metricNames) {
+      if (registry.getSingleMetric(metricName)) {
+        throw new Error(`A metric with the name ${metricName} has already been registered.`);
+      }
+    }
+  }
+}
+function isDefaultCollectorActive(collectorName) {
+  if (collectorName === 'processHandles') {
+    return typeof Reflect.get(process, '_getActiveHandles') === 'function';
+  }
+  if (collectorName === 'processRequests') {
+    return typeof Reflect.get(process, '_getActiveRequests') === 'function';
+  }
+  if (collectorName === 'processOpenFileDescriptors') {
+    return process.platform === 'linux';
+  }
+  if (collectorName === 'processMaxFileDescriptors') {
+    try {
+      return readFileSync('/proc/self/limits', 'utf8').split('\n').some(line => line.startsWith('Max open files'));
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function assertRuntimeContainer(value) {
+  if (!isRuntimeContainer(value)) {
+    throw new Error('MetricsModule runtime container provider resolved an invalid container.');
+  }
+  return value;
+}
+function assertBootstrapProviderTokens(value) {
+  if (!(value instanceof Set)) {
+    throw new Error('MetricsModule bootstrap provider token metadata resolved invalidly.');
+  }
+  return value;
+}
+function resolveRegistryMode(options, bootstrapProviderTokens) {
+  return options.registry || bootstrapProviderTokens.has(METRICS_REGISTRY) ? 'shared' : 'isolated';
+}
+function isRuntimeContainer(value) {
+  return typeof value === 'object' && value !== null && 'resolve' in value && typeof value.resolve === 'function';
+}
+function getRuntimePlatformTelemetryRegistryState(registry) {
+  const existing = PLATFORM_TELEMETRY_REGISTRY_STATES.get(registry);
+  if (existing) {
+    return existing;
+  }
+  const state = {
+    lastHealthStatuses: new Map(),
+    lastReadinessStatuses: new Map(),
+    registrations: [],
+    scrapeQueue: new SerializedScrapeQueue()
+  };
+  PLATFORM_TELEMETRY_REGISTRY_STATES.set(registry, state);
+  return state;
+}
 function toReadinessValue(status) {
   return status === 'ready' ? 1 : 0;
 }
@@ -175,16 +312,23 @@ function assertGaugeLabelSchema(gauge, config) {
     throw new Error(`Metric name "${config.name}" is already registered with labels [${registeredLabels}]. Built-in platform telemetry requires labels [${expectedLabels}].`);
   }
 }
+function removeFrameworkGauge(registry, gauge, metricName) {
+  if (!FRAMEWORK_PLATFORM_GAUGES.has(gauge) || registry.getSingleMetric(metricName) !== gauge) {
+    return;
+  }
+  registry.removeSingleMetric(metricName);
+}
 class RuntimePlatformTelemetry {
   readinessGauge;
   healthGauge;
   registryModeGauge;
-  lastHealthStatuses = new Map();
-  lastReadinessStatuses = new Map();
-  scrapeChain = Promise.resolve();
-  constructor(registry, registryMode, labels = {}) {
+  telemetryState;
+  constructor(registry, container, registryMode, labels = {}) {
+    this.registry = registry;
+    this.container = container;
     this.registryMode = registryMode;
     this.labels = labels;
+    this.telemetryState = getRuntimePlatformTelemetryRegistryState(registry);
     this.readinessGauge = getOrCreateGauge(registry, {
       help: 'Runtime platform component readiness from shared platform snapshot semantics.',
       labelNames: PLATFORM_COMPONENT_LABELS,
@@ -201,22 +345,67 @@ class RuntimePlatformTelemetry {
       name: 'fluo_metrics_registry_mode'
     });
     this.registryModeGauge.labels(this.registryMode).set(1);
+    this.installRegistryRefresh();
   }
-  async collectMetrics(ctx, registry) {
-    const collect = this.scrapeChain.then(async () => {
-      await this.refresh(ctx);
-      return registry.metrics();
+  collectMetrics(registry) {
+    return registry.metrics();
+  }
+  async onModuleDestroy() {
+    const registrationIndex = this.telemetryState.registrations.lastIndexOf(this);
+    if (registrationIndex >= 0) {
+      this.telemetryState.registrations.splice(registrationIndex, 1);
+    }
+    if (this.telemetryState.registrations.length > 0) {
+      return;
+    }
+    await this.telemetryState.scrapeQueue.drain(() => {
+      if (this.telemetryState.registrations.length > 0) {
+        return;
+      }
+      const originalMetrics = this.telemetryState.originalMetrics;
+      if (originalMetrics) {
+        this.clearPlatformTelemetry();
+        removeFrameworkGauge(this.registry, this.readinessGauge, 'fluo_component_ready');
+        removeFrameworkGauge(this.registry, this.healthGauge, 'fluo_component_health');
+        removeFrameworkGauge(this.registry, this.registryModeGauge, 'fluo_metrics_registry_mode');
+        this.registry.metrics = originalMetrics;
+        this.telemetryState.originalMetrics = undefined;
+      }
     });
-    this.scrapeChain = collect.then(() => undefined, () => undefined);
-    return collect;
   }
-  async refresh(ctx) {
-    const platformShell = await this.resolvePlatformShell(ctx);
+  installRegistryRefresh() {
+    this.telemetryState.registrations.push(this);
+    if (this.telemetryState.originalMetrics) {
+      return;
+    }
+    const registry = this.registry;
+    const telemetryState = this.telemetryState;
+    const originalMetrics = registry.metrics;
+    telemetryState.originalMetrics = originalMetrics;
+    registry.metrics = () => {
+      return telemetryState.scrapeQueue.enqueue(async () => {
+        const activeRegistration = telemetryState.registrations.at(-1);
+        if (!activeRegistration) {
+          return originalMetrics.call(registry);
+        }
+        return activeRegistration.collectScrape(() => originalMetrics.call(registry));
+      });
+    };
+  }
+  async collectScrape(render) {
+    await this.refresh();
+    return await render();
+  }
+  async refresh() {
+    const platformShell = await this.resolvePlatformShell();
     if (!platformShell) {
       this.clearPlatformTelemetry();
       return;
     }
     const snapshot = await platformShell.snapshot();
+    this.syncSnapshot(snapshot);
+  }
+  syncSnapshot(snapshot) {
     const env = this.labels?.env ?? 'unknown';
     const instance = this.labels?.instance ?? 'local';
     const components = [{
@@ -231,21 +420,17 @@ class RuntimePlatformTelemetry {
       readiness: component.readiness.status
     }))];
     this.syncGaugeStatuses({
-      currentStatuses: new Map(components.map(component => [this.toComponentKey(component.id, component.kind), component.health])),
-      env,
+      currentStatuses: this.toComponentStatusMap(components, env, instance, component => component.health),
       gauge: this.healthGauge,
-      instance,
-      lastStatuses: this.lastHealthStatuses,
+      lastStatuses: this.telemetryState.lastHealthStatuses,
       operation: 'health',
       statuses: HEALTH_STATUSES,
       toMetricValue: toHealthValue
     });
     this.syncGaugeStatuses({
-      currentStatuses: new Map(components.map(component => [this.toComponentKey(component.id, component.kind), component.readiness])),
-      env,
+      currentStatuses: this.toComponentStatusMap(components, env, instance, component => component.readiness),
       gauge: this.readinessGauge,
-      instance,
-      lastStatuses: this.lastReadinessStatuses,
+      lastStatuses: this.telemetryState.lastReadinessStatuses,
       operation: 'readiness',
       statuses: READINESS_STATUSES,
       toMetricValue: toReadinessValue
@@ -253,32 +438,30 @@ class RuntimePlatformTelemetry {
   }
   clearPlatformTelemetry() {
     this.clearGaugeStatuses({
-      env: this.labels?.env ?? 'unknown',
       gauge: this.healthGauge,
-      instance: this.labels?.instance ?? 'local',
-      lastStatuses: this.lastHealthStatuses,
+      lastStatuses: this.telemetryState.lastHealthStatuses,
       operation: 'health',
       statuses: HEALTH_STATUSES
     });
     this.clearGaugeStatuses({
-      env: this.labels?.env ?? 'unknown',
       gauge: this.readinessGauge,
-      instance: this.labels?.instance ?? 'local',
-      lastStatuses: this.lastReadinessStatuses,
+      lastStatuses: this.telemetryState.lastReadinessStatuses,
       operation: 'readiness',
       statuses: READINESS_STATUSES
     });
   }
   clearGaugeStatuses({
-    env,
     gauge,
-    instance,
     lastStatuses,
     operation,
     statuses
   }) {
-    for (const componentKey of lastStatuses.keys()) {
-      const [componentId, componentKind] = this.fromComponentKey(componentKey);
+    for (const {
+      componentId,
+      componentKind,
+      env,
+      instance
+    } of this.componentStatusEntries(lastStatuses)) {
       for (const status of statuses) {
         gauge.remove(componentId, componentKind, operation, status, env, instance);
       }
@@ -287,20 +470,23 @@ class RuntimePlatformTelemetry {
   }
   syncGaugeStatuses({
     currentStatuses,
-    env,
     gauge,
-    instance,
     lastStatuses,
     operation,
     statuses,
     toMetricValue
   }) {
-    for (const [componentKey, previousStatus] of lastStatuses) {
-      const nextStatus = currentStatuses.get(componentKey);
+    for (const {
+      componentId,
+      componentKind,
+      env,
+      instance,
+      status: previousStatus
+    } of this.componentStatusEntries(lastStatuses)) {
+      const nextStatus = this.getComponentStatus(currentStatuses, env, instance, componentId, componentKind);
       if (nextStatus === previousStatus) {
         continue;
       }
-      const [componentId, componentKind] = this.fromComponentKey(componentKey);
       for (const status of statuses) {
         if (status !== previousStatus) {
           continue;
@@ -308,41 +494,100 @@ class RuntimePlatformTelemetry {
         gauge.remove(componentId, componentKind, operation, status, env, instance);
       }
     }
-    for (const [componentKey, currentStatus] of currentStatuses) {
-      const [componentId, componentKind] = this.fromComponentKey(componentKey);
+    for (const {
+      componentId,
+      componentKind,
+      env,
+      instance,
+      status: currentStatus
+    } of this.componentStatusEntries(currentStatuses)) {
       gauge.labels(componentId, componentKind, operation, currentStatus, env, instance).set(toMetricValue(currentStatus));
     }
     lastStatuses.clear();
-    for (const [componentKey, currentStatus] of currentStatuses) {
-      lastStatuses.set(componentKey, currentStatus);
+    for (const {
+      componentId,
+      componentKind,
+      env,
+      instance,
+      status: currentStatus
+    } of this.componentStatusEntries(currentStatuses)) {
+      this.setComponentStatus(lastStatuses, env, instance, componentId, componentKind, currentStatus);
     }
   }
-  fromComponentKey(componentKey) {
-    const separatorIndex = componentKey.indexOf('::');
-    return [componentKey.slice(0, separatorIndex), componentKey.slice(separatorIndex + 2)];
+  toComponentStatusMap(components, env, instance, getStatus) {
+    const statuses = new Map();
+    for (const component of components) {
+      this.setComponentStatus(statuses, env, instance, component.id, component.kind, getStatus(component));
+    }
+    return statuses;
   }
-  toComponentKey(componentId, componentKind) {
-    return `${componentId}::${componentKind}`;
+  setComponentStatus(statuses, env, instance, componentId, componentKind, status) {
+    let statusByInstance = statuses.get(env);
+    if (!statusByInstance) {
+      statusByInstance = new Map();
+      statuses.set(env, statusByInstance);
+    }
+    let statusByComponent = statusByInstance.get(instance);
+    if (!statusByComponent) {
+      statusByComponent = new Map();
+      statusByInstance.set(instance, statusByComponent);
+    }
+    let statusByKind = statusByComponent.get(componentId);
+    if (!statusByKind) {
+      statusByKind = new Map();
+      statusByComponent.set(componentId, statusByKind);
+    }
+    statusByKind.set(componentKind, status);
+  }
+  getComponentStatus(statuses, env, instance, componentId, componentKind) {
+    return statuses.get(env)?.get(instance)?.get(componentId)?.get(componentKind);
+  }
+  *componentStatusEntries(statuses) {
+    for (const [env, statusByInstance] of statuses) {
+      for (const [instance, statusByComponent] of statusByInstance) {
+        for (const [componentId, statusByKind] of statusByComponent) {
+          for (const [componentKind, status] of statusByKind) {
+            yield {
+              componentId,
+              componentKind,
+              env,
+              instance,
+              status
+            };
+          }
+        }
+      }
+    }
   }
-  async resolvePlatformShell(ctx) {
+  async resolvePlatformShell() {
+    const hasPlatformShell = hasContainerToken(this.container, PLATFORM_SHELL);
+    if (hasPlatformShell === false) {
+      return undefined;
+    }
     try {
-      return await ctx.container.resolve(PLATFORM_SHELL);
+      return await this.container.resolve(PLATFORM_SHELL);
     } catch (error) {
-      if (isMissingPlatformShellResolutionError(error)) {
+      if (hasPlatformShell !== true && isMissingPlatformShellResolutionError(error)) {
         return undefined;
       }
       throw error;
     }
   }
 }
+function hasContainerToken(container, token) {
+  const has = container.has;
+  if (typeof has !== 'function') {
+    return undefined;
+  }
+  return has.call(container, token);
+}
 function isMissingPlatformShellResolutionError(error) {
   if (!(error instanceof ContainerResolutionError)) {
     return false;
   }
   const containerError = error;
   const token = typeof containerError.meta?.token === 'string' ? containerError.meta.token : undefined;
-  const hint = typeof containerError.meta?.hint === 'string' ? containerError.meta.hint : undefined;
-  return token !== undefined && PLATFORM_SHELL_TOKEN_NAMES.has(token) && hint === 'Ensure the provider is registered in a module\'s providers array, or that the module exporting it is imported by the consuming module.';
+  return token !== undefined && PLATFORM_SHELL_TOKEN_NAMES.has(token);
 }
 function resolveHttpOptions(http) {
   if (!http) {
@@ -356,6 +601,7 @@ function resolveHttpOptions(http) {
   }
   return {
     allowUnsafeRawPathLabelMode: http.allowUnsafeRawPathLabelMode,
+    durationHistogramBuckets: http.durationHistogramBuckets,
     pathLabelMode: http.pathLabelMode,
     pathLabelNormalizer: http.pathLabelNormalizer,
     unknownPathLabel: http.unknownPathLabel

package/dist/metrics-service.d.ts

@@ -1,6 +1,11 @@
 import type { Registry, CounterConfiguration, GaugeConfiguration, HistogramConfiguration } from 'prom-client';
 /**
- * Small facade for creating custom Prometheus metrics on the module registry.
+ * Small facade for creating custom Prometheus metrics on its `MetricsModule` registry.
+ *
+ * @remarks
+ * `MetricsService` is non-global: a module can inject it when it directly imports a
+ * `MetricsModule.forRoot(...)` registration or imports a module that re-exports
+ * `MetricsService`; unrelated sibling modules do not receive it automatically.
  */
 export declare class MetricsService {
     private readonly registry;

package/dist/metrics-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics-service.d.ts","sourceRoot":"","sources":["../src/metrics-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAIrB;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAE/C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAIlE;;;;;OAKG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAI9D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAItE;;;;OAIG;IACH,WAAW,IAAI,QAAQ;CAGxB"}
+{"version":3,"file":"metrics-service.d.ts","sourceRoot":"","sources":["../src/metrics-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAIrB;;;;;;;GAOG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAE/C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAIlE;;;;;OAKG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAI9D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAItE;;;;OAIG;IACH,WAAW,IAAI,QAAQ;CAGxB"}

package/dist/metrics-service.js

@@ -1,7 +1,12 @@
 import { createPrometheusCounter, createPrometheusGauge, createPrometheusHistogram } from './providers/prometheus-metrics-factory.js';
 
 /**
- * Small facade for creating custom Prometheus metrics on the module registry.
+ * Small facade for creating custom Prometheus metrics on its `MetricsModule` registry.
+ *
+ * @remarks
+ * `MetricsService` is non-global: a module can inject it when it directly imports a
+ * `MetricsModule.forRoot(...)` registration or imports a module that re-exports
+ * `MetricsService`; unrelated sibling modules do not receive it automatically.
  */
 export class MetricsService {
   constructor(registry) {

package/dist/serialized-scrape-queue.d.ts

@@ -0,0 +1,19 @@
+/** Observable state for package-internal serialized scrape scheduling. */
+export interface SerializedScrapeQueueState {
+    readonly isRunning: boolean;
+    readonly queued: number;
+}
+/**
+ * Serializes refresh-and-render scrape work while preserving individual results.
+ *
+ * Failed work does not poison later queue entries.
+ */
+export declare class SerializedScrapeQueue {
+    private isRunning;
+    private queued;
+    private tail;
+    get state(): SerializedScrapeQueueState;
+    enqueue<T>(task: () => Promise<T>): Promise<T>;
+    drain(finalizer: () => void): Promise<void>;
+}
+//# sourceMappingURL=serialized-scrape-queue.d.ts.map

package/dist/serialized-scrape-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialized-scrape-queue.d.ts","sourceRoot":"","sources":["../src/serialized-scrape-queue.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAoC;IAEhD,IAAI,KAAK,IAAI,0BAA0B,CAKtC;IAED,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqBxC,KAAK,CAAC,SAAS,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAalD"}