@fluojs/metrics 1.0.0-beta.1 → 1.0.0-beta.3

package/README.ko.md

@@ -28,7 +28,7 @@ pnpm add @fluojs/metrics
 
 ## 빠른 시작
 
-루트 모듈에 `MetricsModule.forRoot()`를 추가하여 기본 `/metrics` 엔드포인트를 활성화합니다.
+루트 모듈에 `MetricsModule.forRoot()`를 추가하여 기본 `/metrics` 엔드포인트를 활성화합니다. HTTP 요청 수와 지연 시간까지 계측하려면 `http: true` 또는 `http` 옵션 객체를 함께 전달합니다.
 
 ```typescript
 import { Module } from '@fluojs/core';
@@ -36,7 +36,7 @@ import { MetricsModule } from '@fluojs/metrics';
 
 @Module({
   imports: [
-    MetricsModule.forRoot(),
+        MetricsModule.forRoot({ http: true }),
   ],
 })
 class AppModule {}
@@ -44,7 +44,7 @@ class AppModule {}
 // GET /metrics → Prometheus 텍스트 형식
 ```
 
-`MetricsModule.forRoot()`는 기본적으로 `GET /metrics`를 노출합니다. 운영 환경에서는 이 경계를 명시적으로 다루세요. 플랫폼 프록시/네트워크 제어를 붙이기 전까지 `path: false`로 비활성화하거나, 전용 endpoint middleware를 연결하는 방식을 권장합니다.
+`MetricsModule.forRoot()`는 기본적으로 `GET /metrics`를 노출합니다. `http: true`를 전달한 경우에만 HTTP 요청 계측 미들웨어가 설치됩니다. 운영 환경에서는 이 경계를 명시적으로 다루세요. 플랫폼 프록시/네트워크 제어를 붙이기 전까지 `path: false`로 비활성화하거나, 전용 endpoint middleware를 연결하는 방식을 권장합니다.
 
 ## 공통 패턴
 
