@fluojs/metrics 1.0.3 → 2.0.0

package/README.ko.md

@@ -20,6 +20,10 @@ HTTP metric과 platform telemetry를 포함해 fluo 애플리케이션을 위한
 pnpm add @fluojs/metrics
 ```
 
+## 요구 사항
+
+`@fluojs/metrics`는 Node.js 20 이상에서 실행됩니다. package manifest는 `engines.node >=20.0.0`을 선언합니다.
+
 ## 사용 시점
 
 - 애플리케이션이 Prometheus-compatible scraping을 위한 `/metrics` endpoint를 노출해야 할 때
@@ -40,17 +44,18 @@ 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을 전달하지 않는 한 격리된 Registry를 생성합니다. framework metric과 application-defined metric이 하나의 scrape surface를 의도적으로 공유해야 할 때만 shared `Registry`를 전달하세요.
+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`를 전달하세요.
 
 ## 공개 책임
 
 | 표면 | 책임 | 경계 |
 | --- | --- | --- |
 | `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입니다. | 비즈니스/application metric은 package internals 대신 이 서비스를 사용하세요. |
-| `METER_PROVIDER` / `PrometheusMeterProvider` | Provider token이 필요한 first-party package integration용 low-level meter bridge입니다. | Application code는 package-level integration을 직접 조합하는 경우가 아니면 보통 이 token이 필요하지 않습니다. |
+| `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에 넘겨야 할 때만 사용하세요. |
+| `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`를 사용하세요. |
-| `endpointMiddleware` | 설정된 scrape endpoint에만 바인딩되는 class-based `@fluojs/http` middleware constructor입니다. | `path: false`일 때는 무시됩니다. 함수나 global middleware declaration은 이 option의 계약 밖입니다. |
+| `endpointMiddleware` | 설정된 scrape endpoint에만 바인딩되는 class-based `@fluojs/http` middleware constructor입니다. | `path: false`일 때만 무시됩니다. `''`를 포함한 모든 문자열 `path`는 활성 endpoint path입니다. 함수나 global middleware declaration은 이 option의 계약 밖입니다. |
 
 ## 공통 패턴
 
