@fluojs/metrics 2.0.0 → 3.0.0

package/README.ko.md

@@ -22,7 +22,7 @@ pnpm add @fluojs/metrics
 
 ## 요구 사항
 
-`@fluojs/metrics`는 Node.js 20 이상에서 실행됩니다. package manifest는 `engines.node >=20.0.0`을 선언합니다.
+`@fluojs/metrics`는 패키지 자체의 지원 계약인 Node.js `>=24.0.0 <27`을 요구합니다.
 
 ## 사용 시점
 
@@ -44,14 +44,15 @@ class AppModule {}
 
 `MetricsModule.forRoot()`는 기본적으로 `GET /metrics`를 노출합니다. HTTP request instrumentation middleware를 설치하려면 `http: true` 또는 `http` option object를 전달하세요. HTTP 계측이 활성화되면 request total, error count, request duration을 기록합니다. 운영 환경에서는 scrape endpoint boundary를 명시적으로 다루세요. platform-level proxy가 준비될 때까지 `path: false`로 끄거나 dedicated endpoint middleware를 연결할 수 있습니다.
 
-Scrape endpoint는 active `prom-client` Registry output을 해당 Registry의 Prometheus content type으로 반환합니다. `MetricsModule.forRoot()`는 `registry` option을 전달하지 않는 한 application bootstrap마다 격리된 Registry를 생성합니다. 같은 dynamic module class를 다른 bootstrap에서 재사용해도 격리된 metric state는 새로 만들어집니다. framework metric과 application-defined metric이 하나의 scrape surface를 의도적으로 공유해야 할 때만 shared `Registry`를 전달하세요.
+Scrape endpoint는 active `prom-client` Registry output을 해당 Registry의 Prometheus content type으로 반환합니다. `MetricsModule.forRoot()`는 bootstrap이 `METRICS_REGISTRY`를 구성하거나 legacy `registry` option을 제공하지 않는 한 application bootstrap마다 격리된 Registry를 생성합니다. 같은 dynamic module class를 다른 bootstrap에서 재사용해도 격리된 metric state는 새로 만들어집니다. framework metric과 application-defined metric이 하나의 scrape surface를 의도적으로 공유해야 할 때만 bootstrap에서 shared `Registry`를 구성하세요.
 
 ## 공개 책임
 
 | 표면 | 책임 | 경계 |
 | --- | --- | --- |
 | `MetricsModule.forRoot(...)` | Prometheus scrape endpoint, default metrics, optional HTTP instrumentation, platform telemetry, registry ownership을 wiring합니다. | `provider`는 현재 `'prometheus'`만 받습니다. `path: false`는 scrape route와 route-scoped endpoint middleware를 비활성화합니다. |
-| `MetricsService` | Active Registry 위에서 custom `Counter`, `Gauge`, `Histogram`을 만드는 application-facing facade이며, 고급 Registry 공유를 위한 `getRegistry()`도 제공합니다. | 비즈니스/application metric은 collector helper를 사용하세요. `getRegistry()`는 active `prom-client` Registry를 `MetricsModule.forRoot({ registry })`로 직접 받을 수 없는 integration에 넘겨야 할 때만 사용하세요. |
+| `MetricsService` | Active Registry 위에서 custom `Counter`, `Gauge`, `Histogram`을 만드는 application-facing facade이며, 고급 Registry 공유를 위한 `getRegistry()`도 제공합니다. | `MetricsService`는 non-global service입니다. `MetricsModule.forRoot(...)` registration을 직접 import한 module 또는 `MetricsService`를 re-export하는 module을 import한 module에서 inject하세요. 관련 없는 sibling module에는 자동으로 제공되지 않습니다. 비즈니스/application metric은 collector helper를 사용하세요. `getRegistry()`는 active `prom-client` Registry를 bootstrap의 `METRICS_REGISTRY`로 직접 받을 수 없는 integration에 넘겨야 할 때만 사용하세요. |
+| `METRICS_REGISTRY` | Shared `prom-client` Registry를 위한 bootstrap provider token입니다. | `bootstrapApplication()` provider가 module의 legacy `registry` option보다 우선하여 ownership을 가집니다. |
 | `Registry` | Shared-registry setup을 위한 `prom-client` `Registry` constructor re-export입니다. | 같은 Prometheus Registry 구현체이므로 중복 metric name은 Prometheus semantics에 따라 계속 실패합니다. |
 | `METER_PROVIDER` / `PrometheusMeterProvider` / meter type | Provider token 또는 backend-neutral counter/gauge/histogram facade가 필요한 first-party package integration용 low-level meter bridge입니다. | Application code는 package-level integration을 직접 조합하는 경우가 아니면 보통 이 token이 필요하지 않습니다. 현재 bundled provider backend는 Prometheus뿐입니다. |
 | `middleware` | Framework HTTP metrics와 endpoint-scoped middleware 뒤의 module middleware chain에 참여하는 module-level middleware입니다. | Route-scoped가 아니므로 scrape route만 보호하려면 `endpointMiddleware`를 사용하세요. |
@@ -82,6 +83,21 @@ MetricsModule.forRoot({
 });
 ```
 
+### HTTP duration histogram bucket 구성
+
+```ts
+MetricsModule.forRoot({
+  http: {
+    durationHistogramBuckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
+  },
+});
+```
+
+`durationHistogramBuckets`는 내장 HTTP request duration histogram의
+`prom-client` 기본값을 대체합니다. 값의 단위는 초이며, alerting하려는
+latency 범위에 맞게 정해야 합니다. 각 경계는 유한하고 엄격히 증가해야 하며,
+잘못된 구성은 setup 중 거부됩니다.
+
 ### 메트릭 엔드포인트 보호 또는 비활성화
 
 ```ts
