This is an automated email from the ASF dual-hosted git repository.
jianglongtao 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 a5fb296987f add agent doc about JDBC (#24503)
a5fb296987f is described below
commit a5fb296987fa7a0d416a602b1a0b581176c93df9
Author: jiangML <[email protected]>
AuthorDate: Wed Mar 8 18:27:10 2023 +0800
add agent doc about JDBC (#24503)
* add agent doc for JDBC
* update agent doc of Proxy
* update doc
---
.../shardingsphere-jdbc/observability/_index.cn.md | 117 ++++++++++++++++++++
.../shardingsphere-jdbc/observability/_index.en.md | 118 +++++++++++++++++++++
.../observability/_index.cn.md | 6 +-
.../observability/_index.en.md | 6 +-
4 files changed, 241 insertions(+), 6 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.cn.md
new file mode 100644
index 00000000000..befb856d874
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.cn.md
@@ -0,0 +1,117 @@
++++
+title = "可观察性"
+weight = 7
++++
+
+## Agent
+
+### 源码编译
+
+从 Github 下载 Apache ShardingSphere 源码，对源码进行编译，操作命令如下。
+
+```shell
+git clone --depth 1 https://github.com/apache/shardingsphere.git
+cd shardingsphere
+mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true
-Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests -Prelease
+```
+agent 包输出目录为
distribution/agent/target/apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz
+
+### 目录说明
+
+创建 agent 目录，解压 agent 二进制包到 agent 目录。
+
+```shell
+mkdir agent
+tar -zxvf
apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz
-C agent
+cd agent
+tree
+├── LICENSE
+├── NOTICE
+├── conf
+│ └── agent.yaml
+├── plugins
+│ ├── lib
+│ │ ├── shardingsphere-agent-metrics-core-${latest.release.version}.jar
+│ │ └── shardingsphere-agent-plugin-core-${latest.release.version}.jar
+│ ├── logging
+│ │ └── shardingsphere-agent-logging-file-${latest.release.version}.jar
+│ ├── metrics
+│ │ └──
shardingsphere-agent-metrics-prometheus-${latest.release.version}.jar
+│ └── tracing
+│ ├──
shardingsphere-agent-tracing-opentelemetry-${latest.release.version}.jar
+│ └──
shardingsphere-agent-tracing-opentracing-${latest.release.version}.jar
+└── shardingsphere-agent-${latest.release.version}.jar
+```
+Agent 日志输出位置在 `agent/logs/stdout.log`。
+
+### 配置说明
+
+`conf/agent.yaml` 用于管理 agent 配置。内置插件包括
File、Prometheus、OpenTelemetry、OpenTracing。
+
+```yaml
+plugins:
+# logging:
+# File:
+# props:
+# level: "INFO"
+# metrics:
+# Prometheus:
+# host: "localhost"
+# port: 9090
+# props:
+# jvm-information-collector-enabled: "true"
+# tracing:
+# OpenTelemetry:
+# props:
+# otel.service.name: "shardingsphere"
+# otel.traces.exporter: "jaeger"
+# otel.exporter.otlp.traces.endpoint: "http://localhost:14250";
+# otel.traces.sampler: "always_on"
+# OpenTracing:
+# props:
+# opentracing-tracer-class-name:
"org.apache.skywalking.apm.toolkit.opentracing.SkywalkingTracer"
+```
+
+### 插件说明
+
+#### File
+
+目前 File 插件只有构建元数据耗时日志输出，暂无其他日志输出。
+
+#### Prometheus
+
+用于暴露监控指标
+
+* 参数说明
+
+| 名称 | 说明 |
+|-----------------------------------|----------------------|
+| host | 主机 |
+| port | 端口 |
+| jvm-information-collector-enabled | 是否采集 JVM 指标信息 |
+
+
+## ShardingSphere-JDBC 使用
+
++ 1 准备好已集成 `ShardingSphere-JDBC` 的 `SpringBoot` 项目，test-project.jar
++ 2 启动项目
+```shell
+java -javaagent:/agent/shardingsphere-agent-${latest.release.version}.jar -jar
test-project.jar
+```
++ 3 访问启动的服务
++ 4 查看对应的插件是否生效
+
+## Metrics
+
+| 指标名称 | 指标类型 | 指标描述
|
+| :--------------------------------------- | :------------------
|:-----------------------------------------------------------------------------------------------|
+| build_info | GAUGE | 构建信息
|
+| parsed_sql_total | COUNTER |
按类型（INSERT、UPDATE、DELETE、SELECT、DDL、DCL、DAL、TCL、RQL、RDL、RAL、RUL）分类的解析总数
|
+| routed_sql_total | COUNTER |
按类型（INSERT、UPDATE、DELETE、SELECT）分类的路由总数
|
+| routed_result_total | COUNTER |
路由结果总数(数据源路由结果、表路由结果)
|
+| jdbc_state | GAUGE |
ShardingSphere-JDBC 状态信息。0 表示正常状态；1 表示熔断状态；2 锁定状态 |
+| jdbc_meta_data_info | GAUGE |
ShardingSphere-JDBC 元数据信息
|
+| jdbc_statement_execute_total | COUNTER | 语句执行总数
|
+| jdbc_statement_execute_errors_total | COUNTER | 语句执行错误总数
|
+| jdbc_statement_execute_latency_millis | HISTOGRAM | 语句执行耗时
|
+| jdbc_transactions_total | COUNTER | 事务总数，按
commit，rollback 分类
|
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.en.md
new file mode 100644
index 00000000000..21eed5eab7b
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/observability/_index.en.md
@@ -0,0 +1,118 @@
++++
+title = "Observability"
+weight = 7
++++
+
+## Agent
+
+### Compile source code
+
+Download Apache ShardingSphere from GitHub,Then compile.
+
+```shell
+git clone --depth 1 https://github.com/apache/shardingsphere.git
+cd shardingsphere
+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.
+
+```shell
+mkdir agent
+tar -zxvf
apache-shardingsphere-${latest.release.version}-shardingsphere-agent-bin.tar.gz
-C agent
+cd agent
+tree
+├── LICENSE
+├── NOTICE
+├── conf
+│ └── agent.yaml
+├── plugins
+│ ├── lib
+│ │ ├── shardingsphere-agent-metrics-core-${latest.release.version}.jar
+│ │ └── shardingsphere-agent-plugin-core-${latest.release.version}.jar
+│ ├── logging
+│ │ └── shardingsphere-agent-logging-file-${latest.release.version}.jar
+│ ├── metrics
+│ │ └──
shardingsphere-agent-metrics-prometheus-${latest.release.version}.jar
+│ └── tracing
+│ ├──
shardingsphere-agent-tracing-opentelemetry-${latest.release.version}.jar
+│ └──
shardingsphere-agent-tracing-opentracing-${latest.release.version}.jar
+└── 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.
+
+```yaml
+plugins:
+# logging:
+# File:
+# props:
+# level: "INFO"
+# metrics:
+# Prometheus:
+# host: "localhost"
+# port: 9090
+# props:
+# jvm-information-collector-enabled: "true"
+# tracing:
+# OpenTelemetry:
+# props:
+# otel.service.name: "shardingsphere"
+# otel.traces.exporter: "jaeger"
+# otel.exporter.otlp.traces.endpoint: "http://localhost:14250";
+# otel.traces.sampler: "always_on"
+# OpenTracing:
+# props:
+# 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
+
+| Name | Description
|
+|-----------------------------------|----------------------------------------------|
+| host | host IP
|
+| port | port
|
+| jvm-information-collector-enabled | whether to collect JVM indicator
information |
+
+## Usage in ShardingSphere-JDBC
+
++ 1 The `SpringBoot` project ready to integrate `ShardingSphere-JDBC`,
test-project.jar
++ 2 Startup project
+```shell
+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
+
+| Name | Type |
Description
|
+| :---------------------------------------- | :------------------
|:-----------------------------------------------------------------------------------------------------------|
+| build_info | GAUGE | Build
information
|
+| parsed_sql_total | COUNTER | Total
count of parsed by type (INSERT, UPDATE, DELETE, SELECT, DDL, DCL, DAL, TCL,
RQL, RDL, RAL, RUL) |
+| routed_sql_total | COUNTER | Total
count of routed by type (INSERT, UPDATE, DELETE, SELECT)
|
+| routed_result_total | COUNTER | Total
count of routed result (data source routed, table routed)
|
+| jdbc_state | GAUGE | Status
information of ShardingSphere-JDBC. 0 is OK; 1 is CIRCUIT BREAK; 2 is LOCK
|
+| jdbc_meta_data_info | GAUGE | Meta data
information of ShardingSphere-JDBC
|
+| jdbc_statement_execute_total | GAUGE | Total
number of statements executed
|
+| jdbc_statement_execute_errors_total | GAUGE | Total
number of statement execution errors
|
+| jdbc_statement_execute_latency_millis | HISTOGRAM | Statement
execution latency
|
+| jdbc_transactions_total | GAUGE | Total
number of transactions, classify by commit and rollback
|
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.cn.md
index 700f09d331d..1f25a6a65c5 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.cn.md
@@ -156,12 +156,12 @@ services:
| 指标名称 | 指标类型 | 指标描述
|
| :-------------------------------- | :------------------
|:--------------------------------------------------------------------------|
-| build_info | GAUGE_METRIC_FAMILY | 构建信息
|
+| build_info | GAUGE | 构建信息
|
| parsed_sql_total | COUNTER |
按类型（INSERT、UPDATE、DELETE、SELECT、DDL、DCL、DAL、TCL、RQL、RDL、RAL、RUL）分类的解析总数 |
| routed_sql_total | COUNTER |
按类型（INSERT、UPDATE、DELETE、SELECT）分类的路由总数 |
| routed_result_total | COUNTER |
路由结果总数(数据源路由结果、表路由结果) |
-| proxy_state | GAUGE_METRIC_FAMILY |
ShardingSphere-Proxy 状态信息。0 表示正常状态；1 表示熔断状态；2 锁定状态 |
-| proxy_meta_data_info | GAUGE_METRIC_FAMILY |
ShardingSphere-Proxy 元数据信息，database_count：逻辑库数量，storage_unit_count：存储节点数量 |
+| proxy_state | GAUGE |
ShardingSphere-Proxy 状态信息。0 表示正常状态；1 表示熔断状态；2 锁定状态 |
+| proxy_meta_data_info | GAUGE |
ShardingSphere-Proxy 元数据信息，database_count：逻辑库数量，storage_unit_count：存储节点数量 |
| proxy_current_connections | GAUGE |
ShardingSphere-Proxy 的当前连接数 |
| proxy_requests_total | COUNTER |
ShardingSphere-Proxy 的接受请求总数 |
| proxy_transactions_total | COUNTER |
ShardingSphere-Proxy 的事务总数，按 commit，rollback 分类 |
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.en.md
index 0a042dfb9d8..d4ca137bb4f 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/observability/_index.en.md
@@ -159,12 +159,12 @@ services:
| Name | Type | Description
|
| :-------------------------------- | :------------------
|:------------------------------------------------------------------------------------------------------------------------------------------|
-| build_info | GAUGE_METRIC_FAMILY | Build information
|
+| build_info | GAUGE | Build information
|
| parsed_sql_total | COUNTER | Total count of
parsed by type (INSERT, UPDATE, DELETE, SELECT, DDL, DCL, DAL, TCL, RQL, RDL,
RAL, RUL) |
| routed_sql_total | COUNTER | Total count of
routed by type (INSERT, UPDATE, DELETE, SELECT)
|
| routed_result_total | COUNTER | Total count of
routed result (data source routed, table routed)
|
-| proxy_state | GAUGE_METRIC_FAMILY | Status information
of ShardingSphere-Proxy. 0 is OK; 1 is CIRCUIT BREAK; 2 is LOCK
|
-| proxy_meta_data_info | GAUGE_METRIC_FAMILY | Meta data
information of ShardingSphere-Proxy. database_count is logic number of
databases; storage_unit_count is number of storage units |
+| proxy_state | GAUGE | Status information
of ShardingSphere-Proxy. 0 is OK; 1 is CIRCUIT BREAK; 2 is LOCK
|
+| proxy_meta_data_info | GAUGE | Meta data
information of ShardingSphere-Proxy. database_count is logic number of
databases; storage_unit_count is number of storage units |
| proxy_current_connections | GAUGE | Current
connections of ShardingSphere-Proxy
|
| proxy_requests_total | COUNTER | Total requests of
ShardingSphere-Proxy
|
| proxy_transactions_total | COUNTER | Total transactions
of ShardingSphere-Proxy, classify by commit, rollback
|
