使用规范

源码编译

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

  1. git clone --depth 1 https://github.com/apache/shardingsphere.git
  2. cd shardingsphere
  3. mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests -Prelease

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

agent 配置

  • 目录说明

创建 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. .
  6. ├── conf
  7. │   ├── agent.yaml
  8. │   └── logback.xml
  9. ├── plugins
  10. │   ├── shardingsphere-agent-logging-base-${latest.release.version}.jar
  11. │   ├── shardingsphere-agent-metrics-prometheus-${latest.release.version}.jar
  12. │   ├── shardingsphere-agent-tracing-jaeger-${latest.release.version}.jar
  13. │   ├── shardingsphere-agent-tracing-opentelemetry-${latest.release.version}.jar
  14. │   ├── shardingsphere-agent-tracing-opentracing-${latest.release.version}.jar
  15. │   └── shardingsphere-agent-tracing-zipkin-${latest.release.version}.jar
  16. └── shardingsphere-agent.jar
  • 配置说明

agent.yaml 是配置文件，插件有 Jaeger、OpenTracing、Zipkin、OpenTelemetry、Logging、Prometheus。 如果需要开启插件时，只需要注释掉 ignoredPluginNames 中对应的插件即可。

  1. applicationName: shardingsphere-agent
  2. ignoredPluginNames:
  3.   - Jaeger
  4.   - OpenTracing
  5.   - Zipkin
  6.   - OpenTelemetry
  7.   - Logging
  8.   - Prometheus
  10. plugins:
  11.   Prometheus:
  12.     host:  "localhost"
  13.     port: 9090
  14.     props:
  15.       JVM_INFORMATION_COLLECTOR_ENABLED : "true"
  16.   Jaeger:
  17.     host: "localhost"
  18.     port: 5775
  19.     props:
  20.       SERVICE_NAME: "shardingsphere-agent"
  21.       JAEGER_SAMPLER_TYPE: "const"
  22.       JAEGER_SAMPLER_PARAM: "1"
  23.   Zipkin:
  24.     host: "localhost"
  25.     port: 9411
  26.     props:
  27.       SERVICE_NAME: "shardingsphere-agent"
  28.       URL_VERSION: "/api/v2/spans"
  29.       SAMPLER_TYPE: "const"
  30.       SAMPLER_PARAM: "1"
  31.   OpenTracing:
  32.     props:
  33.       OPENTRACING_TRACER_CLASS_NAME: "org.apache.skywalking.apm.toolkit.opentracing.SkywalkingTracer"
  34.   OpenTelemetry:
  35.     props:
  36.       otel.resource.attributes: "service.name=shardingsphere-agent"
  37.       otel.traces.exporter: "zipkin"
  38.   Logging:
  39.     props:
  40.       LEVEL: "INFO"
  • 参数说明；
名称说明取值范围默认值
JVM_INFORMATION_COLLECTOR_ENABLED是否开启 JVM 采集器true、falsetrue
SERVICE_NAME链路跟踪的服务名称自定义shardingsphere-agent
JAEGER_SAMPLER_TYPEJaeger 采样率类型const、probabilistic、ratelimiting、remoteconst
JAEGER_SAMPLER_PARAMJaeger 采样率参数const：0、1，probabilistic：0.0 - 1.0，ratelimiting：> 0，自定义每秒采集数量，remote：需要自定义配置远程采样率管理服务地址，JAEGER_SAMPLER_MANAGER_HOST_PORT1（const 类型）
SAMPLER_TYPEZipkin 采样率类型const、counting、ratelimiting、boundaryconst
SAMPLER_PARAMZipkin 采样率参数const： 0、1，counting：0.01 - 1.0，ratelimiting：> 0，自定义每秒采集数量，boundary: 0.0001 - 1.01（const 类型）
otel.resource.attributesopentelemetry 资源属性字符串键值对（,分割）service.name=shardingsphere-agent
otel.traces.exporterTracing expoterzipkin、jaegerzipkin
otel.traces.sampleropentelemetry 采样率类型always_on、always_off、traceidratioalways_on
otel.traces.sampler.argopentelemetry 采样率参数traceidratio：0.0 - 1.01.0

ShardingSphere-Proxy 中使用

  • 启动脚本

    配置 shardingsphere-agent.jar 的绝对路径到 ShardingSphere-Proxy 的 start.sh 启动脚本中，请注意配置自己对应的绝对路径。

  1. nohup java ${JAVA_OPTS} ${JAVA_MEM_OPTS} \
  2. -javaagent:/xxxxx/agent/shardingsphere-agent.jar \
  3. -classpath ${CLASS_PATH} ${MAIN_CLASS} >> ${STDOUT_FILE} 2>&1 &
  • 启动插件

通过改造后的 ShardingSphere-Proxy 的启动脚本启动。

  1. bin/start.sh

正常启动可以在对应的 ShardingSphere-Proxy 日志查看到 plugin 的启动日志，访问 Proxy 后，可以通过配置的地址查看到 Metric 和 Tracing 的数据。