@@ -110,7 +126,7 @@ MetricsModule.forRoot({
 
 ### Custom metric은 한 번 생성하고 재사용하기
 
-`MetricsService.counter(...)`, `gauge(...)`, `histogram(...)`은 active Registry에 Prometheus collector를 생성합니다. 각 custom metric은 provider construction 또는 application startup 중 한 번만 만들고, business action이 발생할 때는 반환된 collector를 재사용하세요.
+`MetricsService.counter(...)`, `gauge(...)`, `histogram(...)`은 active Registry에 Prometheus collector를 생성합니다. `MetricsService`는 non-global service이므로, 이를 inject하는 provider 또는 controller는 `MetricsModule.forRoot(...)` registration을 직접 import하거나 `MetricsService`를 re-export하는 module을 import한 module에 속해야 합니다. 관련 없는 sibling module에는 자동으로 제공되지 않습니다. 각 custom metric은 provider construction 또는 application startup 중 한 번만 만들고, business action이 발생할 때는 반환된 collector를 재사용하세요.
 
 ```ts
 import { Inject } from '@fluojs/core';
@@ -135,30 +151,42 @@ class OrdersService {
 
 같은 이름으로 `MetricsService.counter(...)`를 다시 호출하면 collector를 다시 만들려고 하므로 Prometheus의 duplicate-name failure behavior를 따릅니다. 요청이나 command handler마다 새로 만들지 말고 collector를 저장해 재사용하세요.
 
-`MetricsService.getRegistry()`는 module scrape endpoint, 내장 HTTP collector, platform telemetry, service를 통해 만든 custom collector가 함께 사용하는 동일한 active `prom-client` Registry를 반환합니다. Bootstrap을 직접 소유한다면 `MetricsModule.forRoot({ registry })`에 명시적 `registry`를 전달하는 방식을 우선하세요. `getRegistry()`는 DI로 `MetricsService`를 받은 advanced integration이 이미 활성화된 Registry에 third-party Prometheus collector를 등록해야 할 때 사용합니다.
+`MetricsService.getRegistry()`는 module scrape endpoint, 내장 HTTP collector, platform telemetry, service를 통해 만든 custom collector가 함께 사용하는 동일한 active `prom-client` Registry를 반환합니다. Bootstrap을 직접 소유한다면 public `METRICS_REGISTRY` token으로 명시적 shared registry를 구성하세요. `getRegistry()`는 DI로 `MetricsService`를 받은 advanced integration이 이미 활성화된 Registry에 third-party Prometheus collector를 등록해야 할 때 사용합니다.
 
 ### Framework metric과 app metric이 하나의 registry를 공유하기
 
+애플리케이션이 `Counter`, `Registry` 같은 raw collector를 `prom-client`에서 직접
+import하기로 했다면 애플리케이션 의존성에 `prom-client`를 추가하세요.
+
+```bash
+pnpm add prom-client
+```
+
+`@fluojs/metrics`는 내부적으로 `prom-client`를 사용하지만, 그 의존성만으로 애플리케이션에서
+`prom-client`를 지원되는 transitive import로 사용할 수 있는 것은 아닙니다. 아래 setup은
+`@fluojs/metrics`가 re-export하는 `Registry`를 사용하므로 해당 direct dependency가 필요하지 않습니다.
+
 ```ts
 import { Module } from '@fluojs/core';
-import { Counter, Registry } from 'prom-client';
-import { MetricsModule } from '@fluojs/metrics';
+import { METRICS_REGISTRY, MetricsModule, Registry } from '@fluojs/metrics';
+import { bootstrapApplication } from '@fluojs/runtime';
 
 const registry = new Registry();
 
-new Counter({
-  name: 'orders_total',
-  help: 'Total orders processed',
-  registers: [registry],
-});
-
 @Module({
-  imports: [MetricsModule.forRoot({ http: true, registry })],
+  imports: [MetricsModule.forRoot({ http: true })],
 })
 class AppModule {}
+
+const app = await bootstrapApplication({
+  rootModule: AppModule,
+  providers: [{ provide: METRICS_REGISTRY, useValue: registry }],
+});
 ```
 
-여러 `MetricsModule` 인스턴스가 같은 Registry를 의도적으로 공유하는 경우, 내장 HTTP 메트릭은 framework ownership, label schema, effective path-label configuration이 모두 일치할 때만 기존 `http_requests_total`, `http_errors_total`, `http_request_duration_seconds` collector를 재사용합니다. Path-label compatibility 검사는 `pathLabelMode`, 정확히 같은 `pathLabelNormalizer` 함수 참조, `unknownPathLabel` fallback 의미론을 포함하므로 서로 다른 HTTP series policy를 하나의 collector set에 섞는 module instance는 빠르게 실패합니다. 내장 플랫폼 텔레메트리 Gauge도 같은 ownership 규칙을 따릅니다. 모듈이 만든 `fluo_component_ready`, `fluo_component_health`, `fluo_metrics_registry_mode` Gauge는 framework ownership과 label schema가 일치할 때만 재사용합니다. 플랫폼 텔레메트리 상태는 재사용된 Registry별로 추적되므로, 이후 스크레이프는 이전 module instance가 남긴 stale component readiness/health series를 제거한 뒤 메트릭을 반환합니다. Registry scrape wrapper는 최신 active module registration을 사용하며 마지막 registration이 종료되면 Registry의 원래 `metrics()` 함수를 복원합니다. 애플리케이션이 직접 등록한 중복 메트릭 이름은 Prometheus Registry 규칙대로 계속 빠르게 실패합니다.
+`Registry`는 `@fluojs/metrics`가 re-export하므로 이 setup에는 `prom-client` 직접 dependency가 필요하지 않습니다. application collector는 위의 `MetricsService` pattern으로 생성하세요.
+
+여러 `MetricsModule` 인스턴스가 같은 Registry를 의도적으로 공유하는 경우, 내장 HTTP 메트릭은 framework ownership, label schema, effective HTTP instrumentation configuration이 모두 일치할 때만 기존 `http_requests_total`, `http_errors_total`, `http_request_duration_seconds` collector를 재사용합니다. Compatibility 검사는 `pathLabelMode`, 정확히 같은 `pathLabelNormalizer` 함수 참조, `unknownPathLabel` fallback 의미론, 순서가 있는 `durationHistogramBuckets` 값을 포함하므로 서로 다른 HTTP series policy를 하나의 collector set에 섞는 module instance는 빠르게 실패합니다. 내장 플랫폼 텔레메트리 Gauge도 같은 ownership 규칙을 따릅니다. 모듈이 만든 `fluo_component_ready`, `fluo_component_health`, `fluo_metrics_registry_mode` Gauge는 framework ownership과 label schema가 일치할 때만 재사용합니다. 플랫폼 텔레메트리 상태는 재사용된 Registry별로 추적되므로, 이후 스크레이프는 이전 module instance가 남긴 stale component readiness/health series를 제거한 뒤 메트릭을 반환합니다. Registry scrape wrapper는 최신 active module registration을 사용하며 마지막 registration이 종료되면 Registry의 원래 `metrics()` 함수를 복원합니다. 애플리케이션이 직접 등록한 중복 메트릭 이름은 Prometheus Registry 규칙대로 계속 빠르게 실패합니다.
 
 ### 중복 메트릭 이름은 계속 빠르게 실패합니다
 
@@ -170,7 +198,7 @@ Prometheus 메트릭 이름은 하나의 Registry 안에서 고유해야 합니
 
 - `fluo_component_ready`: 준비 완료 시 1, 아닐 시 0.
 - `fluo_component_health`: 정상 상태 시 1, 아닐 시 0.
-- `fluo_metrics_registry_mode`: active registry mode를 `mode="isolated"` 또는 `mode="shared"` label과 gauge value `1`로 나타냅니다.
+- `fluo_metrics_registry_mode`: `MetricsModule.forRoot()`가 Registry를 생성하면 `mode="isolated"`, bootstrap이 `METRICS_REGISTRY`를 제공하거나 legacy `registry` option을 제공하면 `mode="shared"` label과 gauge value `1`을 노출합니다. 이 label은 bootstrap 또는 module registration 중 선택한 실효 Registry ownership configuration을 나타내며 scrape 시점에 Registry 공유 여부를 추론하지 않습니다.
 
 이 데이터는 built-in `/metrics` controller와 `MetricsService.getRegistry().metrics()`를 사용하는 advanced custom scraper를 포함해 active Registry가 스크레이프될 때마다 `PLATFORM_SHELL`을 쿼리하여 갱신됩니다. 초기화 시 환경 라벨을 제공할 수 있습니다.
 
@@ -204,23 +232,26 @@ MetricsModule.forRoot({
 ## 공개 API
 
 - `MetricsModule.forRoot(options)`
+- 의도적으로 공유하는 `Registry`를 위한 bootstrap 전용 token `METRICS_REGISTRY`
 - `MetricsService` 및 `counter(...)`, `gauge(...)`, `histogram(...)`, `getRegistry()`
 - `METER_PROVIDER` (Token)
 - `PrometheusMeterProvider`
 - Meter abstraction type: `MeterProvider`, `MeterCounter`, `MeterGauge`, `MeterHistogram`
 - `HttpMetricsMiddleware` 및 HTTP path-label 옵션 타입
 - `provider`(현재는 `'prometheus'`만 지원), module-level `middleware`, endpoint-scoped `endpointMiddleware`를 포함한 module option
-- `prom-client`의 `Registry`
+- `prom-client`에서 re-export한 `Registry`
 
 ### 운영 기본값
 
 - `path`의 기본값은 `'/metrics'`입니다. `''`를 포함한 모든 문자열 path는 scrape endpoint를 노출하며, `path: false`로만 scrape endpoint를 완전히 비활성화할 수 있습니다.
-- `registry`를 생략하면 application bootstrap마다 fresh isolated Registry, `MetricsService`, meter provider, telemetry collector set을 소유합니다.
+- bootstrap `METRICS_REGISTRY`와 legacy `registry` option을 모두 제공하지 않으면 application bootstrap마다 fresh isolated Registry, `MetricsService`, meter provider, telemetry collector set을 소유합니다.
+- Bootstrap `METRICS_REGISTRY` provider는 legacy `registry` option보다 우선하며, 같은 token을 가진 관련 없는 module provider는 metrics ownership을 구성하지 않습니다.
 - scrape response는 active Registry의 Prometheus content type과 Registry contents를 사용합니다.
 - `defaultMetrics`의 기본값은 `true`이며, `defaultMetrics: false`로 해당 Registry의 Prometheus 기본 프로세스/Node.js collector를 끌 수 있습니다.
 - `endpointMiddleware`는 class-based route-scoped middleware를 스크레이프 엔드포인트에만 바인딩합니다. HTTP 계측이 활성화된 경우 endpoint middleware 실패는 내장 HTTP collector에 집계됩니다.
 - HTTP 메트릭은 `http: true` 또는 `http` 옵션 객체를 전달한 경우에만 설치되며, 설치된 뒤에는 기본적으로 템플릿 기반 경로 라벨 정규화를 사용합니다.
-- 내장 HTTP collector는 같은 Registry를 공유하는 모듈 인스턴스 사이에서 framework-owned이고 예상 label schema 및 일치하는 path-label configuration을 가진 경우에만 재사용됩니다. 플랫폼 텔레메트리 Gauge는 framework-owned이고 예상 label schema를 가진 경우에만 재사용되며, 커스텀 애플리케이션 메트릭 이름 충돌은 Prometheus의 중복 이름 실패 동작을 유지합니다.
+- `http.durationHistogramBuckets`는 내장 HTTP request duration histogram bucket을 명시적인 초 단위 경계로 대체합니다.
+- 내장 HTTP collector는 같은 Registry를 공유하는 모듈 인스턴스 사이에서 framework-owned이고 예상 label schema 및 일치하는 HTTP instrumentation configuration을 가진 경우에만 재사용됩니다. 플랫폼 텔레메트리 Gauge는 framework-owned이고 예상 label schema를 가진 경우에만 재사용되며, 커스텀 애플리케이션 메트릭 이름 충돌은 Prometheus의 중복 이름 실패 동작을 유지합니다.
 - Shared Registry 텔레메트리 refresh는 소유 metrics module이 하나라도 active인 동안 유지되고 마지막 module이 종료되면 원래 `metrics()` 함수를 복원합니다.
 - raw path 라벨은 `allowUnsafeRawPathLabelMode: true`를 명시한 bounded internal route에서만 사용해야 합니다.
 - 플랫폼 텔레메트리는 `PLATFORM_SHELL`이 실제로 누락된 경우에만 생략되며, 그 외 resolve 실패는 스크레이프를 실패시킵니다.

package/README.md

@@ -22,7 +22,7 @@ pnpm add @fluojs/metrics
 
 ## Requirements
 
-`@fluojs/metrics` runs on Node.js 20 or newer; the package manifest declares `engines.node >=20.0.0`.
+`@fluojs/metrics` requires Node.js `>=24.0.0 <27` as its package-owned support contract.
 
 ## When to Use
 
@@ -44,14 +44,15 @@ class AppModule {}
 
 `MetricsModule.forRoot()` exposes `GET /metrics` by default. Pass `http: true` (or an `http` options object) when you want the module to install HTTP request instrumentation middleware. When HTTP instrumentation is enabled, the module records request totals, error counts, and request duration. For production deployments, make the scrape endpoint boundary explicit: either disable it with `path: false` until a platform-level proxy is in place, or attach dedicated endpoint middleware.
 
-The scrape endpoint returns the active `prom-client` registry output with that registry's Prometheus content type. `MetricsModule.forRoot()` creates an isolated registry for each application bootstrap unless you pass a `registry` option; reusing the same dynamic module class for another bootstrap receives fresh isolated metrics state. Pass a shared `Registry` only when framework metrics and application-defined metrics intentionally share one scrape surface.
+The scrape endpoint returns the active `prom-client` registry output with that registry's Prometheus content type. `MetricsModule.forRoot()` creates an isolated registry for each application bootstrap unless the bootstrap configures `METRICS_REGISTRY` or the legacy `registry` option is supplied; reusing the same dynamic module class for another bootstrap receives fresh isolated metrics state. Configure a shared `Registry` at bootstrap only when framework metrics and application-defined metrics intentionally share one scrape surface.
 
 ## Public Responsibilities
 
 | Surface | Responsibility | Boundary |
 | --- | --- | --- |
 | `MetricsModule.forRoot(...)` | Wires the Prometheus scrape endpoint, default metrics, optional HTTP instrumentation, platform telemetry, and registry ownership. | `provider` currently accepts only `'prometheus'`; `path: false` disables the scrape route and route-scoped endpoint middleware. |
-| `MetricsService` | Application-facing facade for custom `Counter`, `Gauge`, and `Histogram` metrics on the active registry, plus `getRegistry()` for deliberate advanced registry sharing. | Use collector helpers for business/application metrics. Use `getRegistry()` only when an integration must hand the active `prom-client` Registry to code that cannot receive `MetricsModule.forRoot({ registry })` directly. |
+| `MetricsService` | Application-facing facade for custom `Counter`, `Gauge`, and `Histogram` metrics on the active registry, plus `getRegistry()` for deliberate advanced registry sharing. | `MetricsService` is non-global: inject it from a module that directly imports a `MetricsModule.forRoot(...)` registration or imports a module that re-exports `MetricsService`; unrelated sibling modules do not receive it automatically. Use collector helpers for business/application metrics. Use `getRegistry()` only when an integration must hand the active `prom-client` Registry to code that cannot receive `METRICS_REGISTRY` at bootstrap. |
+| `METRICS_REGISTRY` | Bootstrap provider token for a shared `prom-client` Registry. | A provider supplied to `bootstrapApplication()` takes ownership over the module's legacy `registry` option. |
 | `Registry` | Re-export of `prom-client`'s `Registry` constructor for shared-registry setups. | It is the same Prometheus registry implementation; duplicate metric names still fail according to Prometheus semantics. |
 | `METER_PROVIDER` / `PrometheusMeterProvider` / meter types | Low-level meter bridge for first-party package integrations that need a provider token or backend-neutral counter/gauge/histogram facade. | Application code usually does not need this token unless it is composing package-level integrations; the only bundled provider backend today is Prometheus. |
 | `middleware` | Module-level middleware that participates in the module middleware chain after framework HTTP metrics and endpoint-scoped middleware. | It is not route-scoped; use `endpointMiddleware` when only the scrape route should be protected. |
@@ -82,6 +83,21 @@ MetricsModule.forRoot({
 });
 ```
 
+### Configure HTTP duration histogram buckets
+
+```ts
+MetricsModule.forRoot({
+  http: {
+    durationHistogramBuckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
+  },
+});
+```
+
+`durationHistogramBuckets` replaces the built-in HTTP request duration histogram's
+`prom-client` defaults. Values are measured in seconds and must fit the latency
+range you intend to alert on. Each boundary must be finite and strictly increasing;
+invalid configuration is rejected during setup.
+
 ### Protect or disable the metrics endpoint
 
 ```ts
@@ -110,7 +126,7 @@ MetricsModule.forRoot({
 
 ### Create custom metrics once and reuse them
 
-`MetricsService.counter(...)`, `gauge(...)`, and `histogram(...)` create Prometheus collectors on the active registry. Create each custom metric once during provider construction or application startup, then reuse the returned collector when business actions occur.
+`MetricsService.counter(...)`, `gauge(...)`, and `histogram(...)` create Prometheus collectors on the active registry. `MetricsService` is non-global: the provider or controller that injects it must belong to a module that directly imports a `MetricsModule.forRoot(...)` registration or imports a module that re-exports `MetricsService`; unrelated sibling modules do not receive it automatically. Create each custom metric once during provider construction or application startup, then reuse the returned collector when business actions occur.
 
 ```ts
 import { Inject } from '@fluojs/core';
@@ -135,30 +151,43 @@ class OrdersService {
 
 Calling `MetricsService.counter(...)` again with the same name recreates the collector and follows Prometheus' duplicate-name failure behavior. Store and reuse the collector instead of creating it inside each request or command handler.
 
-`MetricsService.getRegistry()` returns the same active `prom-client` Registry used by the module scrape endpoint, built-in HTTP collectors, platform telemetry, and custom collectors created through the service. Prefer passing an explicit `registry` to `MetricsModule.forRoot({ registry })` when you own the bootstrap. Use `getRegistry()` for advanced integrations that receive `MetricsService` through DI and need to register a third-party Prometheus collector on the already active registry.
+`MetricsService.getRegistry()` returns the same active `prom-client` Registry used by the module scrape endpoint, built-in HTTP collectors, platform telemetry, and custom collectors created through the service. When you own the bootstrap, configure an explicit shared registry with the public `METRICS_REGISTRY` token. Use `getRegistry()` for advanced integrations that receive `MetricsService` through DI and need to register a third-party Prometheus collector on the already active registry.
 
 ### Share one registry for framework and app metrics
 
+If your application chooses to import raw collectors such as `Counter` or
+`Registry` directly from `prom-client`, add it to your application's dependencies:
+
+```bash
+pnpm add prom-client
+```
+
+`@fluojs/metrics` uses `prom-client` internally, but its dependency does not make
+`prom-client` a supported transitive import for your application. The setup below
+uses the `Registry` re-export from `@fluojs/metrics`, so it does not require that
+direct dependency.
+
 ```ts
 import { Module } from '@fluojs/core';
-import { Counter, Registry } from 'prom-client';
-import { MetricsModule } from '@fluojs/metrics';
+import { METRICS_REGISTRY, MetricsModule, Registry } from '@fluojs/metrics';
+import { bootstrapApplication } from '@fluojs/runtime';
 
 const registry = new Registry();
 
-new Counter({
-  name: 'orders_total',
-  help: 'Total orders processed',
-  registers: [registry],
-});
-
 @Module({
-  imports: [MetricsModule.forRoot({ http: true, registry })],
+  imports: [MetricsModule.forRoot({ http: true })],
 })
 class AppModule {}
+
+const app = await bootstrapApplication({
+  rootModule: AppModule,
+  providers: [{ provide: METRICS_REGISTRY, useValue: registry }],
+});
 ```
 
-When multiple metrics module instances intentionally share the same registry, built-in HTTP metrics reuse the existing `http_requests_total`, `http_errors_total`, and `http_request_duration_seconds` collectors instead of registering duplicate framework metrics only when their framework ownership, label schema, and effective path-label configuration match. The path-label compatibility check includes `pathLabelMode`, the exact `pathLabelNormalizer` function reference, and `unknownPathLabel` fallback semantics, so incompatible module instances fail fast instead of mixing different HTTP series policies into one collector set. Built-in platform telemetry gauges follow the same ownership rule: module-created `fluo_component_ready`, `fluo_component_health`, and `fluo_metrics_registry_mode` gauges are reused only when their framework ownership and label schema match. Platform telemetry state is tracked per reused registry, so a later scrape replaces stale module-owned component readiness and health series from an earlier module instance before metrics are returned. The registry scrape wrapper keeps using the latest active module registration and restores the Registry's original `metrics()` function after the last registration closes. Application-defined duplicate names still fail fast.
+`Registry` is re-exported by `@fluojs/metrics`, so this setup needs no direct `prom-client` dependency. Create application collectors through the `MetricsService` pattern above.
+
+When multiple metrics module instances intentionally share the same registry, built-in HTTP metrics reuse the existing `http_requests_total`, `http_errors_total`, and `http_request_duration_seconds` collectors instead of registering duplicate framework metrics only when their framework ownership, label schema, and effective HTTP instrumentation configuration match. Compatibility includes `pathLabelMode`, the exact `pathLabelNormalizer` function reference, `unknownPathLabel` fallback semantics, and ordered `durationHistogramBuckets` values, so incompatible module instances fail fast instead of mixing different HTTP series policies into one collector set. Built-in platform telemetry gauges follow the same ownership rule: module-created `fluo_component_ready`, `fluo_component_health`, and `fluo_metrics_registry_mode` gauges are reused only when their framework ownership and label schema match. Platform telemetry state is tracked per reused registry, so a later scrape replaces stale module-owned component readiness and health series from an earlier module instance before metrics are returned. The registry scrape wrapper keeps using the latest active module registration and restores the Registry's original `metrics()` function after the last registration closes. Application-defined duplicate names still fail fast.
 
 ### Duplicate metric names still fail fast
 
@@ -170,7 +199,7 @@ The module emits fluo-specific gauges that mirror the platform shell and registe
 
 - `fluo_component_ready`: `1` when a component is ready, otherwise `0`.
 - `fluo_component_health`: `1` when a component is healthy, otherwise `0`.
-- `fluo_metrics_registry_mode`: gauge value `1` with a `mode="isolated"` or `mode="shared"` label for the active registry mode.
+- `fluo_metrics_registry_mode`: gauge value `1` with `mode="isolated"` when `MetricsModule.forRoot()` creates its registry, or `mode="shared"` when bootstrap supplies `METRICS_REGISTRY` or the legacy `registry` option is supplied. The label reports the effective registry ownership configuration selected during bootstrap or module registration; it does not infer registry sharing at scrape time.
 
 The platform snapshot is refreshed during each registry scrape, including advanced `MetricsService.getRegistry().metrics()` scrape paths, and you can attach environment labels up front.
 
@@ -204,23 +233,26 @@ MetricsModule.forRoot({
 ## Public API
 
 - `MetricsModule.forRoot(options)`
+- `METRICS_REGISTRY`, the bootstrap-only token for an intentionally shared `Registry`
 - `MetricsService`, including `counter(...)`, `gauge(...)`, `histogram(...)`, and `getRegistry()`
 - `METER_PROVIDER`
 - `PrometheusMeterProvider`
 - Meter abstraction types: `MeterProvider`, `MeterCounter`, `MeterGauge`, and `MeterHistogram`
 - `HttpMetricsMiddleware` and HTTP path-label option types
 - Module options including `provider` (currently only `'prometheus'`), module-level `middleware`, and endpoint-scoped `endpointMiddleware`
-- `Registry` from `prom-client`
+- `Registry`, re-exported from `prom-client`
 
 ### Operational defaults
 
 - `path` defaults to `'/metrics'`, any string path including `''` exposes a scrape endpoint, and `path: false` disables the scrape endpoint entirely.
-- When `registry` is omitted, each application bootstrap owns a fresh isolated registry, `MetricsService`, meter provider, and telemetry collector set.
+- When neither bootstrap `METRICS_REGISTRY` nor the legacy `registry` option is supplied, each application bootstrap owns a fresh isolated registry, `MetricsService`, meter provider, and telemetry collector set.
+- A bootstrap `METRICS_REGISTRY` provider takes precedence over the legacy `registry` option; an unrelated module provider with the same token does not configure metrics ownership.
 - The scrape response uses the active registry's Prometheus content type and registry contents.
 - `defaultMetrics` defaults to `true`, and `defaultMetrics: false` disables Prometheus default process and Node.js collectors for that registry.
 - `endpointMiddleware` binds class-based route-scoped middleware only to the scrape endpoint; with HTTP instrumentation enabled, endpoint middleware failures are counted by the built-in HTTP collectors.
 - HTTP metrics are installed only when `http: true` or an `http` options object is provided, and then default to template-normalized path labels.
-- Built-in HTTP collectors are reused when module instances share one registry only if they are framework-owned, have the expected label schema, and use matching path-label configuration; platform telemetry gauges are reused only if they are framework-owned and have the expected label schema; custom application metric name collisions keep Prometheus' duplicate-name failure behavior.
+- `http.durationHistogramBuckets` replaces the built-in HTTP request duration histogram buckets with explicit second-based boundaries.
+- Built-in HTTP collectors are reused when module instances share one registry only if they are framework-owned, have the expected label schema, and use matching HTTP instrumentation configuration; platform telemetry gauges are reused only if they are framework-owned and have the expected label schema; custom application metric name collisions keep Prometheus' duplicate-name failure behavior.
 - Shared Registry telemetry refresh remains installed while any owning metrics module is active and restores the original `metrics()` function after the last module closes.
 - Raw path labels require `allowUnsafeRawPathLabelMode: true` and should stay limited to bounded internal routes.
 - Platform telemetry is omitted only when `PLATFORM_SHELL` is genuinely missing; other resolution failures fail the scrape.

package/dist/http-metrics-middleware.d.ts

@@ -13,6 +13,8 @@ export interface HttpMetricsPathLabelContext {
 export type HttpMetricsPathLabelNormalizer = (context: HttpMetricsPathLabelContext) => string;
 /** Options that tune HTTP request metric label generation. */
 export interface HttpMetricsMiddlewareOptions {
+    /** Duration buckets in seconds for the built-in HTTP request histogram. */
+    durationHistogramBuckets?: readonly number[];
     pathLabelMode?: HttpMetricsPathLabelMode;
     pathLabelNormalizer?: HttpMetricsPathLabelNormalizer;
     unknownPathLabel?: string;
@@ -28,6 +30,16 @@ export declare class HttpMetricsMiddleware implements Middleware {
     private readonly pathLabelMode;
     private readonly pathLabelNormalizer?;
     private readonly unknownPathLabel;
+    /**
+     * Create the built-in HTTP request collectors in a Prometheus registry.
+     *
+     * @param registry Registry that owns or reuses the built-in HTTP collectors.
+     * @param options HTTP metric label and duration histogram configuration.
+     * @throws {Error} When raw path labels are configured without the explicit unsafe opt-in.
+     * @throws {Error} When duration histogram bucket boundaries are not finite and strictly increasing.
+     * @throws {Error} When an application-owned collector uses a built-in HTTP collector name.
+     * @throws {Error} When a reused framework collector has a different label schema or HTTP instrumentation configuration.
+     */
     constructor(registry: Registry, options?: HttpMetricsMiddlewareOptions);
     private resolvePathLabel;
     handle(context: MiddlewareContext, next: Next): Promise<void>;

package/dist/http-metrics-middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-metrics-middleware.d.ts","sourceRoot":"","sources":["../src/http-metrics-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAsB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AA4BhE,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,UAAU,CAAC;AAE1D,wDAAwD;AACxD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,EAAE,2BAA2B,KAAK,MAAM,CAAC;AAE9F,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAsBD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,UAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAiC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,4BAAiC;IAuB1E,OAAO,CAAC,gBAAgB;IAmBlB,MAAM,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnE,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,oBAAoB;CAsB7B"}
+{"version":3,"file":"http-metrics-middleware.d.ts","sourceRoot":"","sources":["../src/http-metrics-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAsB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AA6BhE,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,UAAU,CAAC;AAE1D,wDAAwD;AACxD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,EAAE,2BAA2B,KAAK,MAAM,CAAC;AAE9F,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B;IAC3C,2EAA2E;IAC3E,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAsBD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,UAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAiC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;;;;;;OASG;gBACS,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,4BAAiC;IAuB1E,OAAO,CAAC,gBAAgB;IAmBlB,MAAM,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnE,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,oBAAoB;CAsB7B"}

package/dist/http-metrics-middleware.js

@@ -38,6 +38,17 @@ export class HttpMetricsMiddleware {
   pathLabelMode;
   pathLabelNormalizer;
   unknownPathLabel;
+
+  /**
+   * Create the built-in HTTP request collectors in a Prometheus registry.
+   *
+   * @param registry Registry that owns or reuses the built-in HTTP collectors.
+   * @param options HTTP metric label and duration histogram configuration.
+   * @throws {Error} When raw path labels are configured without the explicit unsafe opt-in.
+   * @throws {Error} When duration histogram bucket boundaries are not finite and strictly increasing.
+   * @throws {Error} When an application-owned collector uses a built-in HTTP collector name.
+   * @throws {Error} When a reused framework collector has a different label schema or HTTP instrumentation configuration.
+   */
   constructor(registry, options = {}) {
     const collectorConfiguration = resolveHttpMetricsCollectorConfiguration(options);
     this.pathLabelMode = collectorConfiguration.pathLabelMode;
@@ -150,7 +161,10 @@ function getOrCreateHttpHistogram(registry, config, collectorConfiguration) {
   const histogram = createPrometheusHistogram(registry, {
     help: config.help,
     labelNames: [...config.labelNames],
-    name: config.name
+    name: config.name,
+    ...(collectorConfiguration.durationHistogramBuckets ? {
+      buckets: [...collectorConfiguration.durationHistogramBuckets]
+    } : {})
   });
   FRAMEWORK_HTTP_HISTOGRAMS.add(histogram);
   FRAMEWORK_HTTP_COLLECTOR_CONFIGURATION.set(histogram, collectorConfiguration);
@@ -167,7 +181,15 @@ function resolveHttpMetricsCollectorConfiguration(options) {
   if (options.pathLabelMode === 'raw' && options.allowUnsafeRawPathLabelMode !== true) {
     throw new Error('HttpMetricsMiddleware pathLabelMode "raw" is disabled by default. Pass allowUnsafeRawPathLabelMode: true only when you have bounded path cardinality.');
   }
+  let previousDurationHistogramBucket;
+  for (const durationHistogramBucket of options.durationHistogramBuckets ?? []) {
+    if (!Number.isFinite(durationHistogramBucket) || previousDurationHistogramBucket !== undefined && durationHistogramBucket <= previousDurationHistogramBucket) {
+      throw new Error('HttpMetricsMiddleware durationHistogramBuckets must contain finite, strictly increasing boundaries.');
+    }
+    previousDurationHistogramBucket = durationHistogramBucket;
+  }
   return {
+    durationHistogramBuckets: options.durationHistogramBuckets ? [...options.durationHistogramBuckets] : undefined,
     pathLabelMode: options.pathLabelMode ?? 'template',
     pathLabelNormalizer: options.pathLabelNormalizer,
     unknownPathLabel: options.unknownPathLabel ?? 'UNKNOWN'
@@ -176,18 +198,22 @@ function resolveHttpMetricsCollectorConfiguration(options) {
 function assertHttpMetricConfiguration(metric, metricName, expected) {
   const registered = FRAMEWORK_HTTP_COLLECTOR_CONFIGURATION.get(metric);
   if (!registered) {
-    throw new Error(`Metric name "${metricName}" is already registered as a framework-owned HTTP collector without path-label configuration metadata. Built-in HTTP metrics require matching path-label configuration before reuse.`);
+    throw new Error(`Metric name "${metricName}" is already registered as a framework-owned HTTP collector without HTTP instrumentation configuration metadata. Built-in HTTP metrics require matching HTTP collector configuration before reuse.`);
   }
   if (hasSameHttpMetricConfiguration(registered, expected)) {
     return;
   }
-  throw new Error(`Metric name "${metricName}" is already registered with framework HTTP path-label configuration ${describeHttpMetricConfiguration(registered)}. Built-in HTTP metrics require matching path-label configuration before reuse; received ${describeHttpMetricConfiguration(expected)}.`);
+  throw new Error(`Metric name "${metricName}" is already registered with framework HTTP collector configuration ${describeHttpMetricConfiguration(registered)}. Built-in HTTP metrics require matching HTTP collector configuration before reuse; received ${describeHttpMetricConfiguration(expected)}.`);
 }
 function hasSameHttpMetricConfiguration(left, right) {
-  return left.pathLabelMode === right.pathLabelMode && left.pathLabelNormalizer === right.pathLabelNormalizer && left.unknownPathLabel === right.unknownPathLabel;
+  return hasSameDurationHistogramBuckets(left.durationHistogramBuckets, right.durationHistogramBuckets) && left.pathLabelMode === right.pathLabelMode && left.pathLabelNormalizer === right.pathLabelNormalizer && left.unknownPathLabel === right.unknownPathLabel;
+}
+function hasSameDurationHistogramBuckets(left, right) {
+  return left === right || left !== undefined && right !== undefined && left.length === right.length && left.every((bucket, index) => bucket === right[index]);
 }
 function describeHttpMetricConfiguration(configuration) {
-  return `pathLabelMode="${configuration.pathLabelMode}", pathLabelNormalizer=${configuration.pathLabelNormalizer ? 'custom' : 'none'}, unknownPathLabel="${configuration.unknownPathLabel}"`;
+  const durationHistogramBuckets = configuration.durationHistogramBuckets ? `, durationHistogramBuckets=[${configuration.durationHistogramBuckets.join(',')}]` : '';
+  return `pathLabelMode="${configuration.pathLabelMode}", pathLabelNormalizer=${configuration.pathLabelNormalizer ? 'custom' : 'none'}, unknownPathLabel="${configuration.unknownPathLabel}"${durationHistogramBuckets}`;
 }
 function normalizePathToTemplate(path, params) {
   if (!path) {

package/dist/metrics-module.d.ts

@@ -1,9 +1,12 @@
+import { type Token } from '@fluojs/core';
 import { type Middleware, type MiddlewareLike } from '@fluojs/http';
 import { type ModuleType } from '@fluojs/runtime';
 import { type Registry } from 'prom-client';
 import { type HttpMetricsPathLabelMode, type HttpMetricsPathLabelNormalizer } from './http-metrics-middleware.js';
 /** HTTP-specific metric labeling options exposed by `MetricsModule.forRoot(...)`. */
 export interface MetricsHttpOptions {
+    /** Duration buckets in seconds for the built-in HTTP request histogram. */
+    durationHistogramBuckets?: readonly number[];
     /** How request paths are converted into Prometheus label values. Defaults to route templates. */
     pathLabelMode?: HttpMetricsPathLabelMode;
     /** Custom path-label normalizer for bounded application-specific label values. */
@@ -36,13 +39,14 @@ export interface MetricsModuleOptions {
         /** Instance label value. Defaults to `local`. */
         instance?: string;
     };
-    /** External Prometheus registry to share between built-in and custom metrics. */
+    /** Legacy shared-registry fallback. Prefer the `METRICS_REGISTRY` bootstrap provider. */
     registry?: Registry;
 }
+/** Bootstrap provider token for a Registry shared by metrics module instances. */
+export declare const METRICS_REGISTRY: Token<Registry>;
 /** Module entry point that exposes `/metrics` and optional HTTP/runtime telemetry. */
 export declare class MetricsModule {
     private static registeredRegistries;
-    private static httpInstrumentationRegistrations;
     /**
      * Register framework metrics, optional HTTP middleware, and a scrape endpoint.
      *
@@ -50,11 +54,10 @@ export declare 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?: MetricsModuleOptions): ModuleType;

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

@@ -1 +1 @@
-{"version":3,"file":"metrics-module.d.ts","sourceRoot":"","sources":["../src/metrics-module.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAuB,MAAM,cAAc,CAAC;AACrH,OAAO,EAEL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAgE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACpC,MAAM,8BAA8B,CAAC;AAKtC,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,iGAAiG;IACjG,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;IACpC,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,sHAAsH;IACtH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mGAAmG;IACnG,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC;IAC/D,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE;QAClB,iEAAiE;QACjE,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,iDAAiD;QACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,iFAAiF;IACjF,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,sFAAsF;AACtF,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAA2B;IAC9D,OAAO,CAAC,MAAM,CAAC,gCAAgC,CAA4D;IAE3G;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU;IA6H9D,OAAO,CAAC,MAAM,CAAC,cAAc;CAU9B"}
+{"version":3,"file":"metrics-module.d.ts","sourceRoot":"","sources":["../src/metrics-module.ts"],"names":[],"mappings":"AAGA,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAA8B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAuB,MAAM,cAAc,CAAC;AACrH,OAAO,EAEL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAgE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACpC,MAAM,8BAA8B,CAAC;AAMtC,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,iGAAiG;IACjG,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;IACpC,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,sHAAsH;IACtH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mGAAmG;IACnG,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC;IAC/D,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE;QAClB,iEAAiE;QACjE,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,iDAAiD;QACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,yFAAyF;IACzF,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,QAAQ,CAAuC,CAAC;AAErF,sFAAsF;AACtF,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAA2B;IAE9D;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU;IA+G9D,OAAO,CAAC,MAAM,CAAC,cAAc;CAyB9B"}

package/dist/metrics-module.js

@@ -3,16 +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 { RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+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(...)`. */
 
@@ -20,10 +23,12 @@ 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();
-  static httpInstrumentationRegistrations = new WeakMap();
 
   /**
    * Register framework metrics, optional HTTP middleware, and a scrape endpoint.
@@ -32,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 = {}) {
@@ -46,44 +50,33 @@ export class MetricsModule {
     }
     const httpOptions = resolveHttpOptions(options.http);
     const metricsPath = options.path === undefined ? '/metrics' : options.path;
-    let registryToken = Symbol('MetricsModule.registry');
+    const registryToken = Symbol('MetricsModule.registry');
     const platformTelemetryToken = Symbol('MetricsModule.platformTelemetry');
-    let httpMetricsMiddleware = httpOptions ? createHttpMetricsMiddleware(registryToken, httpOptions) : undefined;
+    const httpMetricsMiddleware = httpOptions ? createHttpMetricsMiddleware(registryToken, httpOptions) : undefined;
     const endpointMiddleware = typeof metricsPath === 'string' ? (options.endpointMiddleware ?? []).map(middlewareClass => forRoutes(middlewareClass, metricsPath)) : [];
     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 validationProviders = [];
-    let includeRuntimeRegistryProvider = httpMetricsMiddleware === undefined;
+    const includeRuntimeRegistryProvider = httpMetricsMiddleware === undefined;
     if (httpOptions && httpMetricsMiddleware) {
-      const existingRegistration = options.registry ? MetricsModule.httpInstrumentationRegistrations.get(options.registry) : undefined;
-      if (existingRegistration) {
-        registryToken = existingRegistration.registryToken;
-        httpMetricsMiddleware = undefined;
-        validationProviders.push(createHttpCollectorValidationProvider(registryToken, httpOptions));
-        imports.push(existingRegistration.moduleType);
-      } else {
-        includeRuntimeRegistryProvider = false;
-        class MetricsHttpInstrumentationModule {}
-        defineModule(MetricsHttpInstrumentationModule, {
-          exports: [registryToken],
-          global: true,
-          middleware: [httpMetricsMiddleware],
-          providers: [registryProvider, httpMetricsMiddleware]
-        });
-        if (options.registry) {
-          MetricsModule.httpInstrumentationRegistrations.set(options.registry, {
-            moduleType: MetricsHttpInstrumentationModule,
-            registryToken
-          });
-        }
-        imports.push(MetricsHttpInstrumentationModule);
-      }
+      class MetricsHttpInstrumentationModule {}
+      defineModule(MetricsHttpInstrumentationModule, {
+        exports: [registryToken],
+        global: true,
+        middleware: [httpMetricsMiddleware],
+        providers: [registryProvider, httpMetricsMiddleware]
+      });
+      imports.push(MetricsHttpInstrumentationModule);
     }
-    const providers = [...(includeRuntimeRegistryProvider ? [registryProvider] : []), ...validationProviders, {
+    const providers = [...(includeRuntimeRegistryProvider ? [registryProvider] : []), {
       provide: MetricsService,
       inject: [registryToken, platformTelemetryToken],
       useFactory: registry => new MetricsService(assertPrometheusRegistry(registry))
@@ -93,8 +86,8 @@ export class MetricsModule {
       useFactory: registry => new PrometheusMeterProvider(assertPrometheusRegistry(registry))
     }, {
       provide: platformTelemetryToken,
-      inject: [registryToken, RUNTIME_CONTAINER],
-      useFactory: (registry, container) => new RuntimePlatformTelemetry(assertPrometheusRegistry(registry), assertRuntimeContainer(container), 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') {
@@ -109,9 +102,9 @@ 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);
@@ -133,21 +126,47 @@ export class MetricsModule {
     });
     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_NAMES = new Set([String(PLATFORM_SHELL)]);
@@ -156,14 +175,18 @@ function createHttpMetricsMiddleware(registryToken, httpOptions) {
   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();
@@ -171,12 +194,17 @@ function createHttpMetricsMiddleware(registryToken, httpOptions) {
   }
   return _MetricsHttpMiddlewar;
 }
-function createHttpCollectorValidationProvider(registryToken, httpOptions) {
-  return {
-    provide: Symbol('MetricsModule.httpCollectorValidation'),
-    inject: [registryToken],
-    useFactory: registry => new HttpMetricsMiddleware(assertPrometheusRegistry(registry), httpOptions)
-  };
+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)) {
@@ -184,12 +212,58 @@ function assertPrometheusRegistry(value) {
   }
   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';
 }
@@ -202,7 +276,7 @@ function getRuntimePlatformTelemetryRegistryState(registry) {
     lastHealthStatuses: new Map(),
     lastReadinessStatuses: new Map(),
     registrations: [],
-    scrapeChain: Promise.resolve()
+    scrapeQueue: new SerializedScrapeQueue()
   };
   PLATFORM_TELEMETRY_REGISTRY_STATES.set(registry, state);
   return state;
@@ -238,6 +312,12 @@ 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;
@@ -270,7 +350,7 @@ class RuntimePlatformTelemetry {
   collectMetrics(registry) {
     return registry.metrics();
   }
-  onModuleDestroy() {
+  async onModuleDestroy() {
     const registrationIndex = this.telemetryState.registrations.lastIndexOf(this);
     if (registrationIndex >= 0) {
       this.telemetryState.registrations.splice(registrationIndex, 1);
@@ -278,11 +358,20 @@ class RuntimePlatformTelemetry {
     if (this.telemetryState.registrations.length > 0) {
       return;
     }
-    const originalMetrics = this.telemetryState.originalMetrics;
-    if (originalMetrics) {
-      this.registry.metrics = originalMetrics;
-      this.telemetryState.originalMetrics = undefined;
-    }
+    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;
+      }
+    });
   }
   installRegistryRefresh() {
     this.telemetryState.registrations.push(this);
@@ -293,24 +382,28 @@ class RuntimePlatformTelemetry {
     const telemetryState = this.telemetryState;
     const originalMetrics = registry.metrics;
     telemetryState.originalMetrics = originalMetrics;
-    registry.metrics = async () => {
-      const activeRegistration = telemetryState.registrations.at(-1);
-      await activeRegistration?.refresh();
-      return await originalMetrics.call(registry);
+    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 collect = this.telemetryState.scrapeChain.then(async () => {
-      const platformShell = await this.resolvePlatformShell();
-      if (!platformShell) {
-        this.clearPlatformTelemetry();
-        return;
-      }
-      const snapshot = await platformShell.snapshot();
-      this.syncSnapshot(snapshot);
-    });
-    this.telemetryState.scrapeChain = collect.then(() => undefined, () => undefined);
-    await collect;
+    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';
@@ -508,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"}

package/dist/serialized-scrape-queue.js

@@ -0,0 +1,43 @@
+/** Observable state for package-internal serialized scrape scheduling. */
+
+/**
+ * Serializes refresh-and-render scrape work while preserving individual results.
+ *
+ * Failed work does not poison later queue entries.
+ */
+export class SerializedScrapeQueue {
+  isRunning = false;
+  queued = 0;
+  tail = Promise.resolve();
+  get state() {
+    return {
+      isRunning: this.isRunning,
+      queued: this.queued
+    };
+  }
+  enqueue(task) {
+    this.queued += 1;
+    const scrape = this.tail.then(async () => {
+      this.queued -= 1;
+      this.isRunning = true;
+      try {
+        return await task();
+      } finally {
+        this.isRunning = false;
+      }
+    });
+    this.tail = scrape.then(() => undefined, () => undefined);
+    return scrape;
+  }
+  async drain(finalizer) {
+    for (;;) {
+      const observedTail = this.tail;
+      await observedTail;
+      if (this.tail !== observedTail) {
+        continue;
+      }
+      finalizer();
+      return;
+    }
+  }
+}

package/package.json

@@ -8,7 +8,7 @@
     "monitoring",
     "observability"
   ],
-  "version": "2.0.0",
+  "version": "3.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "directory": "packages/metrics"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -35,15 +35,16 @@
     "dist"
   ],
   "dependencies": {
-    "prom-client": "^15.1.3",
-    "@fluojs/core": "^1.1.0",
-    "@fluojs/di": "^2.0.0",
-    "@fluojs/http": "^2.0.1",
-    "@fluojs/runtime": "^2.0.1"
+    "prom-client": "15.1.3",
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/di": "^3.0.0",
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11",
+    "@fluojs/testing": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",