105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
# ShardingSphere Agent
|
|
|
|
ShardingSphere-Agent module provides an observable framework for ShardingSphere, which is implemented based on Java Agent.
|
|
|
|
## Features
|
|
|
|
### Logging
|
|
|
|
The logging plugin uses to record logs of ShardingSphere.
|
|
Supports for File.
|
|
|
|
### Metrics
|
|
|
|
The metrics plugin uses to collect and expose monitoring metrics.
|
|
Supports for prometheus.
|
|
|
|
### Tracing
|
|
|
|
The tracing plugin uses to obtain the link trace information of SQL parsing and SQL execution.
|
|
Supports for OpenTelemetry.
|
|
|
|
## How To Build
|
|
|
|
```shell
|
|
git clone https://github.com/apache/shardingsphere.git
|
|
cd shardingsphere
|
|
./mvnw clean install -Prelease
|
|
```
|
|
|
|
Artifact is `distribution/agent/target/apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz`
|
|
|
|
## Quick Start
|
|
|
|
* `shardingsphere-agent-{latest.release.version}.jar` is the agent startup jar.
|
|
* `conf/agent.yaml` is used to configure and enable plugins.
|
|
|
|
### Quick Start with Proxy
|
|
|
|
Add the agent to the Proxy directory, as follows:
|
|
|
|
```shell
|
|
apache-shardingsphere-{latest.release.version}-shardingsphere-proxy-bin/agent/shardingsphere-agent.jar
|
|
```
|
|
|
|
Start agent with `-g` option by bin/start.sh
|
|
```shell
|
|
sh start.sh -g
|
|
|
|
# following command also works
|
|
sh start.sh --agent
|
|
```
|
|
|
|
### Quick Start with JDBC
|
|
|
|
When using ShardingSphere-JDBC, you need to add javaagent configuration in the startup command, as follows:
|
|
|
|
```shell
|
|
java -javaagent:/xx/xx/shardingsphere-agent-{latest.release.version}.jar -jar project-using-shardingsphere-jdbc.jar
|
|
```
|
|
|
|
## Install Customized Plugins
|
|
|
|
### Usage of lib and plugins folders
|
|
|
|
* `lib` contains dependencies common to plugins.
|
|
* `plugins` contains all plugins.
|
|
|
|
### Extend via SPI PluginLifecycleService
|
|
|
|
`PluginLifecycleService` is the plugin service definition interface, used to start the plugin service.
|
|
Custom plugins need to implement this interface.
|
|
|
|
### Configure advisors.yaml
|
|
|
|
`advisors.yaml` is used to define interception points. The format is as follows:
|
|
|
|
```yaml
|
|
advisors:
|
|
- target: xxx.TargetClass # class that need interception enhancements
|
|
advice: xxx.XXXAdvice # enhanced class
|
|
pointcuts: # intercept methods
|
|
- name: foo # method name
|
|
type: method # intercept type. configuring "method" when intercepting the method, configuring "constructor" when intercepting the constructor
|
|
params: # method parameters, just satisfy the unique identification method
|
|
- index: 0 # parameter index
|
|
type: java.lang.String # parameter type
|
|
```
|
|
|
|
The file location is as follows:
|
|
|
|
* Proxy: META-INF/conf/{plugin-type}-proxy-advisors.yaml
|
|
* JDBC: META-INF/conf/{plugin-type}-jdbc-advisors.yaml
|
|
|
|
### Configure more metrics collector into metrics.yaml
|
|
|
|
`metrics.yaml` is the metrics definition file. The format is as follows.
|
|
|
|
```yaml
|
|
metrics:
|
|
- id: xxx_id # metric id
|
|
type: COUNTER # metric type, COUNTER、GAUGE、HISTOGRAM、SUMMARY
|
|
name: xxx_name # metric name
|
|
help: xxx help # metric help
|
|
```
|