@@ -116,12 +116,18 @@ const ordersTotal = new Counter({
 
 @Module({
   imports: [
-    MetricsModule.forRoot({ registry: sharedRegistry }),
+     MetricsModule.forRoot({ http: true, registry: sharedRegistry }),
   ],
 })
 class AppModule {}
 ```
 
+여러 `MetricsModule` 인스턴스가 같은 Registry를 의도적으로 공유하는 경우, 내장 HTTP 메트릭은 기존 `http_requests_total`, `http_errors_total`, `http_request_duration_seconds` collector를 재사용합니다. 애플리케이션이 직접 등록한 중복 메트릭 이름은 Prometheus Registry 규칙대로 계속 빠르게 실패합니다.
+
+### 중복 메트릭 이름은 계속 빠르게 실패합니다
+
+Prometheus 메트릭 이름은 하나의 Registry 안에서 고유해야 합니다. 공유 Registry 모드는 애플리케이션 메트릭의 중복 이름을 조용히 덮어쓰지 않고 이 동작을 유지합니다.
+
 ### 런타임 플랫폼 텔레메트리
 
 이 모듈은 플랫폼 셸 및 등록된 컴포넌트의 내부 상태를 반영하는 fluo 전용 Gauge를 자동으로 생성합니다.
@@ -145,6 +151,7 @@ MetricsModule.forRoot({
 플랫폼 텔레메트리는 매 `/metrics` 스크레이프마다 `PLATFORM_SHELL`을 resolve하여 `fluo_component_ready`와 `fluo_component_health`를 갱신합니다.
 
 - `PLATFORM_SHELL` 등록 자체가 빠진 경우에는 스크레이프가 계속 성공하고 플랫폼 텔레메트리 시리즈만 생략됩니다.
+- 이전 스크레이프에서 플랫폼 텔레메트리를 노출한 뒤 `PLATFORM_SHELL`을 사용할 수 없게 되면, stale `fluo_component_ready` 및 `fluo_component_health` 시리즈를 제거한 뒤 메트릭을 반환합니다.
 - 그 외의 `PLATFORM_SHELL` resolve 실패는 조용히 삼키지 않고 스크레이프 실패로 그대로 드러납니다.
 
 ### 기본 프로세스/Node 메트릭 비활성화
@@ -162,16 +169,20 @@ MetricsModule.forRoot({
 - `MetricsModule.forRoot(options)`
 - `MetricsService`
 - `METER_PROVIDER` (Token)
-- 카운터, 게이지, 히스토그램 및 레지스트리 접근을 위한 Prometheus 기반 헬퍼
+- `PrometheusMeterProvider`
+- `HttpMetricsMiddleware` 및 HTTP path-label 옵션 타입
+- `prom-client`의 `Registry`
 
 ### 운영 기본값
 
 - `path`의 기본값은 `'/metrics'`이며, `path: false`로 스크레이프 엔드포인트를 완전히 비활성화할 수 있습니다.
 - `defaultMetrics`의 기본값은 `true`이며, `defaultMetrics: false`로 해당 Registry의 Prometheus 기본 프로세스/Node.js collector를 끌 수 있습니다.
 - `endpointMiddleware`는 스크레이프 엔드포인트에만 route-scoped middleware를 바인딩합니다.
-- HTTP 메트릭은 기본적으로 템플릿 기반 경로 라벨 정규화를 사용합니다.
+- HTTP 메트릭은 `http: true` 또는 `http` 옵션 객체를 전달한 경우에만 설치되며, 설치된 뒤에는 기본적으로 템플릿 기반 경로 라벨 정규화를 사용합니다.
+- 내장 HTTP collector는 같은 Registry를 공유하는 모듈 인스턴스 사이에서 재사용되며, 커스텀 애플리케이션 메트릭 이름 충돌은 Prometheus의 중복 이름 실패 동작을 유지합니다.
 - raw path 라벨은 `allowUnsafeRawPathLabelMode: true`를 명시한 bounded internal route에서만 사용해야 합니다.
 - 플랫폼 텔레메트리는 `PLATFORM_SHELL`이 실제로 누락된 경우에만 생략되며, 그 외 resolve 실패는 스크레이프를 실패시킵니다.
+- 이전에 노출된 플랫폼 텔레메트리 시리즈는 `PLATFORM_SHELL`을 사용할 수 없게 된 스크레이프에서 제거됩니다.
 
 ## 관련 패키지
 

package/README.md

@@ -33,12 +33,12 @@ import { MetricsModule } from '@fluojs/metrics';
 import { Module } from '@fluojs/core';
 
 @Module({
-  imports: [MetricsModule.forRoot()],
+  imports: [MetricsModule.forRoot({ http: true })],
 })
 class AppModule {}
 ```
 
-`MetricsModule.forRoot()` still exposes `GET /metrics` by default. For production deployments, make that endpoint boundary explicit: either disable it with `path: false` until a platform-level proxy is in place, or attach dedicated endpoint middleware.
+`MetricsModule.forRoot()` still exposes `GET /metrics` by default. Pass `http: true` (or an `http` options object) when you want the module to install HTTP request instrumentation middleware. 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.
 
 ## Common Patterns
 
@@ -94,11 +94,13 @@ new Counter({
 });
 
 @Module({
-  imports: [MetricsModule.forRoot({ registry })],
+  imports: [MetricsModule.forRoot({ http: true, registry })],
 })
 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. Application-defined duplicate names still fail fast.
+
 ### Duplicate metric names still fail fast
 
 Prometheus metric names must stay unique inside a registry. Shared-registry mode keeps that behavior intact instead of silently shadowing metrics.
@@ -126,6 +128,7 @@ MetricsModule.forRoot({
 Platform telemetry refreshes `fluo_component_ready` and `fluo_component_health` on each `/metrics` scrape by resolving `PLATFORM_SHELL`.
 
 - If `PLATFORM_SHELL` is not registered, the scrape still succeeds and omits the platform telemetry series.
+- If `PLATFORM_SHELL` becomes unavailable after a previous successful scrape, stale `fluo_component_ready` and `fluo_component_health` series are removed before metrics are returned.
 - If resolving `PLATFORM_SHELL` fails for any other reason, the scrape surfaces that failure instead of swallowing it.
 
 ### Disable default process and Node metrics
@@ -143,16 +146,20 @@ MetricsModule.forRoot({
 - `MetricsModule.forRoot(options)`
 - `MetricsService`
 - `METER_PROVIDER`
-- Prometheus-backed helpers for counters, gauges, histograms, and registry access
+- `PrometheusMeterProvider`
+- `HttpMetricsMiddleware` and HTTP path-label option types
+- `Registry` from `prom-client`
 
 ### Operational defaults
 
 - `path` defaults to `'/metrics'`, and `path: false` disables the scrape endpoint entirely.
 - `defaultMetrics` defaults to `true`, and `defaultMetrics: false` disables Prometheus default process and Node.js collectors for that registry.
 - `endpointMiddleware` binds route-scoped middleware only to the scrape endpoint.
-- HTTP metrics default to template-normalized path labels.
+- 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; custom application metric name collisions keep Prometheus' duplicate-name failure behavior.
 - 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 a prior successful scrape.
 
 ## Related Packages
 

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

@@ -1,5 +1,5 @@
 import type { FrameworkRequest, Middleware, MiddlewareContext, Next } from '@fluojs/http';
-import type { Registry } from 'prom-client';
+import { type Registry } from 'prom-client';
 /** Strategy used to label request paths in emitted HTTP metrics. */
 export type HttpMetricsPathLabelMode = 'raw' | 'template';
 /** Context passed to a custom path-label normalizer. */

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,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkB5C,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;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"}

package/dist/http-metrics-middleware.js

@@ -1,4 +1,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();
 
 /** Strategy used to label request paths in emitted HTTP metrics. */
 
@@ -41,17 +44,17 @@ export class HttpMetricsMiddleware {
     this.pathLabelMode = options.pathLabelMode ?? 'template';
     this.pathLabelNormalizer = options.pathLabelNormalizer;
     this.unknownPathLabel = options.unknownPathLabel ?? 'UNKNOWN';
-    this.requestsTotal = createPrometheusCounter(registry, {
+    this.requestsTotal = getOrCreateHttpCounter(registry, {
       help: 'Total number of HTTP requests',
       labelNames: ['method', 'path', 'status'],
       name: 'http_requests_total'
     });
-    this.errorsTotal = createPrometheusCounter(registry, {
+    this.errorsTotal = getOrCreateHttpCounter(registry, {
       help: 'Total number of HTTP error responses (4xx/5xx)',
       labelNames: ['method', 'path', 'status'],
       name: 'http_errors_total'
     });
-    this.requestDuration = createPrometheusHistogram(registry, {
+    this.requestDuration = getOrCreateHttpHistogram(registry, {
       help: 'HTTP request duration in seconds',
       labelNames: ['method', 'path', 'status'],
       name: 'http_request_duration_seconds'
@@ -116,6 +119,38 @@ export class HttpMetricsMiddleware {
     }
   }
 }
+function getOrCreateHttpCounter(registry, config) {
+  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.`);
+    }
+    return existing;
+  }
+  const counter = createPrometheusCounter(registry, {
+    help: config.help,
+    labelNames: [...config.labelNames],
+    name: config.name
+  });
+  FRAMEWORK_HTTP_COUNTERS.add(counter);
+  return counter;
+}
+function getOrCreateHttpHistogram(registry, config) {
+  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.`);
+    }
+    return existing;
+  }
+  const histogram = createPrometheusHistogram(registry, {
+    help: config.help,
+    labelNames: [...config.labelNames],
+    name: config.name
+  });
+  FRAMEWORK_HTTP_HISTOGRAMS.add(histogram);
+  return histogram;
+}
 function normalizePathToTemplate(path, params) {
   if (!path) {
     return '/';

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Prometheus registry constructor re-exported for applications that want custom
+ * application metrics and Fluo framework metrics to share one scrape endpoint.
+ *
+ * @remarks
+ * The implementation is `prom-client`'s `Registry`; duplicate metric names still
+ * follow Prometheus registry semantics and fail fast.
+ */
 export { Registry } from 'prom-client';
 export * from './metrics-module.js';
 export * from './metrics-service.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,3 +1,11 @@
+/**
+ * Prometheus registry constructor re-exported for applications that want custom
+ * application metrics and Fluo framework metrics to share one scrape endpoint.
+ *
+ * @remarks
+ * The implementation is `prom-client`'s `Registry`; duplicate metric names still
+ * follow Prometheus registry semantics and fail fast.
+ */
 export { Registry } from 'prom-client';
 export * from './metrics-module.js';
 export * from './metrics-service.js';

package/dist/metrics-module.js

@@ -158,6 +158,7 @@ class RuntimePlatformTelemetry {
   async refresh(ctx) {
     const platformShell = await this.resolvePlatformShell(ctx);
     if (!platformShell) {
+      this.clearPlatformTelemetry();
       return;
     }
     const snapshot = await platformShell.snapshot();
@@ -195,6 +196,40 @@ class RuntimePlatformTelemetry {
       toMetricValue: toReadinessValue
     });
   }
+  clearPlatformTelemetry() {
+    this.clearGaugeStatuses({
+      env: this.labels?.env ?? 'unknown',
+      gauge: this.healthGauge,
+      instance: this.labels?.instance ?? 'local',
+      lastStatuses: this.lastHealthStatuses,
+      operation: 'health',
+      statuses: HEALTH_STATUSES
+    });
+    this.clearGaugeStatuses({
+      env: this.labels?.env ?? 'unknown',
+      gauge: this.readinessGauge,
+      instance: this.labels?.instance ?? 'local',
+      lastStatuses: this.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 status of statuses) {
+        gauge.remove(componentId, componentKind, operation, status, env, instance);
+      }
+    }
+    lastStatuses.clear();
+  }
   syncGaugeStatuses({
     currentStatuses,
     env,
@@ -250,12 +285,13 @@ function isMissingPlatformShellResolutionError(error) {
     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 containerError.message.startsWith(`No provider registered for token ${token}.`);
+    return message.startsWith(`No provider registered for token ${token}.`);
   }
   for (const tokenName of PLATFORM_SHELL_TOKEN_NAMES) {
-    if (containerError.message.startsWith(`No provider registered for token ${tokenName}.`)) {
+    if (message.startsWith(`No provider registered for token ${tokenName}.`)) {
       return true;
     }
   }

package/package.json

@@ -8,7 +8,7 @@
     "monitoring",
     "observability"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
   ],
   "dependencies": {
     "prom-client": "^15.1.3",
-    "@fluojs/di": "^1.0.0-beta.1",
-    "@fluojs/runtime": "^1.0.0-beta.1",
-    "@fluojs/http": "^1.0.0-beta.1"
+    "@fluojs/di": "^1.0.0-beta.6",
+    "@fluojs/http": "^1.0.0-beta.9",
+    "@fluojs/runtime": "^1.0.0-beta.9"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",