@fluojs/metrics 1.0.1 → 1.0.3

package/README.ko.md

@@ -42,6 +42,16 @@ class AppModule {}
 
 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`를 전달하세요.
 
+## 공개 책임
+
+| 표면 | 책임 | 경계 |
+| --- | --- | --- |
+| `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이 필요하지 않습니다. |
+| `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의 계약 밖입니다. |
+
 ## 공통 패턴
 
 ### HTTP path label 정규화
@@ -91,7 +101,7 @@ MetricsModule.forRoot({
 });
 ```
 
-`endpointMiddleware`는 class-based `@fluojs/http` middleware constructor를 받으며 metrics scrape endpoint에만 바인딩됩니다. middleware function이나 global middleware declaration은 이 option의 패키지 계약이 아닙니다. HTTP 계측이 활성화된 경우 endpoint middleware가 던진 실패도 내장 HTTP request/error collector에 기록됩니다.
+`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에 기록됩니다.
 
 ### Framework metric과 app metric이 하나의 registry를 공유하기
 
@@ -163,7 +173,7 @@ MetricsModule.forRoot({
 - `METER_PROVIDER` (Token)
 - `PrometheusMeterProvider`
 - `HttpMetricsMiddleware` 및 HTTP path-label 옵션 타입
-- `provider`(현재는 `'prometheus'`만 지원)와 endpoint `middleware`를 포함한 module option
+- `provider`(현재는 `'prometheus'`만 지원), module-level `middleware`, endpoint-scoped `endpointMiddleware`를 포함한 module option
 - `prom-client`의 `Registry`
 
 ### 운영 기본값

package/README.md

@@ -42,6 +42,16 @@ class AppModule {}
 
 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.
 
+## 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. |
+| `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. |
+
 ## Common Patterns
 
 ### Normalize HTTP path labels
@@ -91,7 +101,7 @@ 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. When HTTP instrumentation is enabled, failures thrown by endpoint middleware are recorded in the built-in HTTP request and error collectors.
+`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.
 
 ### Share one registry for framework and app metrics
 
@@ -163,7 +173,7 @@ MetricsModule.forRoot({
 - `METER_PROVIDER`
 - `PrometheusMeterProvider`
 - `HttpMetricsMiddleware` and HTTP path-label option types
-- Module options including `provider` (currently only `'prometheus'`) and endpoint `middleware`
+- Module options including `provider` (currently only `'prometheus'`), module-level `middleware`, and endpoint-scoped `endpointMiddleware`
 - `Registry` from `prom-client`
 
 ### Operational defaults

package/dist/metrics-module.d.ts

@@ -4,23 +4,36 @@ 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 {
+    /** 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. */
     pathLabelNormalizer?: HttpMetricsPathLabelNormalizer;
+    /** Label value used when no normalized path can be derived. */
     unknownPathLabel?: string;
+    /** Explicit opt-in required before raw URL paths may be used as labels. */
     allowUnsafeRawPathLabelMode?: boolean;
 }
 /**
  * Module options for exposing Prometheus metrics and runtime platform telemetry.
  */
 export interface MetricsModuleOptions {
+    /** Enables built-in HTTP request collectors when `true` or configured with path-label options. */
     http?: boolean | MetricsHttpOptions;
+    /** Scrape endpoint path. Defaults to `/metrics`; `false` disables the scrape endpoint and endpoint-scoped middleware. */
     path?: string | false;
+    /** Meter provider implementation. Currently only `prometheus` is supported. */
     provider?: 'prometheus';
+    /** Whether Prometheus process and Node.js default collectors are registered once per registry. Defaults to `true`. */
     defaultMetrics?: boolean;
+    /** Module-level middleware applied after framework HTTP metrics and endpoint-scoped middleware. */
     middleware?: MiddlewareLike[];
+    /** Class-based middleware bound only to the configured scrape endpoint. Ignored when `path: false`. */
     endpointMiddleware?: Array<new (...args: any[]) => Middleware>;
+    /** Fixed labels attached to built-in runtime platform telemetry gauges. */
     platformTelemetry?: {
+        /** Deployment environment label value. Defaults to `unknown`. */
         env?: string;
+        /** Instance label value. Defaults to `local`. */
         instance?: string;
     };
     /** External Prometheus registry to share between built-in and custom metrics. */

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,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,kBAAkB,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC;IAC/D,iBAAiB,CAAC,EAAE;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,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":"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"}

package/package.json

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