diff --git a/README.md b/README.md index 2147ade..ae0a94d 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,10 @@ curl -H "Accept: application/json" http://localhost:8080/monitor ## Fiber -`monitor` is built on `net/http`. Fiber is based on `fasthttp`, but Fiber's official adaptor middleware can wrap `net/http` middleware: +`monitor` is built on `net/http`. Fiber is based on `fasthttp`, so the safest integration today is to create one monitor instance during startup and expose only the monitor endpoint through Fiber's official adaptor. + +> Important: do not call `monitor.New` or `monitor.NewMonitor` inside `adaptor.HTTPMiddleware`. +> Fiber executes that middleware factory for every request, while each monitor instance starts one background collector goroutine. Creating a monitor instance per request will leak collector goroutines. ```go package main @@ -91,11 +94,12 @@ import ( func main() { app := fiber.New() - app.Use(adaptor.HTTPMiddleware(func(next http.Handler) http.Handler { - return monitor.New(next, monitor.Config{ - Path: "/monitor", - }) - })) + m := monitor.NewMonitor(http.NotFoundHandler(), monitor.Config{ + Path: "/monitor", + }) + defer m.Stop() + + app.All("/monitor", adaptor.HTTPHandler(m)) app.Get("/", func(c *fiber.Ctx) error { return c.SendString("hello") @@ -107,6 +111,8 @@ func main() { Open `http://localhost:8080/monitor`. +This Fiber example safely serves the monitor page and JSON snapshot, but it does not wrap all Fiber routes. Therefore `http.total_requests` only reflects requests handled by this monitor handler. If you need full Fiber business request accounting, use a native Fiber adapter instead of wrapping `monitor.New` with `adaptor.HTTPMiddleware`. + ## Configuration ```go diff --git a/docs/releases/v1.0.1.md b/docs/releases/v1.0.1.md new file mode 100644 index 0000000..41d7c11 --- /dev/null +++ b/docs/releases/v1.0.1.md @@ -0,0 +1,21 @@ +# v1.0.1 Release Notes + +`monitor` v1.0.1 is a documentation-focused patch release that corrects the Fiber integration guidance. + +## Fixed + +- Corrected the Fiber README examples to avoid creating `monitor.New` or `monitor.NewMonitor` inside `adaptor.HTTPMiddleware`. +- Documented that Fiber's `adaptor.HTTPMiddleware` executes its middleware factory per request, while each monitor instance starts one background collector goroutine. +- Added explicit guidance to create a single monitor instance during service startup and expose the monitor endpoint through `adaptor.HTTPHandler`. +- Synchronized the corrected Fiber guidance across the English and Simplified Chinese README files. + +## Operational Notes + +- Correct `net/http` usage, where `monitor.New` is called once during startup, does not leak one collector goroutine per request. +- `NewMonitor` should be paired with `Stop()` when the monitor lifecycle is shorter than the process lifecycle, such as in tests or temporary servers. +- The safe Fiber example in this release exposes the monitor page and JSON snapshot, but it does not wrap all Fiber routes. Full Fiber business request accounting should be implemented with a native Fiber adapter instead of wrapping `monitor.New` through `adaptor.HTTPMiddleware`. + +## Upgrade Notes + +- No runtime API or behavior changes are included in this release. +- Users who copied the previous Fiber example should update their integration to create one monitor instance at startup. diff --git a/docs/zh/README.md b/docs/zh/README.md index 6ffbaf4..d75d12b 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -72,7 +72,10 @@ curl -H "Accept: application/json" http://localhost:8080/monitor ## Fiber -`monitor` 基于 `net/http`。Fiber 基于 `fasthttp`,但 Fiber 官方 adaptor 中间件可以包装 `net/http` 中间件: +`monitor` 基于 `net/http`。Fiber 基于 `fasthttp`,因此当前最安全的接入方式是在服务启动阶段只创建一个 monitor 实例,然后通过 Fiber 官方 adaptor 只暴露监控端点。 + +> 重要:不要在 `adaptor.HTTPMiddleware` 内部调用 `monitor.New` 或 `monitor.NewMonitor`。 +> Fiber 会在每个请求里执行这个中间件工厂函数,而每个 monitor 实例都会启动一个后台采集 goroutine。如果每个请求都创建 monitor 实例,就会泄漏采集 goroutine。 ```go package main @@ -88,11 +91,12 @@ import ( func main() { app := fiber.New() - app.Use(adaptor.HTTPMiddleware(func(next http.Handler) http.Handler { - return monitor.New(next, monitor.Config{ - Path: "/monitor", - }) - })) + m := monitor.NewMonitor(http.NotFoundHandler(), monitor.Config{ + Path: "/monitor", + }) + defer m.Stop() + + app.All("/monitor", adaptor.HTTPHandler(m)) app.Get("/", func(c *fiber.Ctx) error { return c.SendString("hello") @@ -104,6 +108,8 @@ func main() { 打开 `http://localhost:8080/monitor`。 +这个 Fiber 示例可以安全地提供监控页面和 JSON 快照,但它不会包裹所有 Fiber 路由。因此 `http.total_requests` 只会反映这个 monitor handler 处理到的请求。如果你需要完整统计 Fiber 业务请求,请使用原生 Fiber adapter,而不是用 `adaptor.HTTPMiddleware` 包装 `monitor.New`。 + ## 配置 ```go