Observability

Agent

Compile source code

Download Apache ShardingSphere from GitHub,Then compile.

  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

Artifact is distribution/agent/target/apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz

Directory structure

Create agent directory, and unzip agent distribution package to the directory.

  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-tracing-opentracing-${latest.release.version}.jar
  20. └── shardingsphere-agent-${latest.release.version}.jar

Agent log output location is agent/logs/stdout.log.

Configuration

conf/agent.yaml is used to manage agent configuration. Built-in plugins include File, Prometheus, OpenTelemetry, OpenTracing.

  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"
  19. # OpenTracing:
  20. # props:
  21. # opentracing-tracer-class-name: "org.apache.skywalking.apm.toolkit.opentracing.SkywalkingTracer"

Plugin description

File

Currently, the File plugin only outputs the time-consuming log output of building metadata, and has no other log output for the time being.

Prometheus

Used for exposure monitoring metrics.

  • Parameter description
NameDescription
hosthost IP
portport
jvm-information-collector-enabledwhether to collect JVM indicator information

OpenTelemetry

OpenTelemetry can export tracing data to Jaeger, Zipkin.

  • Parameter description
NameDescription
otel.service.nameservice name
otel.traces.exportertraces exporter
otel.exporter.otlp.traces.endpointtraces endpoint
otel.traces.samplertraces sampler

Parameter reference OpenTelemetry SDK Autoconfigure

Usage in ShardingSphere-Proxy

Using via a non-container environment

  • Edit the startup script

Configure the absolute path of shardingsphere-agent-${latest.release.version}.jar to the start.sh startup script of shardingsphere proxy.

  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 &
  • Start ShardingSphere-Proxy
  1. bin/start.sh

After startup, you can find the plugin info in the log of ShardingSphere-Proxy, Metric and Tracing data can be viewed through the configured monitoring address.

Use via container environment

  • Assume that the following corresponding configurations have been completed locally.

    • Folder ./custom/agent/ that contains all files after unpacking ShardingSphere-Agent binary package
    • The folder containing the configuration files of ShardingSphere-Proxy such as server.yaml is ./custom/conf/
  • At this point, the use of ShardingSphere-Agent can be configured through the environment variable JVM_OPT. Taking starting in the Docker Compose environment as an example, a reasonable docker-compose.yml example is as follows.
  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

NameTypeDescription
build_infoGAUGEBuild information
parsed_sql_totalCOUNTERTotal count of parsed by type (INSERT, UPDATE, DELETE, SELECT, DDL, DCL, DAL, TCL, RQL, RDL, RAL, RUL)
routed_sql_totalCOUNTERTotal count of routed by type (INSERT, UPDATE, DELETE, SELECT)
routed_result_totalCOUNTERTotal count of routed result (data source routed, table routed)
proxy_stateGAUGEStatus information of ShardingSphere-Proxy. 0 is OK; 1 is CIRCUIT BREAK; 2 is LOCK
proxy_meta_data_infoGAUGEMeta data information of ShardingSphere-Proxy. database_count is logic number of databases; storage_unit_count is number of storage units
proxy_current_connectionsGAUGECurrent connections of ShardingSphere-Proxy
proxy_requests_totalCOUNTERTotal requests of ShardingSphere-Proxy
proxy_transactions_totalCOUNTERTotal transactions of ShardingSphere-Proxy, classify by commit, rollback
proxy_execute_latency_millisHISTOGRAMExecute latency millis histogram of ShardingSphere-Proxy
proxy_execute_errors_totalCOUNTERTotal executor errors of ShardingSphere-Proxy