feature/fgprof (#5)

* feat: fgprof * test: add unit test for fgprof * style: add header * doc: add desc for fgprof * doc: add desc for fgprof * fix: typo * style: rollback license heacder change * style: remove space * chore: change skywalking-eyes hertz version
hertz-contrib · Apr 20, 2023 · a4a0c43 · a4a0c43
1 parent 367bfa5
commit a4a0c43
Show file tree

Hide file tree

Showing 14 changed files with 645 additions and 9 deletions.
diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
@@ -9,7 +9,7 @@ jobs:
  - uses: actions/checkout@v3
 
  - name: Check License Header
- uses: apache/skywalking-eyes@main
+ uses: apache/skywalking-eyes/header@501a28d2fb4a9b962661987e50cf0219631b32ff
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

diff --git a/README.md b/README.md
@@ -7,14 +7,18 @@ This project would not have been possible without the support from the CloudWeGo
 
 - Package pprof serves via its HTTP server runtime profiling data in the format expected by the pprof visualization tool.
 
+fgprof inspired by [fgprof](https://github.com/felixge/fgprof).
+
+If fgprof is used,please upgrade to Go 1.19 or newer. In older versions of Go fgprof can cause significant STW latencies in applications with a lot of goroutines (> 1-10k). See [CL 387415](https://go-review.googlesource.com/c/go/+/387415) for more details.
+
 
 ## Install
 ```shell
 go get github.com/hertz-contrib/pprof
 ```
 
 ## Usage
-### Example
+### pprof Example 
 
 ```go
 package main
@@ -102,7 +106,93 @@ func main() {
  h.Spin()
 }
 ```
+### fgprof example
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
+
+ h := server.Default()
+
+ pprof.FgprofRegister(h)
+
+ h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ h.Spin()
+```
+
+### change default path prefix
+
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
 
+func main() {
+ h := server.Default()
+
+ // default is "debug/pprof"
+ pprof.FgprofRegister(h, "dev/fgprof")
+
+ h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ h.Spin()
+}
+
+```
+
+### custom router group
+
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
+
+func main() {
+ h := server.Default()
+
+ pprof.FgprofRegister(h)
+
+ adminGroup := h.Group("/admin")
+
+ adminGroup.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ pprof.FgprofRouteRegister(adminGroup, "fgprof")
+
+ h.Spin()
+}
+```
+---
 
 ### Use the pprof tool
 
@@ -130,6 +220,14 @@ Or to collect a 5-second execution trace:
 wget http://localhost:8888/debug/pprof/trace?seconds=5
 ```
 
+### Use the fgprof tool
+
+Taking and analyzing a 3s profile：
+
+```
+go tool pprof --http=:6061 http://localhost:6060/debug/fgprof?seconds=3
+```
+
 
 ## License
 This project is under the Apache License 2.0. See the LICENSE file for the full license text.
diff --git a/README_CN.md b/README_CN.md
@@ -5,14 +5,16 @@
 pprof 是为 Hertz 框架开发的中间件，参考了 [Gin](https://github.com/gin-gonic/gin) 中 [pprof](https://github.com/gin-contrib/pprof) 的实现。
 本项目的完成得益于 CloudWeGo 社区的工作以及 Gin 社区所做的相关前置工作。
 
+fgprof 部分参考了 [fgprof](https://github.com/felixge/fgprof)的实现。
+如果使用了fgprof，请升级到Go 1.19或更高版本。在旧版本的Go中，对于具有大量goroutine（>1-10k）的应用程序，fgprof可能会导致显著的STW延迟。有关更多详细信息，请参见 [CL 387415](https://go-review.googlesource.com/c/go/+/387415)。
 
 ## 安装
 ```shell
 go get github.com/hertz-contrib/pprof
 ```
 
 ## 使用
-### 代码实例1
+### pprof 代码实例1
 
 ```go
 package main
@@ -40,7 +42,7 @@ func main() {
 }
 ```
 
-### 代码实例2: 自定义前缀
+### pprof 代码实例2: 自定义前缀
 
 ```go
 package main
@@ -69,7 +71,7 @@ func main() {
 }
 ```
 
-### 代码实例3: 自定义路由组
+### pprof 代码实例3: 自定义路由组
 
 ```go
 package main
@@ -101,8 +103,95 @@ func main() {
 }
 ```
 
+### fgprof 代码实例1
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
+
+ h := server.Default()
+
+ pprof.FgprofRegister(h)
+
+ h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ h.Spin()
+```
+
+### fgprof 代码实例2: 自定义前缀
 
-### 如何使用
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
+
+func main() {
+ h := server.Default()
+
+ // default is "debug/pprof"
+ pprof.FgprofRegister(h, "dev/fgprof")
+
+ h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ h.Spin()
+}
+
+```
+
+### fgprof 代码实例3：自定义路由组
+
+```go
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+ "github.com/hertz-contrib/pprof"
+)
+
+func main() {
+ h := server.Default()
+
+ pprof.FgprofRegister(h)
+
+ adminGroup := h.Group("/admin")
+
+ adminGroup.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ pprof.FgprofRouteRegister(adminGroup, "fgprof")
+
+ h.Spin()
+}
+```
+---
+
+### 如何使用 pprof
 
 使用 `pprof tool` 工具查看堆栈采样信息：
 
@@ -128,6 +217,13 @@ go tool pprof http://localhost:8888/debug/pprof/block
 wget http://localhost:8888/debug/pprof/trace?seconds=5
 ```
 
+### 如何使用 fgprof
+
+使用 `pprof tool` 工具查看 3s 内的采样信息：
+
+```
+go tool pprof --http=:6061 http://localhost:8888/debug/fgprof?seconds=3
+```
 
 ## License
 This project is under the Apache License 2.0. See the LICENSE file for the full license text.
diff --git a/example/fgprof/custom_prefix/server.go b/example/fgprof/custom_prefix/server.go
@@ -0,0 +1,66 @@
+/*
+ * Copyright 2023 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015-present Aliaksandr Valialkin, VertaMedia, Kirill Danshin, Erik Dubbelboer, FastHTTP Authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * This file may have been modified by CloudWeGo authors. All CloudWeGo
+ * Modifications are Copyright 2022 CloudWeGo Authors.
+ */
+
+package main
+
+import (
+ "context"
+
+ "github.com/cloudwego/hertz/pkg/app"
+ "github.com/cloudwego/hertz/pkg/app/server"
+ "github.com/cloudwego/hertz/pkg/common/utils"
+ "github.com/cloudwego/hertz/pkg/protocol/consts"
+
+ "github.com/hertz-contrib/pprof"
+)
+
+func main() {
+ h := server.Default()
+
+ // default is "debug/pprof"
+ pprof.FgprofRegister(h, "dev/fgprof")
+
+ h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
+ ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
+ })
+
+ h.Spin()
+}