chore: Optimizing hertz observability (#845)

Signed-off-by: rogerogers <[email protected]>

content/en/docs/hertz/tutorials/observability/instrumentation.md

@@ -0,0 +1,58 @@
+---
+title: "Instrumentation"
+date: 2023-10-28
+weight: 3
+keywords: ["Hertz", "Stats", "Instrumentation"]
+description: Hertz supports flexible enabling of basic and fine-grained Instrumentation
+---
+
+## Stats Level
+
+| Option        | Description                             | Enable Strategy                                  |
+| ------------- | --------------------------------------- | ------------------------------------------------ |
+| LevelDisabled | disable all events                      | When tracer is not available, enable by default. |
+| LevelBase     | enable basic events                     |                                                  |
+| LevelDetailed | enable basic events and detailed events | When tracer is available, enable by default.     |
+
+## Stats Level Control
+
+```go
+package main
+
+import (
+    "github.com/cloudwego/hertz/pkg/app/server"
+    "github.com/cloudwego/hertz/pkg/common/tracer/stats"
+)
+
+func main() {
+    h := server.Default(server.WithTraceLevel(stats.LevelBase))
+    h.Spin()
+}
+```
+
+## Stats introduction
+
+### Basic Stats Event
+
+1. `HTTPStart` : Http start
+2. `HTTPFinish` : Http finish
+
+### Detailed Stats Event
+
+1. `ReadHeaderStart`：read header start
+2. `ReadHeaderFinish`：read header finish
+3. `ReadBodyStart`：read body start
+4. `ReadBodyFinish`：read body finish
+5. `ServerHandleStart`：server handler start
+6. `ServerHandleFinish`：server handler finish
+7. `WriteStart`：write response start
+8. `WriteFinish`：write response finish
+
+> If you do not want to record this information, you can either not register any tracer or set the tracking strategy to LevelDisabled, and the framework will not record this information.
+>
+> - **Setting the stats level of a certain node in the tracing to `LevelDisabled` will result in the loss of spans/metrics for that node, but it will not cause the tracing to be interrupted.**
+> - **Not registering any tracer will also result in the loss of spans/metrics for that node, and it will also cause the tracing to be interrupted.**
+
+### Timeline
+
+![timeline](/img/docs/hertz_tracing_timeline.png)

content/en/docs/hertz/tutorials/observability/monitoring.md

@@ -2,7 +2,7 @@
 title: "Monitoring"
 linkTitle: "Monitoring"
 date: 2022-06-21
-weight: 3
+weight: 4
 keywords: ["Monitoring"]
 description: "Hertz provides monitoring capabilities."
 

content/en/docs/hertz/tutorials/observability/open-telemetry.md

@@ -1,7 +1,7 @@
 ---
 title: "OpenTelemetry"
 date: 2022-09-13
-weight: 4
+weight: 5
 keywords: ["OpenTelemetry"]
 description: "Hertz provides openTelemetry capabilities."
 ---

content/en/docs/hertz/tutorials/observability/tracing.md

@@ -3,7 +3,7 @@ title: "Tracing"
 linkTitle: "Tracing"
 weight: 2
 keywords: ["Tracing"]
-description: "Hertz provides tracing capabilities."
+description: "Hertz provides tracing capabilities"
 ---
 
 In microservices, link tracing is a very important capability, which plays an important role in quickly locating problems, analyzing business bottlenecks, and restoring the link status of a request. Hertz provides the capability of link tracking and also supports user-defined link tracking.
@@ -41,26 +41,13 @@ type HTTPStats interface {
 }
 ```
 
-Events include：
+Hertz supports flexible enabling of basic and fine-grained instrumentation. For more details, please refer to [Instrumentation](../instrumentation).
 
-```go
-HTTPStart  = newEvent(httpStart, LevelBase) // Request start
-HTTPFinish = newEvent(httpFinish, LevelBase) // Request end
-
-ServerHandleStart  = newEvent(serverHandleStart, LevelDetailed) // Business handler start
-ServerHandleFinish = newEvent(serverHandleFinish, LevelDetailed) // Business handler end
-ReadHeaderStart    = newEvent(readHeaderStart, LevelDetailed) // Read header start
-ReadHeaderFinish   = newEvent(readHeaderFinish, LevelDetailed) // Read header end
-ReadBodyStart      = newEvent(readBodyStart, LevelDetailed) // Read body start
-ReadBodyFinish     = newEvent(readBodyFinish, LevelDetailed) // Read body end
-WriteStart         = newEvent(writeStart, LevelDetailed) // Write response start
-WriteFinish        = newEvent(writeFinish, LevelDetailed) // Write response end
-```
-
-The above information is available at Finish
+The hertz-contrib provides the extension methods for [opentracing](https://opentracing.io/) and [opentelemetry](https://opentelemetry.io), and the hertz-examples also provide the [opentracing example](https://github.com/cloudwego/hertz-examples/tree/main/tracer) and [opentelemetry example](https://github.com/cloudwego/hertz-examples/tree/main/opentelemetry).
 
-At the same time, if you don't want to log this information, you don't have to register any tracer, and the framework stops logging this information.
+Related repositories:
 
-An extension for opentracing is provided in hertz-contrib, and a demo for calling from http to rpc is also available in [hertz-examples](https://github.com/cloudwego/hertz-examples/tree/main/tracer).
+- [hertz opentelemetry](https://github.com/hertz-contrib/obs-opentelemetry/)
+- [hertz opentracing](https://github.com/hertz-contrib/tracer)
 
-Related Repository： https://github.com/hertz-contrib/tracer
+> OpenTracing has been deprecated. For specific reasons, please refer to [Deprecating OpenTracing](https://github.com/opentracing/specification/issues/163). Unless there are specific reasons, it is recommended to use [Opentelemetry](../open-telemetry).

content/zh/docs/hertz/tutorials/observability/instrumentation.md

@@ -0,0 +1,58 @@
+---
+title: "埋点"
+date: 2023-10-28
+weight: 3
+keywords: ["Hertz", "Stats", "Instrumentation"]
+description: Hertz 支持灵活启用基本埋点和细粒度埋点
+---
+
+## 埋点粒度
+
+| 参数          | 介绍                     | 启用策略               |
+| ------------- | ------------------------ | ---------------------- |
+| LevelDisabled | 禁用埋点                 | 无 tracer 时，默认启用 |
+| LevelBase     | 仅启用基本埋点           |                        |
+| LevelDetailed | 启用基本埋点和细粒度埋点 | 有 tracer 时，默认启用 |
+
+## 埋点粒度控制
+
+```go
+package main
+
+import (
+    "github.com/cloudwego/hertz/pkg/app/server"
+    "github.com/cloudwego/hertz/pkg/common/tracer/stats"
+)
+
+func main() {
+    h := server.Default(server.WithTraceLevel(stats.LevelBase))
+    h.Spin()
+}
+```
+
+## 埋点说明
+
+### 基本埋点
+
+1. `HTTPStart` : 请求开始
+2. `HTTPFinish` : 请求结束
+
+### 细粒度埋点
+
+1. `ReadHeaderStart`：读取 header 开始
+2. `ReadHeaderFinish`：读取 header 结束
+3. `ReadBodyStart`：读取 body 开始
+4. `ReadBodyFinish`：读取 body 结束
+5. `ServerHandleStart`：业务 handler 开始
+6. `ServerHandleFinish`：业务 handler 结束
+7. `WriteStart`：写 response 开始
+8. `WriteFinish`：写 response 结束
+
+> 如果不希望记录这些信息，可以不注册任何 tracer 或者将埋点策略设置为 `LevelDisabled`，则框架不会记录这些信息。
+>
+> - **将链路中某节点埋点策略设置为 `LevelDisabled`，会导致本节点 span/matrics 丢失，不会导致链路中断**
+> - **不注册任何 tracer，也会导致本节点 span/metrics 丢失，同时也会导致链路中断**
+
+### 时序图
+
+![timeline](/img/docs/hertz_tracing_timeline.png)

content/zh/docs/hertz/tutorials/observability/monitoring.md

@@ -1,7 +1,7 @@
 ---
 title: "监控"
 linkTitle: "监控"
-weight: 3
+weight: 4
 keywords: ["监控"]
 description: "Hertz 提供的监控能力。"
 

content/zh/docs/hertz/tutorials/observability/open-telemetry.md

@@ -1,7 +1,7 @@
 ---
 title: "OpenTelemetry"
 date: 2022-09-01
-weight: 4
+weight: 5
 keywords: ["OpenTelemetry"]
 description: "Hertz 提供的 OpenTelemetry 能力。"
 ---

content/zh/docs/hertz/tutorials/observability/tracing.md

@@ -3,8 +3,7 @@ title: "链路追踪"
 linkTitle: "链路追踪"
 weight: 2
 keywords: ["链路追踪"]
-description: "Hertz 提供的链路追踪能力。"
-
+description: "Hertz 提供的链路追踪能力"
 ---
 
 在微服务中，链路追踪是一项很重要的能力，在快速定位问题，分析业务瓶颈，还原一次请求的链路情况等方面发挥重要作用。Hertz 提供了链路追踪的能力，也支持用户自定义链路跟踪。
@@ -42,25 +41,13 @@ type HTTPStats interface {
 }
 ```
 
-事件包括：
-
-```go
-HTTPStart  = newEvent(httpStart, LevelBase) // 请求开始
-HTTPFinish = newEvent(httpFinish, LevelBase) // 请求结束
+Hertz 支持灵活启用基本埋点和细粒度埋点，具体请参考 [埋点](../instrumentation)
 
-ServerHandleStart  = newEvent(serverHandleStart, LevelDetailed) // 业务 handler 开始
-ServerHandleFinish = newEvent(serverHandleFinish, LevelDetailed) // 业务 handler 结束
-ReadHeaderStart    = newEvent(readHeaderStart, LevelDetailed) // 读取 header 开始
-ReadHeaderFinish   = newEvent(readHeaderFinish, LevelDetailed) // 读取 header 结束
-ReadBodyStart      = newEvent(readBodyStart, LevelDetailed) // 读取 body 开始
-ReadBodyFinish     = newEvent(readBodyFinish, LevelDetailed) // 读取 body 结束
-WriteStart         = newEvent(writeStart, LevelDetailed) // 写 response 开始
-WriteFinish        = newEvent(writeFinish, LevelDetailed) // 写 response 结束
-```
+hertz-contrib 中提供了 [opentracing](https://opentracing.io/) 和 [opentelemetry](https://opentelemetry.io/) 的扩展方式，也在 hertz-examples 中提供了 [opentracing example](https://github.com/cloudwego/hertz-examples/tree/main/tracer) 以及 [opentelemetry example](https://github.com/cloudwego/hertz-examples/tree/main/opentelemetry)
 
-在 Finish 时可以获取到上述信息。
+相关仓库：
 
-同时，如果不希望记录这些信息，可以不注册任何 tracer，则框架停止对这些信息的记录。
+- [hertz opentelemetry](https://github.com/hertz-contrib/obs-opentelemetry/)
+- [hertz opentracing](https://github.com/hertz-contrib/tracer)
 
-hertz-contrib 中提供了 opentracing 的扩展方式，也在 [hertz-examples](https://github.com/cloudwego/hertz-examples/tree/main/tracer) 提供了可以从 http 到 rpc 调用的 demo。
-仓库：https://github.com/hertz-contrib/tracer
+> OpenTracing 已经被弃用，具体原因可以查看 [Deprecating OpenTracing](https://github.com/opentracing/specification/issues/163)，如果没有特殊的理由，推荐使用 [Opentelemetry](../open-telemetry)