This is an automated email from the ASF dual-hosted git repository.
sunnianjun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 3dc320a3922 Add README.md for agent (#23289)
3dc320a3922 is described below
commit 3dc320a39220fd0c201965200b241969d59beedb
Author: jiangML <[email protected]>
AuthorDate: Tue Jan 3 15:47:11 2023 +0800
Add README.md for agent (#23289)
* add README for agent
* update README of agent
* optimize README of agent
* format README of agent
---
agent/README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 81 insertions(+)
diff --git a/agent/README.md b/agent/README.md
new file mode 100644
index 00000000000..76361ac4004
--- /dev/null
+++ b/agent/README.md
@@ -0,0 +1,81 @@
+
+## Features
+
+ShardingSphere-Agent module provides an observable framework for
ShardingSphere, which is implemented based on Java Agent.
+
+### Usage of logging
+The logging plugin is used to record logs of ShardingSphere.
+
+### Usage of metrics
+The metrics plugin is used to collect and expose monitoring metrics, and
supports Prometheus by default.
+
+### Usage of tracing
+The tracing plugin is used to obtain the link trace information of SQL parsing
and SQL execution. Supports for Jaeger, OpenTelemetry, OpenTracing and Zipkin.
+
+## How To Build
+```shell
+git clone https://github.com/apache/shardingsphere.git
+
+cd shardingsphere
+
+./mvnw clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true
-Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests -Prelease
+```
+Artifact:
+```shell
+agent/distribution/target/apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz
# Binary package of ShardingSphere-Agent
+```
+
+## 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 javaagent configuration in the Proxy startup script, as follows.
+
+```shell
+nohup $JAVA ${JAVA_OPTS} ${JAVA_MEM_OPTS}
-javaagent:/xx/xx/shardingsphere-agent-{latest.release.version}.jar -classpath
${CLASS_PATH} ${MAIN_CLASS} >> ${STDOUT_FILE} 2>&1 &
+```
+
+### 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 PluginBootService
+`PluginBootService` 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: org.apache.shardingsphere.mode.metadata.MetaDataContextsFactory #
class that need interception enhancements
+ advice:
org.apache.shardingsphere.agent.plugin.metrics.core.advice.MetaDataContextsFactoryAdvice
# enhanced class
+ pointcuts: # intercept methods
+ - name: create # 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: 3 # parameter index
+ type: java.util.Map # 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: proxy_request_total # metric id
+ type: COUNTER # metric type, COUNTER、GAUGE、HISTOGRAM、SUMMARY
+ name: proxy_request_total # metric name
+ help: the shardingsphere proxy request total # metric help
+```
