From b170feeb226798d57d6b3ae42cca24d2d79efb52 Mon Sep 17 00:00:00 2001 From: t_max <1172915550@qq.com> Date: Fri, 9 Aug 2024 11:29:37 +0800 Subject: [PATCH] docs: update java demo and grafana alert --- .../com/taos/example/WSConnectExample.java | 4 +- docs/zh/08-develop/01-connect/index.md | 12 +- docs/zh/08-develop/02-sql.md | 2 +- docs/zh/08-develop/04-schemaless.md | 4 +- docs/zh/14-reference/05-connector/14-java.mdx | 2 +- docs/zh/14-reference/05-connector/index.md | 49 ++--- .../20-third-party/03-visual/01-grafana.mdx | 184 ++++++++++-------- .../java/com/taosdata/example/HikariDemo.java | 2 +- 8 files changed, 139 insertions(+), 120 deletions(-) diff --git a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java index d683cc64a6..f920e77037 100644 --- a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java @@ -11,9 +11,9 @@ public class WSConnectExample { // ANCHOR: main public static void main(String[] args) throws SQLException { // use - // String jdbcUrl = "jdbc:TAOS-RS://localhost:6041/dbName?user=root&password=taosdata"; + // String jdbcUrl = "jdbc:TAOS-RS://localhost:6041/dbName?user=root&password=taosdata&batchfetch=true"; // if you want to connect a specified database named "dbName". - String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata"; + String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata&batchfetch=true"; Properties connProps = new Properties(); connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true"); connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true"); diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index 2e0f284eeb..8e279e586e 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -259,17 +259,19 @@ dotnet add package TDengine.Connector ## 建立连接 在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。 + ### 连接参数 连接的配置项较多，因此在建立连接之前，我们能先介绍一下各语言连接器建立连接使用的参数。 + Java 连接器建立连接的参数有 URL 和 Properties。 + TDengine 的 JDBC URL 规范格式为： + `jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}|&batchfetch={batchfetch}]` -Java 连接器建立连接的参数有 URL 和 Properties。 -TDengine 的 JDBC URL 规范格式为： -`jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` + URL 和 Properties 的详细参数说明和如何使用详见 [url 规范](../../reference/connector/java/#url-规范) -URL 和 Properties 的详细参数说明和如何使用详见 [url 规范](../../reference/connector/java/#url-规范) + **注**：REST 连接中增加 `batchfetch` 参数并设置为 true，将开启 WebSocket 连接。 @@ -343,7 +345,7 @@ DSN 的详细说明和如何使用详见 [连接功能](../../reference/connecto - **database**: 数据库名称。 - **params**: 其他参数。 例如token。 - - 完整 D 示例： + - 完整 DSN 示例： ```js ws://root:taosdata@localhost:6041 diff --git a/docs/zh/08-develop/02-sql.md b/docs/zh/08-develop/02-sql.md index 18d1072ce9..3bebe5e7a4 100644 --- a/docs/zh/08-develop/02-sql.md +++ b/docs/zh/08-develop/02-sql.md @@ -90,7 +90,7 @@ curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql/power' \ -> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 `power.meters`。 +> **注意**：建议采用 `.` 的格式构造SQL语句，不推荐在应用中采用 `USE DBName`方式访问。 ## 插入数据 下面以智能电表为例，展示如何使用连接器执行 SQL 来插入数据到 `power` 数据库的 `meters` 超级表。样例使用 TDengine 自动建表 SQL 语法，写入 d1001 子表中 3 条数据，写入 d1002 子表中 1 条数据，然后打印出实际插入数据条数。 diff --git a/docs/zh/08-develop/04-schemaless.md b/docs/zh/08-develop/04-schemaless.md index 2c5279f1d6..1bc750c3cb 100644 --- a/docs/zh/08-develop/04-schemaless.md +++ b/docs/zh/08-develop/04-schemaless.md @@ -169,7 +169,7 @@ st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit" 1626006833640000000 ``` -执行带有 reqId 的无模式写入，此 reqId 可用于请求链路追踪。 +执行带有 reqId 的无模式写入，最后一个参数 reqId 可用于请求链路追踪。 ```java writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO_SECONDS, 1L); @@ -213,7 +213,7 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO {{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java:schemaless}} ``` -执行带有 reqId 的无模式写入，此 reqId 可用于请求链路追踪。 +执行带有 reqId 的无模式写入，最后一个参数 reqId 可用于请求链路追踪。 ```java writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO_SECONDS, 1L); diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index 8d19745668..0dc85feb13 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -199,7 +199,7 @@ Websocket 和 REST 连接使用驱动类 `com.taosdata.jdbc.rs.RestfulDriver`。 #### URL 规范 TDengine 的 JDBC URL 规范格式为： -`jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` +`jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}|&batchfetch={batchfetch}]` 对于建立连接，原生连接与 REST 连接有细微不同。 Websocket 和 REST 连接使用驱动类 `com.taosdata.jdbc.rs.RestfulDriver`。原生连接使用驱动类 `com.taosdata.jdbc.TSDBDriver`。 diff --git a/docs/zh/14-reference/05-connector/index.md b/docs/zh/14-reference/05-connector/index.md index be25521a30..bc63bdff93 100644 --- a/docs/zh/14-reference/05-connector/index.md +++ b/docs/zh/14-reference/05-connector/index.md @@ -13,7 +13,7 @@ TDengine 提供了丰富的应用程序开发接口，为了便于用户快速 目前 TDengine 的原生接口连接器可支持的平台包括：X64/ARM64 等硬件平台，以及 Linux/Win64 等开发环境。对照矩阵如下： | **CPU** | **OS** | **Java** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | C/C++ | -| ------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----- | +|---------------|-----------|----------|------------|--------|-------------|--------|----------|-------| | **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● | | **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● | | **X86 64bit** | **macOS** | ● | ● | ● | ○ | ○ | ● | ● | @@ -28,14 +28,14 @@ TDengine 提供了丰富的应用程序开发接口，为了便于用户快速 TDengine 版本更新往往会增加新的功能特性，列表中的连接器版本为连接器最佳适配版本。 -| **TDengine 版本** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | -| ---------------------- | ------------- | ------------------------------------------- | ------------ | ------------- | --------------- | -------- | -| **3.3.0.0 及以上** | 3.3.2.0及以上 | taospy 2.7.15及以上，taos-ws-py 0.3.2及以上 | 3.5.5及以上 | 3.1.3及以上 | 3.1.0及以上 | 当前版本 | -| **3.0.0.0 及以上** | 3.0.2以上 | 当前版本 | 3.0 分支 | 3.0.0 | 3.1.0 | 当前版本 | -| **2.4.0.14 及以上** | 2.0.38 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | -| **2.4.0.4 - 2.4.0.13** | 2.0.37 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | -| **2.2.x.x ** | 2.0.36 | 当前版本 | master 分支 | n/a | 2.0.7 - 2.0.9 | 当前版本 | -| **2.0.x.x ** | 2.0.34 | 当前版本 | master 分支 | n/a | 2.0.1 - 2.0.6 | 当前版本 | +| **TDengine 版本** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +|------------------------|----------|--------------------------------------|------------|---------------|-----------------|----------| +| **3.3.0.0 及以上** | 3.3.0及以上 | taospy 2.7.15及以上，taos-ws-py 0.3.2及以上 | 3.5.5及以上 | 3.1.3及以上 | 3.1.0及以上 | 当前版本 | +| **3.0.0.0 及以上** | 3.0.2以上 | 当前版本 | 3.0 分支 | 3.0.0 | 3.1.0 | 当前版本 | +| **2.4.0.14 及以上** | 2.0.38 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | +| **2.4.0.4 - 2.4.0.13** | 2.0.37 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | +| **2.2.x.x ** | 2.0.36 | 当前版本 | master 分支 | n/a | 2.0.7 - 2.0.9 | 当前版本 | +| **2.0.x.x ** | 2.0.34 | 当前版本 | master 分支 | n/a | 2.0.1 - 2.0.6 | 当前版本 | ## 功能特性 @@ -43,13 +43,13 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 ### 使用原生接口（taosc） -| **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | -| ------------------- | -------- | ---------- | ------ | ------ | ----------- | -------- | -| **连接管理** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | -| **普通查询** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | -| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | -| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | -| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +|----------------|----------|------------|--------|--------|-------------|----------| +| **连接管理** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | :::info 由于不同编程语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。 @@ -57,17 +57,18 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 ### 使用 http (REST 或 WebSocket) 接口 -| **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | -| ------------------------------ | -------- | ---------- | ------ | ------ | ----------- | -------- | -| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **批量拉取（基于 WebSocket）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +|------------------------|----------|------------|--------|--------|-------------|----------| +| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **批量拉取（基于 WebSocket）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | :::warning +- 参数绑定、数据订阅、Schemaless 和批量拉取功能仅在 WebSocket 连接下支持。 - 无论选用何种编程语言的连接器，2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池，以避免连接内的“USE statement”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。 ::: diff --git a/docs/zh/20-third-party/03-visual/01-grafana.mdx b/docs/zh/20-third-party/03-visual/01-grafana.mdx index 9d12e1db04..860087b901 100644 --- a/docs/zh/20-third-party/03-visual/01-grafana.mdx +++ b/docs/zh/20-third-party/03-visual/01-grafana.mdx @@ -22,8 +22,6 @@ TDengine 能够与开源数据可视化系统 [Grafana](https://www.grafana.com/ - TDengine 集群已经部署并正常运行。 - taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](../../../reference/components/taosadapter) - - 记录以下信息： - TDengine 集群 REST API 地址，如：`http://tdengine.local:6041`。 @@ -173,7 +171,6 @@ docker run -d \ - :::info 下文介绍中，都以 Grafana v11.0.0 版本为例，其他版本功能可能有差异，请参考 [Grafana 官网](https://grafana.com/docs/grafana/latest/)。 @@ -181,6 +178,7 @@ docker run -d \ ::: ## 内置变量和自定义变量 + Grafana 中的 Variable（变量）功能非常强大，可以在 Dashboard 的查询、面板标题、标签等地方使用，用来创建更加动态和交互式的 Dashbord，提高用户体验和效率。 变量的主要作用和特点包括： @@ -191,26 +189,30 @@ Grafana 中的 Variable（变量）功能非常强大，可以在 Dashboard 的 - 灵活的配置选项：变量提供了多种配置选项，如预定义的静态值列表、从数据源动态查询值、正则表达式过滤等，使得变量的应用更加灵活和强大。 - Grafana 提供了内置变量和自定义变量，它们都可以可以在编写 SQL 时引用，引用的方式是 `$variableName`，`variableName` 是变量的名字，其他引用方式请参考 [引用方式](https://grafana.com/docs/grafana/latest/dashboards/variables/variable-syntax/)。 ### 内置变量 + Grafana 内置了 `from`、`to` 和 `interval` 等变量，都取自于 Grafana 插件面板。其含义如下： - `from` 查询范围的起始时间 - `to` 查询范围的结束时间 - `interval` 窗口切分间隔 -对于每个查询都建议设置查询范围的起始时间和结束时间，可以有效的减少 TDengine 服务端执行查询扫描的数据量。`interval` 是窗口切分的大小，在 Grafana 11 版本中，其大小为时间间隔和返回点数计算而得。 +对于每个查询都建议设置查询范围的起始时间和结束时间，可以有效的减少 TDengine 服务端执行查询扫描的数据量。`interval` 是窗口切分的大小，在 Grafana 11 版本中，其大小为时间间隔和返回点数计算而得。 + 除了上述三个常用变量，Grafana 还提供了如 `__timezone`, `__org`, `__user` 等变量，详情请参考 [内置变量](https://grafana.com/docs/grafana/latest/dashboards/variables/add-template-variables/#global-variables)。 ### 自定义变量 + 我们可以在 Dashbord 中增加自定义变量。自定义变量和内置变量的使用方式没有区别，都是在 SQL 中用 `$variableName` 进行引用。 自定义变量支持多种类型，常见的类型包括 `Query`（查询）、`Constant`（常量）、`Interval`（间隔）、`Data source`（数据源）等。 自定义变量可以引用其他自定义变量，比如一个变量表示区域，另一个变量可以引用区域的值，来查询这个区域的设备。 -#### 添加查询类型变量 + +#### 添加查询类型变量 + 在 Dashbord 的配置中，选择 【Variables】，然后点击 【New variable】： -1. 在 “Name“ 字段中，输入你的变量名，此处我们设置变量名为 `selected_groups`。 -2. 在 【Select variable type】下拉菜单中，选择 ”Query“（查询）。 +1. 在 “Name” 字段中，输入你的变量名，此处我们设置变量名为 `selected_groups`。 +2. 在 【Select variable type】下拉菜单中，选择 “Query”（查询）。 根据选择的变量类型，配置相应的选项。例如，如果选择了 “Query” 类型，你需要指定数据源和用于获取变量值的查询语句。此处我们还以智能电表为例，设置查询类型，选择数据源后，配置 SQL 为 `select distinct(groupid) from power.meters where groupid < 3 and ts > $from and ts < $to;` 3. 点击底部的【Run Query】后，可以在 “Preview of values”（值预览）部分，查看到根据你的配置生成的变量值。 4. 还有其他配置不再赘述，完成配置后，点击页面底部的【Apply】（应用）按钮，然后点击右上角的【Save dashboard】保存。 @@ -219,9 +221,10 @@ Grafana 内置了 `from`、`to` 和 `interval` 等变量，都取自于 Grafana 我们还可以再新增自定义变量来引用这个 `selected_groups` 变量，比如我们新增一个名为 `tbname_max_current` 的查询变量，其 SQL 为 `select tbname from power.meters where groupid = $selected_groups and ts > $from and ts < $to;` -#### 添加间隔类型变量 +#### 添加间隔类型变量 + 我们可以自定义时间窗口间隔，可以更加贴合业务需求。 -1. 在 “Name“ 字段中，输入变量名为 `interval`。 +1. 在 “Name” 字段中，输入变量名为 `interval`。 2. 在 【Select variable type】下拉菜单中，选择 “Interval”（间隔）。 3. 在 【Interval options】选项中输入 `1s,2s,5s,10s,15s,30s,1m`。 4. 还有其他配置不再赘述，完成配置后，点击页面底部的【Apply】（应用）按钮，然后点击右上角的【Save dashboard】保存。 @@ -235,6 +238,7 @@ Grafana 内置了 `from`、`to` 和 `interval` 等变量，都取自于 Grafana ::: ## TDengine 时间序列查询支持 + TDengine 在支持标准 SQL 的基础之上，还提供了一系列满足时序业务场景需求的特色查询语法，这些语法能够为时序场景的应用的开发带来极大的便利。 - `partition by` 子句可以按一定的维度对数据进行切分，然后在切分出的数据空间内再进行一系列的计算。绝大多数情况可以替代 `group by`。 - `interval` 子句用于产生相等时间周期的窗口 @@ -249,13 +253,14 @@ TDengine 在支持标准 SQL 的基础之上，还提供了一系列满足时序 ![TDengine Database Grafana plugin create dashboard](./create_dashboard1.webp) -如上图所示，在 ”Query“ 中选中 `TDengine` 数据源，在下方查询框可输入相应 SQL 进行查询。 我们继续用智能电表来举例，为了展示曲线美观，此处**用了虚拟数据**。 +如上图所示，在 “Query” 中选中 `TDengine` 数据源，在下方查询框可输入相应 SQL 进行查询。 我们继续用智能电表来举例，为了展示曲线美观，此处**用了虚拟数据**。 ## 时间序列数据展示 + 假设我们想查询一段时间内的平均电流大小，时间窗口按 `$interval` 切分，若某一时间窗口区间数据缺失，填充 null。 -- “INPUT SQL“：输入要查询的语句（该 SQL 语句的结果集应为两列多行），此处输入：`select _wstart as ts, avg(current) as current from power.meters where groupid in ($selected_groups) and ts > $from and ts < $to interval($interval) fill(null)` ，其中，from、to 和 interval 为 Grafana 内置变量，selected_groups 为自定义变量。 -- “ALIAS BY“：可设置当前查询别名。 -- “GENERATE SQL“： 点击该按钮会自动替换相应变量，并生成最终执行的语句。 +- “INPUT SQL”：输入要查询的语句（该 SQL 语句的结果集应为两列多行），此处输入：`select _wstart as ts, avg(current) as current from power.meters where groupid in ($selected_groups) and ts > $from and ts < $to interval($interval) fill(null)` ，其中，from、to 和 interval 为 Grafana 内置变量，selected_groups 为自定义变量。 +- “ALIAS BY”：可设置当前查询别名。 +- “GENERATE SQL”： 点击该按钮会自动替换相应变量，并生成最终执行的语句。 在顶部的自定义变量中，若选择 `selected_groups` 的值为 1，则查询 `meters` 超级表中 `groupid` 为 1 的所有设备电流平均值变化如下图： @@ -268,10 +273,11 @@ TDengine 在支持标准 SQL 的基础之上，还提供了一系列满足时序 ::: ## 时间序列数据分组展示 + 假设我们想查询一段时间内的平均电流大小，按 `groupid` 分组展示，我们可以修改之前的 SQL 为 `select _wstart as ts, groupid, avg(current) as current from power.meters where ts > $from and ts < $to partition by groupid interval($interval) fill(null)` -- “Group by column(s)“： **半角**逗号分隔的 `group by` 或 `partition by` 列名。如果是 `group by` 或 `partition by` 查询语句，设置 “Group by“ 列，可以展示多维数据。此处设置 “Group by“ 列名为 `groupid`，可以按 `groupid` 分组展示数据。 -- “Group By Format“： `Group by` 或 `Partition by` 场景下多维数据 legend 格式化格式。例如上述 INPUT SQL，将 “Group By Format“ 设置为 `groupid-{{groupid}}`，展示的 legend 名字为格式化的分组名。 +- “Group by column(s)”： **半角**逗号分隔的 `group by` 或 `partition by` 列名。如果是 `group by` 或 `partition by` 查询语句，设置 “Group by” 列，可以展示多维数据。此处设置 “Group by” 列名为 `groupid`，可以按 `groupid` 分组展示数据。 +- “Group By Format”： `Group by` 或 `Partition by` 场景下多维数据 legend 格式化格式。例如上述 INPUT SQL，将 “Group By Format” 设置为 `groupid-{{groupid}}`，展示的 legend 名字为格式化的分组名。 完成设置后，按照 `groupid` 分组展示如下图： @@ -280,10 +286,10 @@ TDengine 在支持标准 SQL 的基础之上，还提供了一系列满足时序 > 关于如何使用 Grafana 创建相应的监测界面以及更多有关使用 Grafana 的信息，请参考 Grafana 官方的[文档](https://grafana.com/docs/)。 ## 性能建议 + - **所有查询加上时间范围**，在时序数据库中，如果不加查询的时间范围，会扫表导致性能低下。常见的 SQL 写法是 `select column_name from db.table where ts > $from and ts < $to;` - 对于最新状态类型的查询，我们一般建议在**创建数据库的时候打开缓存**（`CACHEMODEL` 设置为 last_row 或者 both），常见的 SQL 写法是 `select last(column_name) from db.table where ts > $from and ts < $to;` - ## 导入 Dashboard 在数据源配置页面，您可以为该数据源导入 TDinsight 面板，作为 TDengine 集群的监控可视化工具。如果 TDengine 服务端为 3.0 版本请选择 `TDinsight for 3.x` 导入。注意 TDinsight for 3.x 需要运行和配置 taoskeeper。 @@ -299,30 +305,36 @@ TDengine 在支持标准 SQL 的基础之上，还提供了一系列满足时序 - [15167](https://grafana.com/grafana/dashboards/15167)： TDinsight - [16388](https://grafana.com/grafana/dashboards/16388)： Telegraf 采集节点信息的数据展示 -## 告警配置简介 -### 告警配置流程 +## 告警配置 + TDengine Grafana 插件支持告警，如果要配置告警，需要以下几个步骤： -1. 配置联络点（“Contact points“）：配置通知渠道，包括 DingDing、Email、Slack、WebHook、Prometheus Alertmanager 等 -2. 配置告警通知策略（“Notification policies“）：配置告警发送到哪个通道的路由，以及发送通知的时间和重复频率 -3. 配置 “Alert rules“：配置详细的告警规则 +1. 配置联络点（“Contact points”）：配置通知渠道，包括 DingDing、Email、Slack、WebHook、Prometheus Alertmanager 等 +2. 配置告警通知策略（“Notification policies”）：配置告警发送到哪个通道的路由，以及发送通知的时间和重复频率 +3. 配置告警规则（“Alert rules”）：配置详细的告警规则 3.1 配置告警名称 - 3.2 配置查询及告警触发条件 + 3.2 配置查询和告警触发条件 3.3 配置规则评估策略 3.4 配置标签和告警通道 3.5 配置通知文案 ### 告警配置界面 -在Grafana 11 告警界面一共有 6 个 Tab，分别是 “Alert rules“、“Contact points“、“Notification policies“、“Silences“、 “Groups“ 和 “Settings“。 -- “Alert rules“ 告警规则列表，用于展示和配置告警规则 -- “Contact points“ 通知渠道，包括 DingDing、Email、Slack、WebHook、Prometheus Alertmanager 等 -- “Notification policies“ 配置告警发送到哪个通道的路由，以及发送通知的时间和重复频率 -- “Silences“ 配置告警静默时间段 -- “Groups“ 告警组，配置的告警触发后会在这里分组显示 -- “Settings“ 提供通过 JSON 方式修改告警配置 -## 配置邮件联络点 -### Grafana Server 配置文件修改 -在 Grafana 服务的配置文件中添加 SMTP/Emailing 和 Alerting 模块，以 Linux 系统为例，其配置文件一般位于 `/etc/grafana/grafana.ini` +在Grafana 11 告警界面一共有 6 个 Tab，分别是 “Alert rules”、“Contact points”、“Notification policies”、“Silences”、 “Groups” 和 “Settings”。 +- “Alert rules” 告警规则列表，用于展示和配置告警规则 +- “Contact points” 通知渠道，包括 DingDing、Email、Slack、WebHook、Prometheus Alertmanager 等 +- “Notification policies” 配置告警发送到哪个通道的路由，以及发送通知的时间和重复频率 +- “Silences” 配置告警静默时间段 +- “Groups” 告警组，配置的告警触发后会在这里分组显示 +- “Settings” 提供通过 JSON 方式修改告警配置 + +### 配置联络点 + +以邮件和飞书为例配置联络点。 + +#### 配置邮件联络点 + +在 Grafana 服务的配置文件中添加 SMTP/Emailing 和 Alerting 模块。（以 Linux 系统为例，其配置文件一般位于 `/etc/grafana/grafana.ini`） + 在配置文件中增加下面内容： ```ini @@ -336,106 +348,110 @@ skip_verify = true from_address = sender@foxmail.com ``` -然后重启 Grafana 服务即可， 以 Linux 系统为例，执行 `systemctl restart grafana-server.service` +然后重启 Grafana 服务（以 Linux 系统为例，执行 `systemctl restart grafana-server.service`）即可添加完成 -### Grafana 页面创建新联络点 - -在 Grafana 页面找到 “Home“ -> “Alerting“ -> “Contact points“，创建新联络点 -”Name“： Email Contact Point -“Integration“：选择联络类型，这里选择 Email，填写邮件接收地址，完成后保存联络点 +在 Grafana 页面找到 “Home” -> “Alerting” -> “Contact points”，创建新联络点 +“Name”： Email Contact Point +“Integration”：选择联络类型，这里选择 Email，填写邮件接收地址，完成后保存联络点 ![TDengine Database Grafana plugin alert email](./alert-email.webp) -## 配置飞书联络点 +#### 配置飞书联络点 -### 飞书机器人配置 -1. “飞书工作台“ -> “获取应用“ -> “搜索飞书机器人助手“ -> “新建指令“ +按照以下步骤配置飞书机器人： + +1. “飞书工作台” -> “获取应用” -> “搜索飞书机器人助手” -> “新建指令” 2. 选择触发器：Grafana 3. 选择操作：通过官方机器人发送消息，填写发送对象和发送内容 ![TDengine Database Grafana plugin feishu robot](./alert-feishu1.webp) -### Grafana 配置飞书联络点 - -在 Grafana 页面找到 “Home“ -> “Alerting“ -> “Contact points“ 创建新联络点 -“Name“：Feishu Contact Point -“Integration“：选择联络类型，这里选择 Webhook，并填写 URL (在飞书机器人助手的 Grafana 触发器 Webhook 地址)，完成后保存联络点 +在 Grafana 页面找到 “Home” -> “Alerting” -> “Contact points” 创建新联络点 +“Name”：Feishu Contact Point +“Integration”：选择联络类型，这里选择 Webhook，并填写 URL (在飞书机器人助手的 Grafana 触发器 Webhook 地址)，完成后保存联络点 ![TDengine Database Grafana plugin feishu contact point](./alert-feishu2.webp) -## 通知策略 +### 配置告警通知策略 + 配置好联络点后，可以看到已有一个Default Policy ![TDengine Database Grafana plugin Notification default policy](./alert-notification1.webp) -点击右侧 ”...“ -> ”Edit“，然后编辑默认通知策略，弹出配置窗口： +点击右侧 “...” -> ”Edit”，然后编辑默认通知策略，弹出配置窗口： ![TDengine Database Grafana plugin Notification](./alert-notification2.webp) 然后配置下列参数： -- “Group wait“： 发送首次告警之前的等待时间。 -- “Group interval“： 发送第一个告警后，为该组发送下一批新告警的等待时间。 -- “Repeat interval“： 成功发送告警后再次重复发送告警的等待时间。 +- “Group wait”： 发送首次告警之前的等待时间。 +- “Group interval”： 发送第一个告警后，为该组发送下一批新告警的等待时间。 +- “Repeat interval”： 成功发送告警后再次重复发送告警的等待时间。 -## 配置告警规则 +### 配置告警规则 -### 配置查询和告警触发条件 +以配置智能电表告警为例，告警规则的配置主要包括告警名称、查询和告警触发条件、规则评估策略、标签和告警通道、通知文案。 -在需要配置告警的面板中选择 “Edit“ -> “Alert“ -> “New alert rule“。 +#### 配置告警名称 + +在需要配置告警的面板中选择 “Edit” -> “Alert” -> “New alert rule”。 + +“Enter alert rule name“ (输入告警规则名称)：此处以智能电表为例输入 `power meters alert` + +#### 配置查询和告警触发条件 + +在 “Define query and alert condition” (定义查询和告警触发条件) 中配置告警规则。 +1. 选择数据源：`TDengine Datasource` +2. 查询语句： -1. “Enter alert rule name“ (输入告警规则名称)：此处以智能电表为例输入 `power meters alert` -2. “Define query and alert condition“ (定义查询和告警触发条件) - 2.1 选择数据源：`TDengine Datasource` - 2.2 查询语句： ```sql select _wstart as ts, groupid, avg(current) as current from power.meters where ts > $from and ts < $to partition by groupid interval($interval) fill(null) ``` - 2.3 设置 ”Expression“（表达式）：`Threshold is above 100` - 2.4 点击【Set as alert condition】 - 2.5 “Preview“：查看设置的规则的结果 + +3. 设置 “Expression”（表达式）：`Threshold is above 100` +4. 点击【Set as alert condition】 +5. “Preview”：查看设置的规则的结果 完成设置后可以看到下面图片展示： ![TDengine Database Grafana plugin Alert Rules](./alert-rules1.webp) -### 配置表达式和计算规则 - -Grafana 的 “Expression“（表达式）支持对数据做各种操作和计算，其类型分为： -1. “Reduce“：将所选时间范围内的时间序列值聚合为单个值 - 1.1 “Function“ 用来设置聚合方法，支持 Min、Max、Last、Mean、Sum 和 Count。 - 1.2 “Mode“ 支持下面三种： - - “Strict“：如果查询不到数据，数据会赋值为 NaN。 - - “Drop Non-numeric Value“：去掉非法数据结果。 - - “Replace Non-numeric Value“：如果是非法数据，使用固定值进行替换。 -2. “Threshold“：检查时间序列数据是否符合阈值判断条件。当条件为假时返回 0，为真则返回1。支持下列方式： +Grafana 的 “Expression”（表达式）支持对数据做各种操作和计算，其类型分为： +1. “Reduce”：将所选时间范围内的时间序列值聚合为单个值 + 1.1 “Function” 用来设置聚合方法，支持 Min、Max、Last、Mean、Sum 和 Count。 + 1.2 “Mode” 支持下面三种： + - “Strict”：如果查询不到数据，数据会赋值为 NaN。 + - “Drop Non-numeric Value”：去掉非法数据结果。 + - “Replace Non-numeric Value”：如果是非法数据，使用固定值进行替换。 +2. “Threshold”：检查时间序列数据是否符合阈值判断条件。当条件为假时返回 0，为真则返回1。支持下列方式： - Is above (x > y) - Is below (x < y) - Is within range (x > y1 AND x < y2) - Is outside range (x < y1 AND x > y2) -3. “Math“：对时间序列的数据进行数学运算。 -4. “Resample“：更改每个时间序列中的时间戳使其具有一致的时间间隔，以便在它们之间执行数学运算。 -5. “Classic condition (legacy)“： 可配置多个逻辑条件，判断是否触发告警。 +3. “Math”：对时间序列的数据进行数学运算。 +4. “Resample”：更改每个时间序列中的时间戳使其具有一致的时间间隔，以便在它们之间执行数学运算。 +5. “Classic condition (legacy)”： 可配置多个逻辑条件，判断是否触发告警。 如上节截图显示，此处我们设置最大值超过 100 触发告警。 -### 配置评估策略 +#### 配置规则评估策略 ![TDengine Database Grafana plugin Alert Evaluation Behavior](./alert-evaluation.webp) 完成下面配置： -- “Folder“：设置告警规则所属目录。 -- “Evaluation group“：设置告警规则评估组。“Evaluation group“ 可以选择已有组或者新建组，新建组可以设置组名和评估时间间隔。 -- “Pending period“：在告警规则的阈值被触发后，异常值持续多长时间可以触发告警，合理设置可以避免误报。 +- “Folder”：设置告警规则所属目录。 +- “Evaluation group”：设置告警规则评估组。“Evaluation group” 可以选择已有组或者新建组，新建组可以设置组名和评估时间间隔。 +- “Pending period”：在告警规则的阈值被触发后，异常值持续多长时间可以触发告警，合理设置可以避免误报。 + +#### 配置标签和告警通道 -### 配置标签和告警通道 ![TDengine Database Grafana plugin Alert Labels and Notifications](./alert-labels.webp) 完成下面配置： -- “Labels“ 将标签添加到规则中，以便进行搜索、静默或路由到通知策略。 -- “Contact point“ 选择联络点，当告警发生时通过设置的联络点进行通知。 +- “Labels” 将标签添加到规则中，以便进行搜索、静默或路由到通知策略。 +- “Contact point” 选择联络点，当告警发生时通过设置的联络点进行通知。 -### 配置通知文案 +#### 配置通知文案 ![TDengine Database Grafana plugin Alert Labels and Notifications](./alert-annotations.webp) -设置 “Summary” 和 ”Description” 后，若告警触发，将会收到告警通知。 +设置 “Summary” 和 “Description” 后，若告警触发，将会收到告警通知。 diff --git a/examples/JDBC/connectionPools/src/main/java/com/taosdata/example/HikariDemo.java b/examples/JDBC/connectionPools/src/main/java/com/taosdata/example/HikariDemo.java index 79f636c428..4480cbc7c4 100644 --- a/examples/JDBC/connectionPools/src/main/java/com/taosdata/example/HikariDemo.java +++ b/examples/JDBC/connectionPools/src/main/java/com/taosdata/example/HikariDemo.java @@ -21,7 +21,7 @@ public static void main(String[] args) throws SQLException { config.setConnectionTimeout(30000); //maximum wait milliseconds for get connection from pool config.setMaxLifetime(0); // maximum life time for each connection config.setIdleTimeout(0); // max idle time for recycle idle connection - config.setConnectionTestQuery("SELECT SERVER_STATUS()"); //validation query + config.setConnectionTestQuery("SELECT SERVER_VERSION()"); //validation query HikariDataSource ds = new HikariDataSource(config); //create datasource