可观测性

简要概述

用于链路跟踪、指标数据采集上报。

配置示例

最小化配置

# 分布式链路追踪
#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.HTTPHandlerFuncm.baseCfg.HTTPHandler 实现。