可观测性

简要概述

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

配置示例

最小化配置

# 分布式链路追踪
#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

名称类型说明
enablebool全局是否启动可观测性,默认启用
telemetryTelemetryConfig遥测数据(指标、链路)的个性行为配置
exportersExporterConfig遥测数据(指标、链路)的上报输出配置

TelemetryConfig

名称类型说明
metricsTelemetryMetric指标数据配置
tracesTelemetryTrace链路跟踪配置

TelemetryMetric

名称类型说明
namespacestring命名空间,为所有暴露的指标添加前缀
push_intervalint性能数据上报频率,默认1分钟,单位:秒
exporter_enableExporterEnable是否启用 Exporters 配置下的 otel otelhttp logging prometheus

ExporterEnable

名称类型说明
otlpbool指标或链路是否启用通道 observables.exporters.otlp 上报数据
otlphttpbool指标或链路是否启用通道 observables.exporters.otlphttp 上报数据
prometheusbool指标是否启用通道 observables.exporters.prometheus 输出数据
loggingbool指标或链路是否启用通道 observables.exporters.logging 输出数据

TelemetryTrace

名称类型说明
sample_ratio*float64给定一个 0 至 1 之间的分数决定采样频率,缺省为 1(全采样)
log_fieldsLogFields记录特殊字段,默认不开启
filtersFilters过滤器,用于过滤不需要追踪的请求
exporter_enableExporterEnable是否启用 Exporters 配置下的 otel otelhttp logging prometheus
  • LogFields
名称类型说明
http_requestbool是否记录请求体
http_responsebool是否记录响应体
  • Filters
名称类型说明
methodstringhttp method 或者 grpc method
url_pathstringhttp url

ExportersConfig

名称类型说明
otlpOTLPGRPCConfig使用 otlp grpc 协议上报数据
otlphttpOTLPHTTPConfig使用 otlp http 协议上报数据
prometheusPrometheus使用 prometheus http 服务输出数据
loggingLogging使用本地文件输出数据

OTLPGRPCConfig

名称类型说明
endpointstring服务端地址
headersmap[string]string请求头,有些认证需在这里添加,如:Authentication

OTLPHTTPConfig

名称类型说明
endpointstring服务端地址
headersmap[string]string有些认证需在这里添加,如:Authentication
traces_url_pathstring链路上报接口地址,默认为:/v1/traces
metrics_url_pathstring指标上报接口节点,默认为:/v1/metrics
logs_url_pathstring日志上报接口地址(预留字段,当前版本暂无日志导出器消费)

Prometheus

名称类型说明
metrics_url_pathstring对外暴露应用指标的 http url 地址,默认为:/metrics

Logging

名称类型说明
pretty_printbool是否格式化 json 输出
metrics_file_pathstring指标输出文件,为空则不启用,配置 “stdout” 则输出终端
traces_file_pathstring链路输出文件,为空则不启用,配置 “stdout” 则输出终端

使用场景

对接阿里云服务

  • 服务端接收数据

购买 可观测链路 OpenTelemetry 版 服务。

  • 客户端上报数据

使用 gRPC 上报

# 可观测性配置
observables:
  exporters:
    otlp:
      endpoint: http://tracing-analysis-dc-hz.aliyuncs.com:8090
      headers:
        Authentication: "配置云平台获取的 token"

使用 HTTP 上报

# 可观测性配置
observables:
  enable: true
  exporters:
    otlphttp:
      endpoint: http://tracing-analysis-dc-hz.aliyuncs.com
      traces_url_path: "/xyz@xyz/api/otlp/traces"
      metrics_url_path: "/xyz@xyz/api/otlp/metrics"
  • 监控与告警展示

登录后台 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 实现。

进程全局状态与退出

当前初始化涉及 Prometheus 全局注册及 OpenTelemetry 全局 provider。同一进程内重复初始化多个 LocalConfig 时应验证注册冲突和 provider 归属,不能假设每个微单体模块拥有独立全局遥测实例。

关闭遥测并不保证业务数据库、缓存和自定义后台任务均已释放。应在部署验收中检查日志、链路导出、指标与 SIGTERM,参见启动与部署检查。