可观测性
3 分钟阅读
简要概述
用于链路跟踪、指标数据采集上报。
配置示例
最小化配置
# 分布式链路追踪
#observables:
# enable: true
可不做任何配置,默认开启可观测性指标服务,既直接对外暴露 “/metrics” 地址。
导出所有项
# 可观测性配置
observables:
# 全局是否启动可观测性,默认启用
enable: true
# 遥测数据(指标、链路)的个性行为配置
telemetry:
# 指标数据
metrics:
# 为所有自定义指标添加前缀
namespace: default
# 性能数据上报频率,单位:秒
push_interval: 60
# 配置启用的 exporters 插件
exporter_enable:
otlp: false
otlphttp: false
logging: true
prometheus: true
# 链路数据
traces:
# 给定一个 0 至 1 之间的分数决定采样频率
sample_ratio: 1
# 在网关上记录 http 请求与响应体内容,仅当为 json 结构体有效
log_fields:
http_request: true
http_response: true
# 配置启用的 exporters 插件
exporter_enable:
otlp: true
otlphttp: true
logging: true
prometheus: false
# 过滤 http 或 grpc 请求的链路数据上报
filters:
- url_path: "/api/demo"
method: POST
- method: Demo
# 遥测数据(指标、链路)的上报输出配置
exporters:
# 通过 grpc 上报数据
otlp:
endpoint: "http://127.0.0.1:4317"
headers:
Authentication: token
# 通过 http 上报数据,避免与 oltp 配置多个,否则链路会重复
#otlphttp:
# endpoint: "http://127.0.0.1:4318"
# traces_url_path: ""
# metrics_url_path: ""
# headers:
# Authentication: token
# 对外暴露 prometheus 风格的 http url 地址
prometheus:
metrics_url_path: "/metrics"
# 指标与链路分布写入本地文件路径
logging:
pretty_print: true
traces_file_path: "/tmp/traces.log"
metrics_file_path: "/tmp/metrics.log"
参数说明
ObservablesConfig
名称 | 类型 | 说明 |
---|---|---|
enable | bool | 全局是否启动可观测性,默认启用 |
telemetry | TelemetryConfig | 遥测数据(指标、链路)的个性行为配置 |
exporters | ExporterConfig | 遥测数据(指标、链路)的上报输出配置 |
TelemetryConfig
名称 | 类型 | 说明 |
---|---|---|
metrics | TelemetryMetric | 指标数据配置 |
traces | TelemetryTrace | 链路跟踪配置 |
TelemetryMetric
名称 | 类型 | 说明 |
---|---|---|
namespace | string | 命名空间,为所有暴露的指标添加前缀 |
push_interval | int | 性能数据上报频率,默认1分钟,单位:秒 |
exporter_enable | ExporterEnable | 是否启用 Exporters 配置下的 otel otelhttp logging prometheus |
ExporterEnable
名称 | 类型 | 说明 |
---|---|---|
otlp | bool | 指标或链路是否启用通道 observables.exporters.otlp 上报数据 |
otlphttp | bool | 指标或链路是否启用通道 observables.exporters.otlphttp 上报数据 |
prometheus | bool | 指标是否启用通道 observables.exporters.prometheus 输出数据 |
logging | bool | 指标或链路是否启用通道 observables.exporters.logging 输出数据 |
TelemetryTrace
名称 | 类型 | 说明 |
---|---|---|
sample_ratio | float64 | 给定一个 0 至 1 之间的分数决定采样频率 |
log_fields | LogFields | 记录特殊字段,默认不开启 |
filters | Filters | 过滤器,用于过滤不需要追踪的请求 |
exporter_enable | ExporterEnable | 是否启用 Exporters 配置下的 otel otelhttp logging prometheus |
- LogFields
名称 | 类型 | 说明 |
---|---|---|
http_request | bool | 是否记录请求体 |
http_response | bool | 是否记录响应体 |
- Filters
名称 | 类型 | 说明 |
---|---|---|
method | string | http method 或者 grpc method |
url_path | string | http url |
ExporterConfig
名称 | 类型 | 说明 |
---|---|---|
otlp | OTLPGRPCConfig | 使用 otlp grpc 协议上报数据 |
otlphttp | OTLPHTTPConfig | 使用 otlp http 协议上报数据 |
prometheus | Prometheus | 使用 prometheus http 服务输出数据 |
logging | Logging | 使用本地文件输出数据 |
OTLPGRPCConfig
名称 | 类型 | 说明 |
---|---|---|
endpoint | string | 服务端地址 |
headers | map[string]string | 请求头,有些认证需在这里添加,如:Authentication |
OTLPHTTPConfig
名称 | 类型 | 说明 |
---|---|---|
endpoint | string | 服务端地址 |
headers | map[string]string | 有些认证需在这里添加,如:Authentication |
traces_url_path | string | 链路上报接口地址,默认为:/v1/traces |
metrics_url_path | string | 指标上报接口节点,默认为:/v1/metrics |
Prometheus
名称 | 类型 | 说明 |
---|---|---|
metrics_url_path | string | 对外暴露应用指标的 http url 地址,默认为:/metrics |
Logging
名称 | 类型 | 说明 |
---|---|---|
pretty_print | bool | 是否格式化 json 输出 |
metrics_file_path | string | 指标输出文件,为空则不启用,配置 “stdout” 则输出终端 |
traces_file_path | string | 链路输出文件,为空则不启用,配置 “stdout” 则输出终端 |
使用场景
对接阿里云服务
- 服务端接收数据
购买 可观测链路 OpenTelemetry 版 服务。
- 客户端上报数据
# 可观测性配置
observables:
exporters:
otlp:
endpoint: http://tracing-analysis-dc-hz.aliyuncs.com:8090
headers:
Authentication: "配置云平台获取的 token"
- 监控与告警展示
登录后台 https://tracing.console.aliyun.com 查看。
对接腾讯云服务
- 服务端接收数据
购买 应用性能监控 服务。
- 客户端上报数据
通过设置环境变量 OTEL_RESOURCE_ATTRIBUTES=token=xxxxxxxxx
设置授权,Token 在云服务后台上可找到。
# 可观测性配置
observables:
exporters:
otlp:
endpoint: http://ap-guangzhou.apm.tencentcs.com:4317
- 监控与告警展示
登录后台 https://console.cloud.tencent.com/apm/monitor/system 查看。
对接 honeycomb 服务
- 服务端接收数据
购买 Honeycomb 服务。
- 客户端上报数据
# 可观测性配置
observables:
exporters:
otlp:
endpoint: https://api.honeycomb.io:443
headers:
"x-honeycomb-team": "配置云平台获取的 token"
- 监控与告警展示
登录后台 https://ui.honeycomb.io/ 查看。
对接私有 jaeger 服务
- 服务端接收数据
在本地启动 jaeger all-in-one 容器
docker run --rm --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one:1.50
这里端口 4317 为 grpc 协议,4318 为 http 协议,16686 为 jaeger ui 服务,all-in-one 仅用于开发环境,生产环境需各组件单独部署以便实现高可用。
- 客户端上报数据
配置服务使用 otlp 使用上报链路数据
# 可观测性配置
observables:
exporters:
otlp:
endpoint: http://127.0.0.1:4317
- 监控与告警展示
访问 http://localhost:16686 查看。
过滤特定请求的链路上报
# 可观测性配置
observables:
exporters:
......
telemetry:
traces:
filters:
- url_path: "/api/test"
method: POST
- method: Test
这里将会过滤本服务请求为 http method 为 POST 且地址为 “/api/test” 或 grpc 方法为 “Test” 的链路数据。
更改对外暴露的 http prometheus 性能数据地址
# 可观测性配置
observables:
exporters:
prometheus:
metrics_url_path: /v2/metrics
这个时候需通过接口 “/v2/metrics” 来获取应用的性能数据。
自定义 http 接口如何实现跟踪
默认仅针对 grpc-gateway 至 grpc 转发才会捕获链路数据上报。
如果用户在 handler/private.go
中的 privateHTTPHandle
方法添加了自定义 http 接口,如:
func (m *Microservice) privateHTTPHandle(mux *http.ServeMux) error {
testHandler := func(w http.ResponseWriter, r *http.Request) {
_, _ = fmt.Fprintf(w, "test")
}
// 访问 /favicon.ico 不会产生链路数据
mux.HandleFunc("/favicon.ico", func(w http.ResponseWriter, r *http.Request) {
_, _ = fmt.Fprintf(w, "")
})
// 访问 /test 会产生链路数据
mux.Handle("/test", m.baseCfg.HTTPHandlerFunc(testHandler))
return nil
}
这里定义了两个接口 /favicon.ico
(不会产生链路数据) 与 /test
(会产生链路数据),如需捕获数据,可通过内置函数 m.baseCfg.HTTPHandlerFunc
或 m.baseCfg.HTTPHandler
实现。