可观察性

Agent

源码编译

从 Github 下载 Apache ShardingSphere 源码,对源码进行编译,操作命令如下。

  1. git clone --depth 1 https://github.com/apache/shardingsphere.git
  2. cd shardingsphere
  3. mvn clean install -DskipITs -DskipTests -Prelease

agent 包输出目录为 distribution/agent/target/apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz

目录说明

创建 agent 目录,解压 agent 二进制包到 agent 目录。

  1. mkdir agent
  2. tar -zxvf apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz -C agent
  3. cd agent
  4. tree
  5. ├── LICENSE
  6. ├── NOTICE
  7. ├── conf
  8. └── agent.yaml
  9. ├── plugins
  10. ├── lib
  11. ├── shardingsphere-agent-metrics-core-${latest.release.version}.jar
  12. └── shardingsphere-agent-plugin-core-${latest.release.version}.jar
  13. ├── logging
  14. └── shardingsphere-agent-logging-file-${latest.release.version}.jar
  15. ├── metrics
  16. └── shardingsphere-agent-metrics-prometheus-${latest.release.version}.jar
  17. └── tracing
  18. ├── shardingsphere-agent-tracing-opentelemetry-${latest.release.version}.jar
  19. └── shardingsphere-agent-${latest.release.version}.jar

Agent 日志输出位置在 agent/logs/stdout.log

配置说明

conf/agent.yaml 用于管理 agent 配置。内置插件包括 File、Prometheus、OpenTelemetry。

  1. plugins:
  2. # logging:
  3. # File:
  4. # props:
  5. # level: "INFO"
  6. # metrics:
  7. # Prometheus:
  8. # host: "localhost"
  9. # port: 9090
  10. # props:
  11. # jvm-information-collector-enabled: "true"
  12. # tracing:
  13. # OpenTelemetry:
  14. # props:
  15. # otel.service.name: "shardingsphere"
  16. # otel.traces.exporter: "jaeger"
  17. # otel.exporter.otlp.traces.endpoint: "http://localhost:14250"
  18. # otel.traces.sampler: "always_on"

插件说明

File

目前 File 插件只有构建元数据耗时日志输出,暂无其他日志输出。

Prometheus

用于暴露监控指标

  • 参数说明
名称说明
host主机
port端口
jvm-information-collector-enabled是否采集 JVM 指标信息

OpenTelemetry

OpenTelemetry 可以导出 tracing 数据到 Jaeger,Zipkin。

  • 参数说明
名称说明
otel.service.name服务名称
otel.traces.exportertraces exporter
otel.exporter.otlp.traces.endpointtraces endpoint
otel.traces.samplertraces sampler

参数参考 OpenTelemetry SDK Autoconfigure

ShardingSphere-Proxy 中使用

通过非容器环境使用

  • 编辑启动脚本

配置 shardingsphere-agent-${latest.release.version}.jar 的绝对路径到 ShardingSphere-Proxy 的 start.sh 启动脚本中,请注意配置自己对应的绝对路径。

  1. nohup java ${JAVA_OPTS} ${JAVA_MEM_OPTS} \
  2. -javaagent:/xxxxx/agent/shardingsphere-agent-${latest.release.version}.jar \
  3. -classpath ${CLASS_PATH} ${MAIN_CLASS} >> ${STDOUT_FILE} 2>&1 &
  • 启动 ShardingSphere-Proxy
  1. bin/start.sh

正常启动后,可以在 ShardingSphere-Proxy 日志中找到 plugin 的加载信息,访问 Proxy 后,可以通过配置的监控地址查看到 MetricTracing 的数据。

通过容器环境使用

  • 假设本地已完成如下的对应配置。

    • 包含 ShardingSphere-Agent 二进制包解压后的所有文件的文件夹 ./custom/agent/
    • 包含 server.yaml 等 ShardingSphere-Proxy 的配置文件的文件夹为 ./custom/conf/
  • 此时可通过环境变量 JVM_OPT 来配置 ShardingSphere-Agent 的使用。 以在 Docker Compose 环境下启动为例,合理的 docker-compose.yml 示例如下。
  1. version: "3.8"
  2. services:
  3. apache-shardingsphere-proxy:
  4. image: apache/shardingsphere-proxy:latest
  5. environment:
  6. JVM_OPTS: "-javaagent:/agent/shardingsphere-agent-${latest.release.version}.jar"
  7. PORT: 3308
  8. volumes:
  9. - ./custom/agent/:/agent/
  10. - ./custom/conf/:/opt/shardingsphere-proxy/conf/
  11. ports:
  12. - "13308:3308"

Metrics

指标名称指标类型指标描述
build_infoGAUGE构建信息
parsed_sql_totalCOUNTER按类型(INSERT、UPDATE、DELETE、SELECT、DDL、DCL、DAL、TCL、RQL、RDL、RAL、RUL)分类的解析总数
routed_sql_totalCOUNTER按类型(INSERT、UPDATE、DELETE、SELECT)分类的路由总数
routed_result_totalCOUNTER路由结果总数(数据源路由结果、表路由结果)
proxy_stateGAUGEShardingSphere-Proxy 状态信息。0 表示正常状态;1 表示熔断状态;2 锁定状态
proxy_meta_data_infoGAUGEShardingSphere-Proxy 元数据信息,database_count:逻辑库数量,storage_unit_count:存储节点数量
proxy_current_connectionsGAUGEShardingSphere-Proxy 的当前连接数
proxy_requests_totalCOUNTERShardingSphere-Proxy 的接受请求总数
proxy_transactions_totalCOUNTERShardingSphere-Proxy 的事务总数,按 commit,rollback 分类
proxy_execute_latency_millisHISTOGRAMShardingSphere-Proxy 的执行耗时毫秒直方图
proxy_execute_errors_totalCOUNTERShardingSphere-Proxy 的执行异常总数