From c806ee76195dffffb17b74d8eaae78d9c2ec85f0 Mon Sep 17 00:00:00 2001 From: chenhuan Date: Tue, 8 Jul 2025 18:07:31 +0800 Subject: [PATCH 1/4] Add OpenTelemetry integration design in client_design.md Signed-off-by: chenhuan --- src/guide/develop/client_design.md | 56 ++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/src/guide/develop/client_design.md b/src/guide/develop/client_design.md index ec4c2370..d63accc0 100644 --- a/src/guide/develop/client_design.md +++ b/src/guide/develop/client_design.md @@ -411,3 +411,59 @@ $operation failed, error: $error_details # example: writePoint failed, unmarshall response body error: json: cannot unmarshal number ... ``` +# OpenTelemetry 集成设计 +为提升OpenGemini Go客户端的可观测性，便于追踪查询与写入操作的性能、错误等信息，本方案采用拦截器模式集成OpenTelemetry，实现全链路追踪。该设计支持非侵入式扩展，可与其他拦截器（如日志、认证）共存，同时保持对原生客户端的最小修改。 + +## 定义拦截器接口 + +```mermaid +interface Interceptor { ++ context.Context QueryBefore(context.Context, string) ++ void QueryAfter(context.Context, string, error) ++ context.Context WriteBefore(context.Context, []byte) ++ void WriteAfter(context.Context, []byte, error) +} +``` + +## 定义基础客户端类，关联拦截器接口 + +```mermaid +class Client { +- []Interceptor interceptors ++ Client(interceptors ...Interceptor) ++ AddInterceptor(interceptors ...Interceptor) ++ context.Context doQueryBefore(context.Context, string) ++ void doQueryAfter(context.Context, string, error) ++ context.Context doWriteBefore(context.Context, []byte) ++ void doWriteAfter(context.Context, []byte, error) +} +``` + +## 定义集成 OpenTelemetry 的拦截器实现类，实现 Interceptor 接口 + +```mermaid +class OtelClient { +- trace.Tracer tracer ++ OtelClient() ++ context.Context QueryBefore(context.Context, string) ++ void QueryAfter(context.Context, string, error) ++ context.Context WriteBefore(context.Context, []byte) ++ void WriteAfter(context.Context, []byte, error) +} +``` + +## 定义主函数使用示例相关流程（简化体现调用关系） + +```mermaid +class Main { ++ static func initOtel() func() ++ static func main() ++ static func performQuery(context.Context, string) error +} + +接口与类之间的实现、关联关系 +Client --> Interceptor : 包含多个 +OtelClient --> Interceptor : 实现 +Main --> Client : 使用 +Main --> OtelClient : 初始化并添加到 Client +``` \ No newline at end of file From 7b2815d68b7dbedb0782d5a4c10b88c21d1c1afa Mon Sep 17 00:00:00 2001 From: chenhuan Date: Tue, 8 Jul 2025 22:44:35 +0800 Subject: [PATCH 2/4] Add OpenTelemetry integration design in client_design.md Signed-off-by: chenhuan --- src/guide/develop/client_design.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/guide/develop/client_design.md b/src/guide/develop/client_design.md index d63accc0..29bfdf78 100644 --- a/src/guide/develop/client_design.md +++ b/src/guide/develop/client_design.md @@ -411,10 +411,10 @@ $operation failed, error: $error_details # example: writePoint failed, unmarshall response body error: json: cannot unmarshal number ... ``` -# OpenTelemetry 集成设计 -为提升OpenGemini Go客户端的可观测性，便于追踪查询与写入操作的性能、错误等信息，本方案采用拦截器模式集成OpenTelemetry，实现全链路追踪。该设计支持非侵入式扩展，可与其他拦截器（如日志、认证）共存，同时保持对原生客户端的最小修改。 +# OpenTelemetry integration design +To enhance the observability of the OpenGemini Go client and facilitate tracking of performance metrics, errors, and other information related to query and write operations, this solution adopts the interceptor pattern to integrate OpenTelemetry, enabling full-link tracing. The design supports non-intrusive extensions, allowing coexistence with other interceptors (such as logging and authentication interceptors) while minimizing modifications to the original client. -## 定义拦截器接口 +## Define the interceptor interface ```mermaid interface Interceptor { @@ -425,7 +425,7 @@ interface Interceptor { } ``` -## 定义基础客户端类，关联拦截器接口 +## Define the base client class,associated with the Interceptor interface ```mermaid class Client { @@ -439,7 +439,7 @@ class Client { } ``` -## 定义集成 OpenTelemetry 的拦截器实现类，实现 Interceptor 接口 +## Define the interceptor implementation class integrating OpenTelemetry,implementing the Interceptor interface ```mermaid class OtelClient { @@ -452,7 +452,7 @@ class OtelClient { } ``` -## 定义主函数使用示例相关流程（简化体现调用关系） +## Define processes related to main function usage examples (simplified to show invocation relationships) ```mermaid class Main { From c5d3e2fa52e30f45d9607ea1130a8cc552f806fe Mon Sep 17 00:00:00 2001 From: chenhuan Date: Thu, 10 Jul 2025 19:15:25 +0800 Subject: [PATCH 3/4] Add OpenTelemetry integration design in client_design.md Signed-off-by: chenhuan --- src/guide/develop/client_design.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/guide/develop/client_design.md b/src/guide/develop/client_design.md index 29bfdf78..a150eecd 100644 --- a/src/guide/develop/client_design.md +++ b/src/guide/develop/client_design.md @@ -461,9 +461,9 @@ class Main { + static func performQuery(context.Context, string) error } -接口与类之间的实现、关联关系 -Client --> Interceptor : 包含多个 -OtelClient --> Interceptor : 实现 -Main --> Client : 使用 -Main --> OtelClient : 初始化并添加到 Client +The implementation and association relationships between interfaces and classes +Client --> Interceptor : contains multiple +OtelClient --> Interceptor : implement +Main --> Client : use +Main --> OtelClient : initialize and add to client ``` \ No newline at end of file From 9cadd436136de3436c870a346e00869106e84739 Mon Sep 17 00:00:00 2001 From: chenhuan Date: Sat, 12 Jul 2025 21:25:54 +0800 Subject: [PATCH 4/4] Add Opentelemetry integration design in client_design.md Signed-off-by: chenhuan --- src/guide/develop/client_design.md | 87 ++++++++++----------------- src/zh/guide/develop/client_design.md | 30 +++++++++ 2 files changed, 61 insertions(+), 56 deletions(-) diff --git a/src/guide/develop/client_design.md b/src/guide/develop/client_design.md index a150eecd..ded545b8 100644 --- a/src/guide/develop/client_design.md +++ b/src/guide/develop/client_design.md @@ -245,6 +245,37 @@ classDiagram SeriesResult "1" *-- "0..*" Series: contains ``` +# OpenTelemetry integration design +To enhance the observability of the OpenGemini Go client and facilitate tracking of performance metrics, errors, and other information related to query and write operations, this solution adopts the interceptor pattern to integrate OpenTelemetry, enabling full-link tracing. The design supports non-intrusive extensions, allowing coexistence with other interceptors (such as logging and authentication interceptors) while minimizing modifications to the original client. + +## Interceptor design + +```mermaid +interface Interceptor { + void QueryBefore(context.Context, string) + void QueryAfter(context.Context, string, error) + void WriteBefore(context.Context, []byte) + void WriteAfter(context.Context, []byte, error) +} +``` + +## Define the base client class,associated with the Interceptor interface + +```mermaid +class Client { +- []Interceptor interceptors + +} +``` + +## Define the interceptor implementation class integrating OpenTelemetry,implementing the Interceptor interface + +```mermaid +class OtelClient { + Interceptor +} +``` + # QueryBuilder design ```mermaid @@ -411,59 +442,3 @@ $operation failed, error: $error_details # example: writePoint failed, unmarshall response body error: json: cannot unmarshal number ... ``` -# OpenTelemetry integration design -To enhance the observability of the OpenGemini Go client and facilitate tracking of performance metrics, errors, and other information related to query and write operations, this solution adopts the interceptor pattern to integrate OpenTelemetry, enabling full-link tracing. The design supports non-intrusive extensions, allowing coexistence with other interceptors (such as logging and authentication interceptors) while minimizing modifications to the original client. - -## Define the interceptor interface - -```mermaid -interface Interceptor { -+ context.Context QueryBefore(context.Context, string) -+ void QueryAfter(context.Context, string, error) -+ context.Context WriteBefore(context.Context, []byte) -+ void WriteAfter(context.Context, []byte, error) -} -``` - -## Define the base client class,associated with the Interceptor interface - -```mermaid -class Client { -- []Interceptor interceptors -+ Client(interceptors ...Interceptor) -+ AddInterceptor(interceptors ...Interceptor) -+ context.Context doQueryBefore(context.Context, string) -+ void doQueryAfter(context.Context, string, error) -+ context.Context doWriteBefore(context.Context, []byte) -+ void doWriteAfter(context.Context, []byte, error) -} -``` - -## Define the interceptor implementation class integrating OpenTelemetry,implementing the Interceptor interface - -```mermaid -class OtelClient { -- trace.Tracer tracer -+ OtelClient() -+ context.Context QueryBefore(context.Context, string) -+ void QueryAfter(context.Context, string, error) -+ context.Context WriteBefore(context.Context, []byte) -+ void WriteAfter(context.Context, []byte, error) -} -``` - -## Define processes related to main function usage examples (simplified to show invocation relationships) - -```mermaid -class Main { -+ static func initOtel() func() -+ static func main() -+ static func performQuery(context.Context, string) error -} - -The implementation and association relationships between interfaces and classes -Client --> Interceptor : contains multiple -OtelClient --> Interceptor : implement -Main --> Client : use -Main --> OtelClient : initialize and add to client -``` \ No newline at end of file diff --git a/src/zh/guide/develop/client_design.md b/src/zh/guide/develop/client_design.md index f657ee90..e8fbf19f 100644 --- a/src/zh/guide/develop/client_design.md +++ b/src/zh/guide/develop/client_design.md @@ -230,6 +230,36 @@ classDiagram SeriesResult "1" *-- "0..*" Series: contains ``` +# OpenTelemetry 集成设计 +为提升OpenGemini Go客户端的可观测性，便于追踪查询与写入操作的性能、错误等信息，本方案采用拦截器模式集成OpenTelemetry，实现全链路追踪。该设计支持非侵入式扩展，可与其他拦截器（如日志、认证）共存，同时保持对原生客户端的最小修改。 + +## 拦截器设计 + +```mermaid +interface Interceptor { + void QueryBefore(context.Context, string) + void QueryAfter(context.Context, string, error) + void WriteBefore(context.Context, []byte) + void WriteAfter(context.Context, []byte, error) +} +``` + +## 定义基础客户端类，关联拦截器接口 + +```mermaid +class Client { +- []Interceptor interceptors + +} +``` + +## 定义集成 OpenTelemetry 的拦截器实现类，实现 Interceptor 接口 + +```mermaid +class OtelClient { + Interceptor +``` + # 查询构造器设计 ```mermaid