@@ -103,9 +108,39 @@ MetricsModule.forRoot({
 
 `endpointMiddleware`는 class-based `@fluojs/http` middleware constructor를 받으며 metrics scrape endpoint에만 바인딩됩니다. middleware function이나 global middleware declaration은 이 option의 패키지 계약이 아닙니다. `middleware`는 module-level middleware로 남아 endpoint-scoped middleware 뒤의 module chain에서 실행되고, `endpointMiddleware`는 `path: false`로 scrape route를 비활성화하면 완전히 건너뜁니다. HTTP 계측이 활성화된 경우 endpoint middleware가 던진 실패도 내장 HTTP request/error collector에 기록됩니다.
 
+### Custom metric은 한 번 생성하고 재사용하기
+
+`MetricsService.counter(...)`, `gauge(...)`, `histogram(...)`은 active Registry에 Prometheus collector를 생성합니다. 각 custom metric은 provider construction 또는 application startup 중 한 번만 만들고, business action이 발생할 때는 반환된 collector를 재사용하세요.
+
+```ts
+import { Inject } from '@fluojs/core';
+import { MetricsService } from '@fluojs/metrics';
+
+@Inject(MetricsService)
+class OrdersService {
+  private readonly ordersCreated: ReturnType<MetricsService['counter']>;
+
+  constructor(metrics: MetricsService) {
+    this.ordersCreated = metrics.counter({
+      name: 'orders_created_total',
+      help: 'Total orders created',
+    });
+  }
+
+  recordOrderCreated(): void {
+    this.ordersCreated.inc();
+  }
+}
+```
+
+같은 이름으로 `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를 등록해야 할 때 사용합니다.
+
 ### Framework metric과 app metric이 하나의 registry를 공유하기
 
 ```ts
+import { Module } from '@fluojs/core';
 import { Counter, Registry } from 'prom-client';
 import { MetricsModule } from '@fluojs/metrics';
 
@@ -123,7 +158,7 @@ new Counter({
 class AppModule {}
 ```
 
-여러 `MetricsModule` 인스턴스가 같은 Registry를 의도적으로 공유하는 경우, 내장 HTTP 메트릭은 기존 `http_requests_total`, `http_errors_total`, `http_request_duration_seconds` collector를 재사용합니다. 내장 플랫폼 텔레메트리 Gauge도 같은 ownership 규칙을 따릅니다. 모듈이 만든 `fluo_component_ready`, `fluo_component_health`, `fluo_metrics_registry_mode` Gauge는 framework ownership과 label schema가 일치할 때만 재사용합니다. 애플리케이션이 직접 등록한 중복 메트릭 이름은 Prometheus 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 규칙대로 계속 빠르게 실패합니다.
 
 ### 중복 메트릭 이름은 계속 빠르게 실패합니다
 
@@ -135,9 +170,9 @@ Prometheus 메트릭 이름은 하나의 Registry 안에서 고유해야 합니
 
 - `fluo_component_ready`: 준비 완료 시 1, 아닐 시 0.
 - `fluo_component_health`: 정상 상태 시 1, 아닐 시 0.
-- `fluo_metrics_registry_mode`: active registry mode가 `isolated`인지 `shared`인지 나타냅니다.
+- `fluo_metrics_registry_mode`: active registry mode를 `mode="isolated"` 또는 `mode="shared"` label과 gauge value `1`로 나타냅니다.
 
-이 데이터는 매 스크레이프 시점에 `PLATFORM_SHELL`을 쿼리하여 갱신됩니다. 초기화 시 환경 라벨을 제공할 수 있습니다.
+이 데이터는 built-in `/metrics` controller와 `MetricsService.getRegistry().metrics()`를 사용하는 advanced custom scraper를 포함해 active Registry가 스크레이프될 때마다 `PLATFORM_SHELL`을 쿼리하여 갱신됩니다. 초기화 시 환경 라벨을 제공할 수 있습니다.
 
 ```ts
 MetricsModule.forRoot({
@@ -150,10 +185,10 @@ MetricsModule.forRoot({
 
 ### 런타임 플랫폼 텔레메트리 스크레이프 계약
 
-플랫폼 텔레메트리는 매 `/metrics` 스크레이프마다 `PLATFORM_SHELL`을 resolve하여 `fluo_component_ready`와 `fluo_component_health`를 갱신합니다.
+플랫폼 텔레메트리는 built-in `/metrics` controller 또는 `MetricsService.getRegistry()`를 사용하는 advanced custom scraper가 active Registry를 스크레이프할 때마다 `PLATFORM_SHELL`을 resolve하여 `fluo_component_ready`와 `fluo_component_health`를 갱신합니다.
 
 - `PLATFORM_SHELL` 등록 자체가 빠진 경우에는 스크레이프가 계속 성공하고 플랫폼 텔레메트리 시리즈만 생략됩니다.
-- 직전 성공 스크레이프에서 플랫폼 텔레메트리를 노출한 뒤 `PLATFORM_SHELL`을 사용할 수 없게 되면, stale `fluo_component_ready` 및 `fluo_component_health` 시리즈를 제거한 뒤 메트릭을 반환합니다.
+- 직전 성공 스크레이프에서 플랫폼 텔레메트리를 노출한 뒤 `PLATFORM_SHELL`을 사용할 수 없게 되거나 이후 module instance가 재사용된 Registry를 다른 플랫폼 snapshot으로 갱신하면, stale `fluo_component_ready` 및 `fluo_component_health` 시리즈를 제거한 뒤 메트릭을 반환합니다.
 - 그 외의 `PLATFORM_SHELL` resolve 실패는 조용히 삼키지 않고 스크레이프 실패로 그대로 드러납니다.
 
 ### 기본 프로세스/Node 메트릭 비활성화
@@ -169,24 +204,27 @@ MetricsModule.forRoot({
 ## 공개 API
 
 - `MetricsModule.forRoot(options)`
-- `MetricsService`
+- `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`
 
 ### 운영 기본값
 
-- `path`의 기본값은 `'/metrics'`이며, `path: false`로 스크레이프 엔드포인트를 완전히 비활성화할 수 있습니다.
+- `path`의 기본값은 `'/metrics'`입니다. `''`를 포함한 모든 문자열 path는 scrape endpoint를 노출하며, `path: false`로만 scrape endpoint를 완전히 비활성화할 수 있습니다.
+- `registry`를 생략하면 application bootstrap마다 fresh isolated Registry, `MetricsService`, meter provider, telemetry collector set을 소유합니다.
 - 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와 플랫폼 텔레메트리 Gauge는 같은 Registry를 공유하는 모듈 인스턴스 사이에서 framework-owned이고 예상 label schema를 가진 경우에만 재사용되며, 커스텀 애플리케이션 메트릭 이름 충돌은 Prometheus의 중복 이름 실패 동작을 유지합니다.
+- 내장 HTTP collector는 같은 Registry를 공유하는 모듈 인스턴스 사이에서 framework-owned이고 예상 label schema 및 일치하는 path-label 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 실패는 스크레이프를 실패시킵니다.
-- 직전 성공 스크레이프에서 노출된 플랫폼 텔레메트리 시리즈는 `PLATFORM_SHELL`을 사용할 수 없게 된 스크레이프에서 제거됩니다.
+- 직전 성공 스크레이프에서 노출된 플랫폼 텔레메트리 시리즈는 `PLATFORM_SHELL`을 사용할 수 없게 된 스크레이프 또는 이후 module instance가 재사용된 Registry를 다른 플랫폼 snapshot으로 갱신한 스크레이프에서 제거됩니다.
 
 ## 관련 패키지
 

package/README.md

@@ -20,6 +20,10 @@ Prometheus metrics exposure for fluo applications, including framework-aware HTT
 pnpm add @fluojs/metrics
 ```
 
+## Requirements
+
+`@fluojs/metrics` runs on Node.js 20 or newer; the package manifest declares `engines.node >=20.0.0`.
+
 ## When to Use
 
 - when your app should expose a `/metrics` endpoint for Prometheus-compatible scraping
@@ -40,17 +44,18 @@ 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 unless you pass a `registry` option; 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 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.
 
 ## 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. | Use this for business/application metrics instead of reaching into package internals. |
-| `METER_PROVIDER` / `PrometheusMeterProvider` | Low-level meter bridge for first-party package integrations that need a provider token. | Application code usually does not need this token unless it is composing package-level integrations. |
+| `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. |
+| `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. |
-| `endpointMiddleware` | Class-based `@fluojs/http` middleware constructors bound only to the configured scrape endpoint. | Ignored when `path: false`; functions or global middleware declarations are outside this option's contract. |
+| `endpointMiddleware` | Class-based `@fluojs/http` middleware constructors bound only to the configured scrape endpoint. | Ignored only when `path: false`; any string `path`, including `''`, remains an active endpoint path. Functions or global middleware declarations are outside this option's contract. |
 
 ## Common Patterns
 
@@ -103,9 +108,39 @@ MetricsModule.forRoot({
 
 `endpointMiddleware` accepts class-based `@fluojs/http` middleware constructors and binds them only to the metrics scrape endpoint. Middleware functions or global middleware declarations are not the package contract for this option. `middleware` remains module-level middleware and runs as part of the module chain after endpoint-scoped middleware, while `endpointMiddleware` is skipped entirely when `path: false` disables the scrape route. When HTTP instrumentation is enabled, failures thrown by endpoint middleware are recorded in the built-in HTTP request and error collectors.
 
+### 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.
+
+```ts
+import { Inject } from '@fluojs/core';
+import { MetricsService } from '@fluojs/metrics';
+
+@Inject(MetricsService)
+class OrdersService {
+  private readonly ordersCreated: ReturnType<MetricsService['counter']>;
+
+  constructor(metrics: MetricsService) {
+    this.ordersCreated = metrics.counter({
+      name: 'orders_created_total',
+      help: 'Total orders created',
+    });
+  }
+
+  recordOrderCreated(): void {
+    this.ordersCreated.inc();
+  }
+}
+```
+
+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.
+
 ### Share one registry for framework and app metrics
 
 ```ts
+import { Module } from '@fluojs/core';
 import { Counter, Registry } from 'prom-client';
 import { MetricsModule } from '@fluojs/metrics';
 
@@ -123,7 +158,7 @@ new Counter({
 class AppModule {}
 ```
 
-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. 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. Application-defined duplicate names still fail fast.
+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.
 
 ### Duplicate metric names still fail fast
 
@@ -135,9 +170,9 @@ 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`: `isolated` or `shared` for the active registry mode.
+- `fluo_metrics_registry_mode`: gauge value `1` with a `mode="isolated"` or `mode="shared"` label for the active registry mode.
 
-The platform snapshot is refreshed during each scrape, and you can attach environment labels up front.
+The platform snapshot is refreshed during each registry scrape, including advanced `MetricsService.getRegistry().metrics()` scrape paths, and you can attach environment labels up front.
 
 ```ts
 MetricsModule.forRoot({
@@ -150,7 +185,7 @@ MetricsModule.forRoot({
 
 ### Runtime platform telemetry scrape contract
 
-Platform telemetry refreshes `fluo_component_ready` and `fluo_component_health` on each `/metrics` scrape by resolving `PLATFORM_SHELL`.
+Platform telemetry refreshes `fluo_component_ready` and `fluo_component_health` on each active registry scrape by resolving `PLATFORM_SHELL`, whether the scrape flows through the built-in `/metrics` controller or an advanced custom scraper using `MetricsService.getRegistry()`.
 
 - If `PLATFORM_SHELL` is not registered, the scrape still succeeds and omits the platform telemetry series.
 - If `PLATFORM_SHELL` becomes unavailable after the last successful scrape, stale `fluo_component_ready` and `fluo_component_health` series are removed before metrics are returned.
@@ -169,24 +204,27 @@ MetricsModule.forRoot({
 ## Public API
 
 - `MetricsModule.forRoot(options)`
-- `MetricsService`
+- `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`
 
 ### Operational defaults
 
-- `path` defaults to `'/metrics'`, and `path: false` disables the scrape endpoint entirely.
+- `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.
 - 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 and platform telemetry gauges are reused when module instances share one registry only if they are framework-owned and have the expected label schema; custom application metric name collisions keep Prometheus' duplicate-name failure behavior.
+- 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.
+- 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.
-- Stale platform telemetry series are removed when `PLATFORM_SHELL` becomes unavailable after the last successful scrape.
+- Stale platform telemetry series are removed when `PLATFORM_SHELL` becomes unavailable after the last successful scrape or when a later module instance refreshes a reused registry with a different platform snapshot.
 
 ## Related Packages
 

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;AAqBhE,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;IA2B1E,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;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"}

package/dist/http-metrics-middleware.js

@@ -2,6 +2,7 @@ import { Counter, Histogram } from 'prom-client';
 import { createPrometheusCounter, createPrometheusHistogram } from './providers/prometheus-metrics-factory.js';
 const FRAMEWORK_HTTP_COUNTERS = new WeakSet();
 const FRAMEWORK_HTTP_HISTOGRAMS = new WeakSet();
+const FRAMEWORK_HTTP_COLLECTOR_CONFIGURATION = new WeakMap();
 
 /** Strategy used to label request paths in emitted HTTP metrics. */
 
@@ -38,27 +39,25 @@ export class HttpMetricsMiddleware {
   pathLabelNormalizer;
   unknownPathLabel;
   constructor(registry, 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.');
-    }
-    this.pathLabelMode = options.pathLabelMode ?? 'template';
-    this.pathLabelNormalizer = options.pathLabelNormalizer;
-    this.unknownPathLabel = options.unknownPathLabel ?? 'UNKNOWN';
+    const collectorConfiguration = resolveHttpMetricsCollectorConfiguration(options);
+    this.pathLabelMode = collectorConfiguration.pathLabelMode;
+    this.pathLabelNormalizer = collectorConfiguration.pathLabelNormalizer;
+    this.unknownPathLabel = collectorConfiguration.unknownPathLabel;
     this.requestsTotal = getOrCreateHttpCounter(registry, {
       help: 'Total number of HTTP requests',
       labelNames: ['method', 'path', 'status'],
       name: 'http_requests_total'
-    });
+    }, collectorConfiguration);
     this.errorsTotal = getOrCreateHttpCounter(registry, {
       help: 'Total number of HTTP error responses (4xx/5xx)',
       labelNames: ['method', 'path', 'status'],
       name: 'http_errors_total'
-    });
+    }, collectorConfiguration);
     this.requestDuration = getOrCreateHttpHistogram(registry, {
       help: 'HTTP request duration in seconds',
       labelNames: ['method', 'path', 'status'],
       name: 'http_request_duration_seconds'
-    });
+    }, collectorConfiguration);
   }
   resolvePathLabel(request) {
     if (this.pathLabelNormalizer) {
@@ -119,13 +118,14 @@ export class HttpMetricsMiddleware {
     }
   }
 }
-function getOrCreateHttpCounter(registry, config) {
+function getOrCreateHttpCounter(registry, config, collectorConfiguration) {
   const existing = registry.getSingleMetric(config.name);
   if (existing instanceof Counter) {
     if (!FRAMEWORK_HTTP_COUNTERS.has(existing)) {
       throw new Error(`Metric name "${config.name}" is already registered by the application. Built-in HTTP metrics require framework-owned collectors.`);
     }
     assertHttpMetricLabelSchema(existing, config);
+    assertHttpMetricConfiguration(existing, config.name, collectorConfiguration);
     return existing;
   }
   const counter = createPrometheusCounter(registry, {
@@ -134,15 +134,17 @@ function getOrCreateHttpCounter(registry, config) {
     name: config.name
   });
   FRAMEWORK_HTTP_COUNTERS.add(counter);
+  FRAMEWORK_HTTP_COLLECTOR_CONFIGURATION.set(counter, collectorConfiguration);
   return counter;
 }
-function getOrCreateHttpHistogram(registry, config) {
+function getOrCreateHttpHistogram(registry, config, collectorConfiguration) {
   const existing = registry.getSingleMetric(config.name);
   if (existing instanceof Histogram) {
     if (!FRAMEWORK_HTTP_HISTOGRAMS.has(existing)) {
       throw new Error(`Metric name "${config.name}" is already registered by the application. Built-in HTTP metrics require framework-owned collectors.`);
     }
     assertHttpMetricLabelSchema(existing, config);
+    assertHttpMetricConfiguration(existing, config.name, collectorConfiguration);
     return existing;
   }
   const histogram = createPrometheusHistogram(registry, {
@@ -151,6 +153,7 @@ function getOrCreateHttpHistogram(registry, config) {
     name: config.name
   });
   FRAMEWORK_HTTP_HISTOGRAMS.add(histogram);
+  FRAMEWORK_HTTP_COLLECTOR_CONFIGURATION.set(histogram, collectorConfiguration);
   return histogram;
 }
 function assertHttpMetricLabelSchema(metric, config) {
@@ -160,6 +163,32 @@ function assertHttpMetricLabelSchema(metric, config) {
     throw new Error(`Metric name "${config.name}" is already registered with labels [${registeredLabels}]. Built-in HTTP metrics require labels [${expectedLabels}].`);
   }
 }
+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.');
+  }
+  return {
+    pathLabelMode: options.pathLabelMode ?? 'template',
+    pathLabelNormalizer: options.pathLabelNormalizer,
+    unknownPathLabel: options.unknownPathLabel ?? 'UNKNOWN'
+  };
+}
+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.`);
+  }
+  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)}.`);
+}
+function hasSameHttpMetricConfiguration(left, right) {
+  return left.pathLabelMode === right.pathLabelMode && left.pathLabelNormalizer === right.pathLabelNormalizer && left.unknownPathLabel === right.unknownPathLabel;
+}
+function describeHttpMetricConfiguration(configuration) {
+  return `pathLabelMode="${configuration.pathLabelMode}", pathLabelNormalizer=${configuration.pathLabelNormalizer ? 'custom' : 'none'}, unknownPathLabel="${configuration.unknownPathLabel}"`;
+}
 function normalizePathToTemplate(path, params) {
   if (!path) {
     return '/';

package/dist/metrics-module.d.ts

@@ -42,6 +42,7 @@ export interface MetricsModuleOptions {
 /** 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.
      *
@@ -57,5 +58,6 @@ export declare class MetricsModule {
      * @returns A runtime module that exposes metrics through the configured path.
      */
     static forRoot(options?: MetricsModuleOptions): ModuleType;
+    private static createRegistry;
 }
 //# sourceMappingURL=metrics-module.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"metrics-module.d.ts","sourceRoot":"","sources":["../src/metrics-module.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAuB,MAAM,cAAc,CAAC;AACrH,OAAO,EAAgB,KAAK,UAAU,EAA8C,MAAM,iBAAiB,CAAC;AAC5G,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;IAE9D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU;CAqE/D"}
+{"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"}

package/dist/metrics-module.js

@@ -3,9 +3,11 @@ 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 { Inject } from '@fluojs/core';
 import { ContainerResolutionError } from '@fluojs/di';
 import { Controller, Get, forRoutes } from '@fluojs/http';
 import { defineModule, PLATFORM_SHELL } from '@fluojs/runtime';
+import { 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';
@@ -21,6 +23,7 @@ import { PrometheusMeterProvider } from './providers/prometheus-meter-provider.j
 /** 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.
@@ -43,24 +46,55 @@ export class MetricsModule {
     }
     const httpOptions = resolveHttpOptions(options.http);
     const metricsPath = options.path === undefined ? '/metrics' : options.path;
-    const registry = options.registry ?? new PrometheusRegistry();
-    const metricsService = new MetricsService(registry);
-    const meterProvider = new PrometheusMeterProvider(registry);
-    const platformTelemetry = new RuntimePlatformTelemetry(registry, options.registry ? 'shared' : 'isolated', options.platformTelemetry);
-    if (options.defaultMetrics !== false && !MetricsModule.registeredRegistries.has(registry)) {
-      MetricsModule.registeredRegistries.add(registry);
-      collectDefaultMetrics({
-        register: registry
-      });
+    let registryToken = Symbol('MetricsModule.registry');
+    const platformTelemetryToken = Symbol('MetricsModule.platformTelemetry');
+    let 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)
+    };
+    const imports = [];
+    const validationProviders = [];
+    let 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);
+      }
     }
-    const endpointMiddleware = metricsPath ? (options.endpointMiddleware ?? []).map(middlewareClass => forRoutes(middlewareClass, metricsPath)) : [];
-    const middleware = [...(httpOptions ? [new HttpMetricsMiddleware(registry, httpOptions)] : []), ...endpointMiddleware, ...(options.middleware ?? [])];
-    const providers = [{
+    const providers = [...(includeRuntimeRegistryProvider ? [registryProvider] : []), ...validationProviders, {
       provide: MetricsService,
-      useValue: metricsService
+      inject: [registryToken, platformTelemetryToken],
+      useFactory: registry => new MetricsService(assertPrometheusRegistry(registry))
     }, {
       provide: METER_PROVIDER,
-      useValue: meterProvider
+      inject: [registryToken],
+      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)
     }];
     const controllers = [];
     if (typeof metricsPath === 'string') {
@@ -72,14 +106,16 @@ export class MetricsModule {
           ({
             e: [_initProto],
             c: [_MetricsController, _initClass]
-          } = _applyDecs(this, [Controller('')], [[Get(metricsRoutePath), 2, "getMetrics"]]));
+          } = _applyDecs(this, [Inject(registryToken, platformTelemetryToken), Controller('')], [[Get(metricsRoutePath), 2, "getMetrics"]]));
         }
-        constructor() {
+        constructor(registry, platformTelemetry) {
+          this.registry = registry;
+          this.platformTelemetry = platformTelemetry;
           _initProto(this);
         }
         async getMetrics(_input, ctx) {
-          ctx.response.setHeader('content-type', registry.contentType);
-          return platformTelemetry.collectMetrics(ctx, registry);
+          ctx.response.setHeader('content-type', this.registry.contentType);
+          return this.platformTelemetry.collectMetrics(this.registry);
         }
         static {
           _initClass();
@@ -90,19 +126,87 @@ 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();
+    if (options.defaultMetrics !== false && !MetricsModule.registeredRegistries.has(registry)) {
+      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 FRAMEWORK_PLATFORM_GAUGES = new WeakSet();
+const PLATFORM_TELEMETRY_REGISTRY_STATES = 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;
+    }
+    delegate;
+    constructor(registry) {
+      this.delegate = new HttpMetricsMiddleware(registry, httpOptions);
+    }
+    handle(context, next) {
+      return this.delegate.handle(context, next);
+    }
+    static {
+      _initClass2();
+    }
+  }
+  return _MetricsHttpMiddlewar;
+}
+function createHttpCollectorValidationProvider(registryToken, httpOptions) {
+  return {
+    provide: Symbol('MetricsModule.httpCollectorValidation'),
+    inject: [registryToken],
+    useFactory: registry => new HttpMetricsMiddleware(assertPrometheusRegistry(registry), httpOptions)
+  };
+}
+function assertPrometheusRegistry(value) {
+  if (!(value instanceof PrometheusRegistry)) {
+    throw new Error('MetricsModule registry provider resolved an invalid Prometheus registry.');
+  }
+  return value;
+}
+function assertRuntimeContainer(value) {
+  if (!isRuntimeContainer(value)) {
+    throw new Error('MetricsModule runtime container provider resolved an invalid container.');
+  }
+  return value;
+}
+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: [],
+    scrapeChain: Promise.resolve()
+  };
+  PLATFORM_TELEMETRY_REGISTRY_STATES.set(registry, state);
+  return state;
+}
 function toReadinessValue(status) {
   return status === 'ready' ? 1 : 0;
 }
@@ -138,12 +242,13 @@ 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,
@@ -160,22 +265,54 @@ 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();
-    });
-    this.scrapeChain = collect.then(() => undefined, () => undefined);
-    return collect;
+  collectMetrics(registry) {
+    return registry.metrics();
   }
-  async refresh(ctx) {
-    const platformShell = await this.resolvePlatformShell(ctx);
-    if (!platformShell) {
-      this.clearPlatformTelemetry();
+  onModuleDestroy() {
+    const registrationIndex = this.telemetryState.registrations.lastIndexOf(this);
+    if (registrationIndex >= 0) {
+      this.telemetryState.registrations.splice(registrationIndex, 1);
+    }
+    if (this.telemetryState.registrations.length > 0) {
       return;
     }
-    const snapshot = await platformShell.snapshot();
+    const originalMetrics = this.telemetryState.originalMetrics;
+    if (originalMetrics) {
+      this.registry.metrics = originalMetrics;
+      this.telemetryState.originalMetrics = undefined;
+    }
+  }
+  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 = async () => {
+      const activeRegistration = telemetryState.registrations.at(-1);
+      await activeRegistration?.refresh();
+      return await originalMetrics.call(registry);
+    };
+  }
+  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;
+  }
+  syncSnapshot(snapshot) {
     const env = this.labels?.env ?? 'unknown';
     const instance = this.labels?.instance ?? 'local';
     const components = [{
@@ -190,21 +327,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
@@ -212,32 +345,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);
       }
@@ -246,20 +377,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;
@@ -267,49 +401,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 message = String(containerError.message ?? '');
-  const token = typeof containerError.meta?.['token'] === 'string' ? containerError.meta['token'] : undefined;
-  if (token && PLATFORM_SHELL_TOKEN_NAMES.has(token)) {
-    return message.startsWith(`No provider registered for token ${token}.`);
-  }
-  for (const tokenName of PLATFORM_SHELL_TOKEN_NAMES) {
-    if (message.startsWith(`No provider registered for token ${tokenName}.`)) {
-      return true;
-    }
-  }
-  return false;
+  const token = typeof containerError.meta?.token === 'string' ? containerError.meta.token : undefined;
+  return token !== undefined && PLATFORM_SHELL_TOKEN_NAMES.has(token);
 }
 function resolveHttpOptions(http) {
   if (!http) {
@@ -318,6 +503,9 @@ function resolveHttpOptions(http) {
   if (http === true) {
     return {};
   }
+  if (http.pathLabelMode === 'raw' && http.allowUnsafeRawPathLabelMode !== true) {
+    throw new Error('HttpMetricsMiddleware pathLabelMode "raw" is disabled by default. Pass allowUnsafeRawPathLabelMode: true only when you have bounded path cardinality.');
+  }
   return {
     allowUnsafeRawPathLabelMode: http.allowUnsafeRawPathLabelMode,
     pathLabelMode: http.pathLabelMode,

package/package.json

@@ -8,7 +8,7 @@
     "monitoring",
     "observability"
   ],
-  "version": "1.0.3",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,9 +36,10 @@
   ],
   "dependencies": {
     "prom-client": "^15.1.3",
-    "@fluojs/di": "^1.0.3",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/runtime": "^1.1.1"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/di": "^2.0.0",
+    "@fluojs/http": "^2.0.1",
+    "@fluojs/runtime": "^2.0.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",