Proposal：CloudWeGo 统一可观测性套件

[CoderPoet]

背景

• 社区目前维护了两个有部分重叠模块的拓展库：https://github.com/kitex-contrib/obs-opentelemetry 和 https://github.com/hertz-contrib/obs-opentelemetry 当 kitex 和 hertz 一起使用的情况，用户可能会面临一些选择上的困惑及使用上的问题：
  • 重复的 otel provider 封装，用户难以抉择选择哪一个
  • 重复的 otel log 的集成，用户难以抉择选择哪一个
  • Otel 本身也在快速迭代，不同版本之间不保证 API 的向前兼容性，为两个拓展库的版本依赖管理带来成本
• 目前社区也分别维护了 Prometheus、Opentelemetry相关拓展库，二者的初始化流程存在差异，无法很好平滑替换，以至于在指标场景用户可能也存在一些选择困难
• 缺少开箱即用的 Profiling 集成
• 缺少一个开箱即用的 Grafana Dashboard
• 缺少 Health Checker 相关实现
• 缺乏无缝集成社区已有微服务常用中间件相关的 OpenTelemetry Instrumentation 的统一集成方案及样例：如 Gorm、Redis、ES、Mongo 等等

目标

• 围绕 CloudWeGo 生态打造一个开箱即用、用户友好、面向生产最佳实践的可观测套件，统一集成可观测领域相关工具，包括但不限于：OpenTelemetry、Prometheus、Logger、Profiling、Health Checker
• 提供接入 All in Grafana 全家桶（Pyroscope、Tempo、Loki）的集成方案，并通过数据源和插件的方式集成 Jaeger、VictoriaMetrics
• 提供开箱即用的 Grafana Dashboard 模板，覆盖 R.E.D、Runtime、容器观测、Tracing、Profiling 等核心场景，并提供 Examplar 集成方案
• 提供无缝集成社区已有微服务常用中间件相关 OpenTelemetry Instrumentation 的统一集成方案及样例：如 Gorm、Redis、ES、Mongo 等等
• 集成框架 Debug、dump 等 Diagnosis 诊断能力
• 沉淀可观测性相关最佳实践，形成文档、工程案例等
• 提供业务自定义观测埋点方案及最佳实践

非目标

• 中间件库的插桩：尽量是采用复用社区已有 Instrumentation，不重复造轮子

术语

术语	说明
OpenTelemetry	CNCF 的一个开源可观测框架， 是由一系列工具、API、SDK 组成
Instrumentation	基于切面机制，为一系列框架、库提供 OpenTelemetry 集成，对业务低侵入
Pyroscope	一个开源的 Profiling 平台，已被 Grafana 收购，纳入 Grafana 全家桶
VictoriaMetrics	兼容 Prometheus 的 TSDB，可用于 Prometheus 监控数据做长期远程存储
Jaeger	开源 Tracing 平台，支持作为 Grafana 数据源集成

整体方案

提供一个统一的 Telemetry Repo，Repo 主要分层逻辑为：

• Telemetry Provider：统一抽象并封装各个开源观测工具的集成逻辑

  • 提供 opentelemetry provider 相关的初始化逻辑封装
  • 提供 logging 库相关初始逻辑封装
  • 提供 health checker 标准方法，提供 healthchecker 的全生命周期管理（注册，管理，运行，暴露）
  • 提供 metrics 的标准暴露方法 Interface，管理和暴露 metrics registry
  • 提供 pprof 接口，支持 pyroscope 拉取
  • 提供 Debug 接口，集成框架 Debug、dump 等 Diagnosis 诊断能力

• Telemetry Server：整合所有需要暴露 HTTP 接口的功能，复用同一接口，统一暴露，包括不限于：metrics、pprof、healthcheck、debug 等等

• Telemetry Instrumentation：

  • 专注统一处理各个框架、中间件的具体插桩埋点逻辑
  • 支持复用社区已有 Instrumentation，如：
    • https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation
    • https://github.com/uptrace/opentelemetry-go-extra

• Telemetry Integration：

  • 提供主流开源可观测性平台的集成方案，并形成最佳实践
  • 提供开箱即用的 Grafana Dashboard 模板
  • 提供能够在 kubernetes 环境一键拉起的 ServiceMonitor/PodMonitor 模板

• Examples

  • 提供能够在 kubernetes 环境一键拉起的完整 Demo 示例工程，集成所有插件，并默认和 grafana 全家桶集成

[GuangmingLuo]

Note: 需要梳理下各项工作优先级

[BaiZe1998]

I hope to be involved in this part of the work together

[CoderPoet]

I hope to be involved in this part of the work together

This PR #2 is dealing with this, if you are interested, you can help review it together

[smx-Morgan]

Work In Progress