Go Contrib
为 Go Packages 提供可观测性的扩展插件。
目标与边界
针对特定的 Go Package 提供 middleware
、interceptor
、plugin
、hook
、callback
等形式的可观测性埋点支持,Go 应用在启动、初始化时加载注册本项目组件,使特定操作(如网络调用、中间件调用)上报可观测性数据。
扩展插件只实现于特定 Package 提供的扩展接口之上,并且统一定义数据模型(如指标名、指标 Labels),但不干预用户在服务内做自定义的埋点。
扩展插件使用以下 Package 进行埋点:
- metrics:
github.com/prometheus/client_golang
;
- traces:
github.com/open-telemetry/opentelemetry-go
;
- logs: #TODO
接入使用
请阅读具体扩展插件目录下的 README.md
了解如何使用,如 go-contrib/metrics/gin/README.md
提供了对 github.com/gin-gonic/gin
HTTP 框架 metrics 插装的指引。
Metrics 定义
RPC Metrics
接收请求指标
指标名称:
apm_rpc_receive_request_duration_milliseconds_count
apm_rpc_receive_request_duration_milliseconds_sum
apm_rpc_receive_request_duration_milliseconds_bucket
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib
request_protocol
:请求协议,枚举值:http
| grpc
;
request_target
:请求目标,HTTP 请求为域名,gRPC 请求为服务名,示例值:www.baidu.com
| RouteGuide
| unknown
;
request_path
:请求路径,示例值:/api/v1/foo/bar
| /routeguide.RouteGuide/RouteChat
;
grpc_response_status
:RPC 状态码,遵循 GRPC Core: Status codes and their use in gRPC,通常 0
为 OK;
response_code
:HTTP 状态码,遵循 HTTP/1.1: Status Code Definitions,通常 200
为 OK
代码定义:
DefaultRPCReceiveRequestMetric = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: DefaultRPCReceiveRequestMetricName,
Buckets: []float64{0.5, 1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000, 300000, 600000, 1800000, 3600000},
NativeHistogramBucketFactor: 1.4,
NativeHistogramZeroThreshold: 0.5,
NativeHistogramMinResetDuration: 5 * time.Minute,
NativeHistogramMaxZeroThreshold: 50,
NativeHistogramMaxBucketNumber: 20,
}, []string{"sdk", "request_protocol", "request_target", "request_path", "grpc_response_status", "response_code"})
发送请求指标
指标名称:
apm_rpc_send_request_duration_milliseconds_count
apm_rpc_send_request_duration_milliseconds_sum
apm_rpc_send_request_duration_milliseconds_bucket
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib;
request_protocol
:请求协议,枚举值:http | grpc;
request_target
:请求目标,HTTP 请求为域名,gRPC 请求为服务名,示例值:www.baidu.com | RouteGuide | unknown;
request_path
:请求路径,示例值:127.0.0.1:8080/health | /routeguide.RouteGuide/RouteChat;
grpc_response_status
:RPC 状态码,遵循 GRPC Core: Status codes and their use in gRPC,通常 0 为 OK;
response_code
:HTTP 状态码,遵循 HTTP/1.1: Status Code Definitions,通常 200 为 OK。
代码定义:
DefaultRPCSendRequestMetric = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: DefaultRPCSendRequestMetricName,
Buckets: []float64{0.5, 1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000, 300000, 600000, 1800000, 3600000},
NativeHistogramBucketFactor: 1.4,
NativeHistogramZeroThreshold: 0.5,
NativeHistogramMinResetDuration: 5 * time.Minute,
NativeHistogramMaxZeroThreshold: 50,
NativeHistogramMaxBucketNumber: 20,
}, []string{"sdk", "request_protocol", "request_target", "request_path", "grpc_response_status", "response_code"})
备注
- 由于 etcd 同样使用 gRPC 协议通信,并且使用 gRPC Interceptor 埋点采集,因此指标中包含与 etcd 进行通信的数据;
- 对于 gRPC Streaming 类型请求,同样记录在以上指标中,但是 gRPC Streaming 是双向通信(可单向接收、可单向发送、可同时收发),因此在请求耗时上会不同(测试时显著低)于 Unary gRPC 请求响应;
- 对于发送请求指标中的 request_target, gRPC 请求填入的值为 gRPC 请求方法(格式为:
/package.service/method
)中的 service,由 proto 定义,而非 Kubernetes、Istio 中的 Service,它们可能并不相同;
- 对于
request_path
和 request_target
,若无法获取,则填入 unknown
。
Database Metrics
发送请求指标
指标名称:
apm_database_send_request_duration_milliseconds_count
apm_database_send_request_duration_milliseconds_sum
apm_database_send_request_duration_milliseconds_bucket
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib;
database_type
:数据库类型,枚举值:mysql
| mongodb
;
database_addr
:数据库地址,通过 SDK 元数据获取或用户填入,示例值:127.0.0.1:3306
;
response_status
:请求响应状态:枚举值:成功 0
| 错误 1
;
- query_type:语句类型,随不同数据库类型而不同,示例值:
create
| dropDatabase
| ping
;
代码定义:
DefaultDatabaseSendRequestMetric = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: DefaultDatabaseSendRequestMetricName,
Buckets: []float64{1, 2.5, 5, 10, 20, 50, 100, 500, 1000, 2500, 5000, 7500, 10000},
NativeHistogramBucketFactor: 1.4,
NativeHistogramZeroThreshold: 1,
NativeHistogramMinResetDuration: 5 * time.Minute,
NativeHistogramMaxZeroThreshold: 50,
NativeHistogramMaxBucketNumber: 20,
}, []string{"sdk", "database_type", "database_addr", "response_status", "query_type"})
缓存指标
发送请求指标
指标名称:
apm_cache_send_request_duration_milliseconds_count
apm_cache_send_request_duration_milliseconds_sum
apm_cache_send_request_duration_milliseconds_bucket
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib;
cache_type
:数据库类型,枚举值:redis
| memcached
;
cache_addr
:数据库地址,通过 SDK 元数据获取或用户填入,示例值:127.0.0.1:6379
;
response_status
:请求响应状态:枚举值:成功 0
| 错误 1
;
command
:语句类型,随不同缓存类型而不同,示例值: get
| pipeline
;
代码定义:
DefaultCacheRequestMetric = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: DefaultCacheRequestMetricName,
Buckets: []float64{0.25, 0.5, 1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 3000, 5000},
NativeHistogramBucketFactor: 1.4,
NativeHistogramZeroThreshold: 0.1,
NativeHistogramMinResetDuration: 5 * time.Minute,
NativeHistogramMaxZeroThreshold: 10,
NativeHistogramMaxBucketNumber: 20,
}, []string{"sdk", "cache_type", "cache_addr", "command", "response_status"})
消息队列指标
发送消息指标:
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib;
mq_type
:MQ 类型,枚举值:kafka
;
mq_addr
:MQ Broker 地址,通过 SDK 元数据获取或用户填入,示例值:127.0.0.1:9092
;
mq_topic
:MQ Topic,示例值:my_kafka_topic
;
mq_partition
:MQ 分区,若发送时未知则为 unknown
;
代码定义:
DefaultMQSendMsgMetric = prometheus.NewCounterVec(prometheus.CounterOpts{
Name: DefaultMQSendMsgMetricName,
}, []string{"sdk", "mq_type", "mq_addr", "mq_topic", "mq_partition"})
消费消息指标:
包含 Labels:
sdk
:插装 SDK,枚举值见 quwan-sre/observability-go-contrib;
mq_type
:MQ 类型,枚举值:kafka
;
mq_addr
:MQ Broker 地址,通过 SDK 元数据获取或用户填入,示例值:127.0.0.1:9092
;
mq_topic
:MQ Topic,示例值:my_kafka_topic
;
mq_partition
:MQ 分区,示例值:0
| 1
| 2
;
代码定义:
DefaultMQReceiveMsgMetric = prometheus.NewCounterVec(prometheus.CounterOpts{
Name: DefaultMQReceiveMsgMetricName,
}, []string{"sdk", "mq_type", "mq_addr", "mq_topic", "mq_partition"})
Go Packages 支持列表
分类 |
Package |
数据类型 & 稳定性状态 |
HTTP |
github.com/gin-gonic/gin |
alpha: metrics |
HTTP |
github.com/go-resty/resty/v2 |
alpha: metrics |
RPC |
google.golang.org/grpc |
alpha: metrics |
Redis |
github.com/go-redis/redis/v9 |
alpha: metrics |
Kafka |
github.com/Shopify/sarama |
alpha: metrics |
MongoDB |
go.mongodb.org/mongo-driver |
alpha: metrics |
etcd |
go.etcd.io/etcd/client/v3 |
alpha: metrics |