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 -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-${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.

  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"

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-JDBC

  • 1 The SpringBoot project ready to integrate ShardingSphere-JDBC, test-project.jar
  • 2 Startup project
  1. java -javaagent:/agent/shardingsphere-agent-${latest.release.version}.jar -jar test-project.jar
  • 3 Access to started service
  • 4 Check whether the corresponding plug-in is effective

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)
jdbc_stateGAUGEStatus information of ShardingSphere-JDBC. 0 is OK; 1 is CIRCUIT BREAK; 2 is LOCK
jdbc_meta_data_infoGAUGEMeta data information of ShardingSphere-JDBC
jdbc_statement_execute_totalGAUGETotal number of statements executed
jdbc_statement_execute_errors_totalGAUGETotal number of statement execution errors
jdbc_statement_execute_latency_millisHISTOGRAMStatement execution latency
jdbc_transactions_totalGAUGETotal number of transactions, classify by commit and rollback