taosAdapter 参考手册

taosAdapter 是一个 TDengine 的配套工具，是 TDengine 集群和应用程序之间的桥梁和适配器。它提供了一种易于使用和高效的方式来直接从数据收集代理软件（如 Telegraf、StatsD、collectd 等）摄取数据。它还提供了 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine。

taosAdapter 提供以下功能：

• RESTful 接口
• 兼容 InfluxDB v1 写接口
• 兼容 OpenTSDB JSON 和 telnet 格式写入
• 无缝连接到 Telegraf
• 无缝连接到 collectd
• 无缝连接到 StatsD
• 支持 Prometheus remote_read 和 remote_write
• 获取 table 所在的虚拟节点组（VGroup）的 VGroup ID

taosAdapter 架构图

taosAdapter 部署方法

安装 taosAdapter

taosAdapter 是 TDengine 服务端软件 的一部分，如果您使用 TDengine server 您不需要任何额外的步骤来安装 taosAdapter。您可以从涛思数据官方网站下载 TDengine server 安装包。如果需要将 taosAdapter 分离部署在 TDengine server 之外的服务器上，则应该在该服务器上安装完整的 TDengine 来安装 taosAdapter。如果您需要使用源代码编译生成 taosAdapter，您可以参考构建 taosAdapter文档。

启动/停止 taosAdapter

在 Linux 系统上 taosAdapter 服务默认由 systemd 管理。使用命令 systemctl start taosadapter 可以启动 taosAdapter 服务。使用命令 systemctl stop taosadapter 可以停止 taosAdapter 服务。

移除 taosAdapter

使用命令 rmtaos 可以移除包括 taosAdapter 在内的 TDengine server 软件。

升级 taosAdapter

taosAdapter 和 TDengine server 需要使用相同版本。请通过升级 TDengine server 来升级 taosAdapter。 与 taosd 分离部署的 taosAdapter 必须通过升级其所在服务器的 TDengine server 才能得到升级。

taosAdapter 参数列表

taosAdapter 支持通过命令行参数、环境变量和配置文件来进行配置。默认配置文件是 /etc/taos/taosadapter.toml。

命令行参数优先于环境变量优先于配置文件，命令行用法是 arg=val，如 taosadapter -p=30000 —debug=true，详细列表如下：

1. Usage of taosAdapter:
2. --collectd.db string                           collectd db name. Env "TAOS_ADAPTER_COLLECTD_DB" (default "collectd")
3. --collectd.enable                              enable collectd. Env "TAOS_ADAPTER_COLLECTD_ENABLE" (default true)
4. --collectd.password string                     collectd password. Env "TAOS_ADAPTER_COLLECTD_PASSWORD" (default "taosdata")
5. --collectd.port int                            collectd server port. Env "TAOS_ADAPTER_COLLECTD_PORT" (default 6045)
6. --collectd.ttl int                             collectd data ttl. Env "TAOS_ADAPTER_COLLECTD_TTL"
7. --collectd.user string                         collectd user. Env "TAOS_ADAPTER_COLLECTD_USER" (default "root")
8. --collectd.worker int                          collectd write worker. Env "TAOS_ADAPTER_COLLECTD_WORKER" (default 10)
9. -c, --config string                                config path default /etc/taos/taosadapter.toml
10. --cors.allowAllOrigins                         cors allow all origins. Env "TAOS_ADAPTER_CORS_ALLOW_ALL_ORIGINS" (default true)
11. --cors.allowCredentials                        cors allow credentials. Env "TAOS_ADAPTER_CORS_ALLOW_Credentials"
12. --cors.allowHeaders stringArray                cors allow HEADERS. Env "TAOS_ADAPTER_ALLOW_HEADERS"
13. --cors.allowOrigins stringArray                cors allow origins. Env "TAOS_ADAPTER_ALLOW_ORIGINS"
14. --cors.allowWebSockets                         cors allow WebSockets. Env "TAOS_ADAPTER_CORS_ALLOW_WebSockets"
15. --cors.exposeHeaders stringArray               cors expose headers. Env "TAOS_ADAPTER_Expose_Headers"
16. --debug                                        enable debug mode. Env "TAOS_ADAPTER_DEBUG" (default true)
17. --help                                         Print this help message and exit
18. --httpCodeServerError                          Use a non-200 http status code when server returns an error. Env "TAOS_ADAPTER_HTTP_CODE_SERVER_ERROR"
19. --influxdb.enable                              enable influxdb. Env "TAOS_ADAPTER_INFLUXDB_ENABLE" (default true)
20. --instanceId int                               instance ID. Env "TAOS_ADAPTER_INSTANCE_ID" (default 32)
21. --log.compress                                 whether to compress old log. Env "TAOS_ADAPTER_LOG_COMPRESS"
22. --log.enableRecordHttpSql                      whether to record http sql. Env "TAOS_ADAPTER_LOG_ENABLE_RECORD_HTTP_SQL"
23. --log.level string                             log level (trace debug info warning error). Env "TAOS_ADAPTER_LOG_LEVEL" (default "info")
24. --log.path string                              log path. Env "TAOS_ADAPTER_LOG_PATH" (default "/var/log/taos")
25. --log.reservedDiskSize string                  reserved disk size for log dir (KB MB GB), must be a positive integer. Env "TAOS_ADAPTER_LOG_RESERVED_DISK_SIZE" (default "1GB")
26. --log.rotationCount uint                       log rotation count. Env "TAOS_ADAPTER_LOG_ROTATION_COUNT" (default 30)
27. --log.rotationSize string                      log rotation size(KB MB GB), must be a positive integer. Env "TAOS_ADAPTER_LOG_ROTATION_SIZE" (default "1GB")
28. --log.rotationTime duration                    deprecated: log rotation time always 24 hours. Env "TAOS_ADAPTER_LOG_ROTATION_TIME" (default 24h0m0s)
29. --log.sqlRotationCount uint                    record sql log rotation count. Env "TAOS_ADAPTER_LOG_SQL_ROTATION_COUNT" (default 2)
30. --log.sqlRotationSize string                   record sql log rotation size(KB MB GB), must be a positive integer. Env "TAOS_ADAPTER_LOG_SQL_ROTATION_SIZE" (default "1GB")
31. --log.sqlRotationTime duration                 record sql log rotation time. Env "TAOS_ADAPTER_LOG_SQL_ROTATION_TIME" (default 24h0m0s)
32. --logLevel string                              log level (trace debug info warning error). Env "TAOS_ADAPTER_LOG_LEVEL" (default "info")
33. --monitor.collectDuration duration             Set monitor duration. Env "TAOS_ADAPTER_MONITOR_COLLECT_DURATION" (default 3s)
34. --monitor.disable                              Whether to disable monitoring. Env "TAOS_ADAPTER_MONITOR_DISABLE" (default true)
35. --monitor.identity string                      The identity of the current instance, or 'hostname:port' if it is empty. Env "TAOS_ADAPTER_MONITOR_IDENTITY"
36. --monitor.incgroup                             Whether running in cgroup. Env "TAOS_ADAPTER_MONITOR_INCGROUP"
37. --monitor.pauseAllMemoryThreshold float        Memory percentage threshold for pause all. Env "TAOS_ADAPTER_MONITOR_PAUSE_ALL_MEMORY_THRESHOLD" (default 80)
38. --monitor.pauseQueryMemoryThreshold float      Memory percentage threshold for pause query. Env "TAOS_ADAPTER_MONITOR_PAUSE_QUERY_MEMORY_THRESHOLD" (default 70)
39. --node_exporter.caCertFile string              node_exporter ca cert file path. Env "TAOS_ADAPTER_NODE_EXPORTER_CA_CERT_FILE"
40. --node_exporter.certFile string                node_exporter cert file path. Env "TAOS_ADAPTER_NODE_EXPORTER_CERT_FILE"
41. --node_exporter.db string                      node_exporter db name. Env "TAOS_ADAPTER_NODE_EXPORTER_DB" (default "node_exporter")
42. --node_exporter.enable                         enable node_exporter. Env "TAOS_ADAPTER_NODE_EXPORTER_ENABLE"
43. --node_exporter.gatherDuration duration        node_exporter gather duration. Env "TAOS_ADAPTER_NODE_EXPORTER_GATHER_DURATION" (default 5s)
44. --node_exporter.httpBearerTokenString string   node_exporter http bearer token. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_BEARER_TOKEN_STRING"
45. --node_exporter.httpPassword string            node_exporter http password. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_PASSWORD"
46. --node_exporter.httpUsername string            node_exporter http username. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_USERNAME"
47. --node_exporter.insecureSkipVerify             node_exporter skip ssl check. Env "TAOS_ADAPTER_NODE_EXPORTER_INSECURE_SKIP_VERIFY" (default true)
48. --node_exporter.keyFile string                 node_exporter cert key file path. Env "TAOS_ADAPTER_NODE_EXPORTER_KEY_FILE"
49. --node_exporter.password string                node_exporter password. Env "TAOS_ADAPTER_NODE_EXPORTER_PASSWORD" (default "taosdata")
50. --node_exporter.responseTimeout duration       node_exporter response timeout. Env "TAOS_ADAPTER_NODE_EXPORTER_RESPONSE_TIMEOUT" (default 5s)
51. --node_exporter.ttl int                        node_exporter data ttl. Env "TAOS_ADAPTER_NODE_EXPORTER_TTL"
52. --node_exporter.urls strings                   node_exporter urls. Env "TAOS_ADAPTER_NODE_EXPORTER_URLS" (default [http://localhost:9100])
53. --node_exporter.user string                    node_exporter user. Env "TAOS_ADAPTER_NODE_EXPORTER_USER" (default "root")
54. --opentsdb.enable                              enable opentsdb. Env "TAOS_ADAPTER_OPENTSDB_ENABLE" (default true)
55. --opentsdb_telnet.batchSize int                opentsdb_telnet batch size. Env "TAOS_ADAPTER_OPENTSDB_TELNET_BATCH_SIZE" (default 1)
56. --opentsdb_telnet.dbs strings                  opentsdb_telnet db names. Env "TAOS_ADAPTER_OPENTSDB_TELNET_DBS" (default [opentsdb_telnet,collectd_tsdb,icinga2_tsdb,tcollector_tsdb])
57. --opentsdb_telnet.enable                       enable opentsdb telnet,warning: without auth info(default false). Env "TAOS_ADAPTER_OPENTSDB_TELNET_ENABLE"
58. --opentsdb_telnet.flushInterval duration       opentsdb_telnet flush interval (0s means not valid) . Env "TAOS_ADAPTER_OPENTSDB_TELNET_FLUSH_INTERVAL"
59. --opentsdb_telnet.maxTCPConnections int        max tcp connections. Env "TAOS_ADAPTER_OPENTSDB_TELNET_MAX_TCP_CONNECTIONS" (default 250)
60. --opentsdb_telnet.password string              opentsdb_telnet password. Env "TAOS_ADAPTER_OPENTSDB_TELNET_PASSWORD" (default "taosdata")
61. --opentsdb_telnet.ports ints                   opentsdb telnet tcp port. Env "TAOS_ADAPTER_OPENTSDB_TELNET_PORTS" (default [6046,6047,6048,6049])
62. --opentsdb_telnet.tcpKeepAlive                 enable tcp keep alive. Env "TAOS_ADAPTER_OPENTSDB_TELNET_TCP_KEEP_ALIVE"
63. --opentsdb_telnet.ttl int                      opentsdb_telnet data ttl. Env "TAOS_ADAPTER_OPENTSDB_TELNET_TTL"
64. --opentsdb_telnet.user string                  opentsdb_telnet user. Env "TAOS_ADAPTER_OPENTSDB_TELNET_USER" (default "root")
65. --pool.idleTimeout duration                    Set idle connection timeout. Env "TAOS_ADAPTER_POOL_IDLE_TIMEOUT"
66. --pool.maxConnect int                          max connections to server. Env "TAOS_ADAPTER_POOL_MAX_CONNECT"
67. --pool.maxIdle int                             max idle connections to server. Env "TAOS_ADAPTER_POOL_MAX_IDLE"
68. --pool.maxWait int                             max count of waiting for connection. Env "TAOS_ADAPTER_POOL_MAX_WAIT"
69. --pool.waitTimeout int                         wait for connection timeout seconds. Env "TAOS_ADAPTER_POOL_WAIT_TIMEOUT" (default 60)
70. -P, --port int                                     http port. Env "TAOS_ADAPTER_PORT" (default 6041)
71. --prometheus.enable                            enable prometheus. Env "TAOS_ADAPTER_PROMETHEUS_ENABLE" (default true)
72. --restfulRowLimit int                          restful returns the maximum number of rows (-1 means no limit). Env "TAOS_ADAPTER_RESTFUL_ROW_LIMIT" (default -1)
73. --smlAutoCreateDB                              Whether to automatically create db when writing with schemaless. Env "TAOS_ADAPTER_SML_AUTO_CREATE_DB"
74. --statsd.allowPendingMessages int              statsd allow pending messages. Env "TAOS_ADAPTER_STATSD_ALLOW_PENDING_MESSAGES" (default 50000)
75. --statsd.db string                             statsd db name. Env "TAOS_ADAPTER_STATSD_DB" (default "statsd")
76. --statsd.deleteCounters                        statsd delete counter cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_COUNTERS" (default true)
77. --statsd.deleteGauges                          statsd delete gauge cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_GAUGES" (default true)
78. --statsd.deleteSets                            statsd delete set cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_SETS" (default true)
79. --statsd.deleteTimings                         statsd delete timing cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_TIMINGS" (default true)
80. --statsd.enable                                enable statsd. Env "TAOS_ADAPTER_STATSD_ENABLE"
81. --statsd.gatherInterval duration               statsd gather interval. Env "TAOS_ADAPTER_STATSD_GATHER_INTERVAL" (default 5s)
82. --statsd.maxTCPConnections int                 statsd max tcp connections. Env "TAOS_ADAPTER_STATSD_MAX_TCP_CONNECTIONS" (default 250)
83. --statsd.password string                       statsd password. Env "TAOS_ADAPTER_STATSD_PASSWORD" (default "taosdata")
84. --statsd.port int                              statsd server port. Env "TAOS_ADAPTER_STATSD_PORT" (default 6044)
85. --statsd.protocol string                       statsd protocol [tcp or udp]. Env "TAOS_ADAPTER_STATSD_PROTOCOL" (default "udp4")
86. --statsd.tcpKeepAlive                          enable tcp keep alive. Env "TAOS_ADAPTER_STATSD_TCP_KEEP_ALIVE"
87. --statsd.ttl int                               statsd data ttl. Env "TAOS_ADAPTER_STATSD_TTL"
88. --statsd.user string                           statsd user. Env "TAOS_ADAPTER_STATSD_USER" (default "root")
89. --statsd.worker int                            statsd write worker. Env "TAOS_ADAPTER_STATSD_WORKER" (default 10)
90. --taosConfigDir string                         load taos client config path. Env "TAOS_ADAPTER_TAOS_CONFIG_FILE"
91. --uploadKeeper.enable                          Whether to enable sending metrics to keeper. Env "TAOS_ADAPTER_UPLOAD_KEEPER_ENABLE" (default true)
92. --uploadKeeper.interval duration               send to Keeper interval. Env "TAOS_ADAPTER_UPLOAD_KEEPER_INTERVAL" (default 15s)
93. --uploadKeeper.retryInterval duration          retry interval. Env "TAOS_ADAPTER_UPLOAD_KEEPER_RETRY_INTERVAL" (default 5s)
94. --uploadKeeper.retryTimes uint                 retry times. Env "TAOS_ADAPTER_UPLOAD_KEEPER_RETRY_TIMES" (default 3)
95. --uploadKeeper.timeout duration                send to Keeper timeout. Env "TAOS_ADAPTER_UPLOAD_KEEPER_TIMEOUT" (default 5s)
96. --uploadKeeper.url string                      Keeper url. Env "TAOS_ADAPTER_UPLOAD_KEEPER_URL" (default "http://127.0.0.1:6043/adapter_report")
97. -V, --version                                      Print the version and exit

备注： 使用浏览器进行接口调用请根据实际情况设置如下跨源资源共享（CORS）参数：

1. AllowAllOrigins
2. AllowOrigins
3. AllowHeaders
4. ExposeHeaders
5. AllowCredentials
6. AllowWebSockets

如果不通过浏览器进行接口调用无需关心这几项配置。

关于 CORS 协议细节请参考：<https://www.w3.org/wiki/CORS_Enabled> 或 <https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS>。

示例配置文件参见 example/config/taosadapter.toml。

连接池参数说明

在使用 RESTful 接口请求时，系统将通过连接池管理 TDengine 连接。连接池可通过以下参数进行配置：

• pool.maxConnect：连接池允许的最大连接数，默认值为 2 倍 CPU 核心数。建议保持默认设置。
• pool.maxIdle：连接池中允许的最大空闲连接数，默认与 pool.maxConnect 相同。建议保持默认设置。
• pool.idleTimeout：连接空闲超时时间，默认永不超时。建议保持默认设置。
• pool.waitTimeout：从连接池获取连接的超时时间，默认设置为 60 秒。如果在超时时间内未能获取连接，将返回 HTTP 状态码 503。该参数从版本 3.3.3.0 开始提供。
• pool.maxWait：连接池中等待获取连接的请求数上限，默认值为 0，表示不限制。当排队请求数超过此值时，新的请求将返回 HTTP 状态码 503。该参数从版本 3.3.3.0 开始提供。

功能列表

• RESTful 接口 RESTful API
• 兼容 InfluxDB v1 写接口 <https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/write/>
• 兼容 OpenTSDB JSON 和 telnet 格式写入
• <http://opentsdb.net/docs/build/html/api_http/put.html>
• <http://opentsdb.net/docs/build/html/api_telnet/put.html>
• 与 collectd 无缝连接。 collectd 是一个系统统计收集守护程序，请访问 <https://collectd.org/> 了解更多信息。
• Seamless connection with StatsD。 StatsD 是一个简单而强大的统计信息汇总的守护程序。请访问 <https://github.com/statsd/statsd> 了解更多信息。
• 与 icinga2 的无缝连接。 icinga2 是一个收集检查结果指标和性能数据的软件。请访问 <https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer> 了解更多信息。
• 与 tcollector 无缝连接。 TCollector是一个客户端进程，从本地收集器收集数据，并将数据推送到 OpenTSDB。请访问 <http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html> 了解更多信息。
• 无缝连接 node_exporter。 node_export 是一个机器指标的导出器。请访问 <https://github.com/prometheus/node_exporter> 了解更多信息。
• 支持 Prometheus remote_read 和 remote_write。 remote_read 和 remote_write 是 Prometheus 数据读写分离的集群方案。请访问<https://prometheus.io/blog/2019/10/10/remote-read-meets-streaming/#remote-apis> 了解更多信息。
• 获取 table 所在的虚拟节点组（VGroup）的 VGroup ID。

接口

TDengine RESTful 接口

您可以使用任何支持 http 协议的客户端通过访问 RESTful 接口地址 http://<fqdn>:6041/rest/sql 来写入数据到 TDengine 或从 TDengine 中查询数据。细节请参考REST API 文档。

InfluxDB

您可以使用任何支持 http 协议的客户端访问 Restful 接口地址 http://<fqdn>:6041/influxdb/v1/write 来写入 InfluxDB 兼容格式的数据到 TDengine。

支持 InfluxDB 参数如下：

• db 指定 TDengine 使用的数据库名
• precision TDengine 使用的时间精度
• u TDengine 用户名
• p TDengine 密码
• ttl 自动创建的子表生命周期，以子表的第一条数据的 TTL 参数为准，不可更新。更多信息请参考创建表文档的 TTL 参数。

注意： 目前不支持 InfluxDB 的 token 验证方式，仅支持 Basic 验证和查询参数验证。 示例： curl —request POST <http://127.0.0.1:6041/influxdb/v1/write?db=test> —user “root:taosdata” —data-binary “measurement,host=host1 field1=2i,field2=2.0 1577836800000000000”

OpenTSDB

您可以使用任何支持 http 协议的客户端访问 Restful 接口地址 http://<fqdn>:6041/<APIEndPoint> 来写入 OpenTSDB 兼容格式的数据到 TDengine。EndPoint 如下：

1. /opentsdb/v1/put/json/<db>
2. /opentsdb/v1/put/telnet/<db>

collectd

配置 taosAdapter

配置 taosAdapter 接收 collectd 数据的方法：

• 在 taosAdapter 配置文件（默认位置为 /etc/taos/taosadapter.toml）中使能配置项

1. ...
2. [opentsdb_telnet]
3. enable = true
4. maxTCPConnections = 250
5. tcpKeepAlive = false
6. dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"]
7. ports = [6046, 6047, 6048, 6049]
8. user = "root"
9. password = "taosdata"
10. ...

其中 taosAdapter 默认写入的数据库名称为 collectd，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。

• 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 collectd 数据功能，具体细节请参考 taosAdapter 的参考手册

配置 collectd

collectd 使用插件机制可以以多种形式将采集到的监控数据写入到不同的数据存储软件。TDengine 支持直接采集插件和 write_tsdb 插件。

配置接收直接采集插件数据

修改 collectd 配置文件（默认位置 /etc/collectd/collectd.conf）相关配置项。

1. LoadPlugin network
2. <Plugin network>
3. Server "<taosAdapter's host>" "<port for collectd direct>"
4. </Plugin>

其中 <taosAdapter’s host> 填写运行 taosAdapter 的服务器域名或 IP 地址。<port for collectd direct> 填写 taosAdapter 用于接收 collectd 数据的端口（默认为 6045）。

示例如下：

1. LoadPlugin network
2. <Plugin network>
3. Server "127.0.0.1" "6045"
4. </Plugin>

配置 write_tsdb 插件数据

修改 collectd 配置文件（默认位置 /etc/collectd/collectd.conf）相关配置项。

1. LoadPlugin write_tsdb
2. <Plugin write_tsdb>
3. <Node>
4. Host "<taosAdapter's host>"
5. Port "<port for collectd write_tsdb plugin>"
6. ...
7. </Node>
8. </Plugin>

其中 <taosAdapter’s host> 填写运行 taosAdapter 的服务器域名或 IP 地址。<port for collectd write_tsdb plugin> 填写 taosAdapter 用于接收 collectd write_tsdb 插件的数据（默认为 6047）。

1. LoadPlugin write_tsdb
2. <Plugin write_tsdb>
3. <Node>
4. Host "127.0.0.1"
5. Port "6047"
6. HostTags "status=production"
7. StoreRates false
8. AlwaysAppendDS false
9. </Node>
10. </Plugin>

然后重启 collectd：

1. systemctl restart collectd

StatsD

配置 taosAdapter

配置 taosAdapter 接收 StatsD 数据的方法：

• 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项

1. ...
2. [statsd]
3. enable = true
4. port = 6044
5. db = "statsd"
6. user = "root"
7. password = "taosdata"
8. worker = 10
9. gatherInterval = "5s"
10. protocol = "udp"
11. maxTCPConnections = 250
12. tcpKeepAlive = false
13. allowPendingMessages = 50000
14. deleteCounters = true
15. deleteGauges = true
16. deleteSets = true
17. deleteTimings = true
18. ...

其中 taosAdapter 默认写入的数据库名称为 statsd，也可以修改 taosAdapter 配置文件 db 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。

• 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 StatsD 数据功能，具体细节请参考 taosAdapter 的参考手册

配置 StatsD

使用 StatsD 需要下载其源代码。其配置文件请参考其源代码下载到本地的根目录下的示例文件 exampleConfig.js 进行修改。其中 <taosAdapter’s host> 填写运行 taosAdapter 的服务器域名或 IP 地址，<port for StatsD> 请填写 taosAdapter 接收 StatsD 数据的端口（默认为 6044）。

1. backends 部分添加 "./backends/repeater"
2. repeater 部分添加 { host:'<taosAdapter's host>', port: <port for StatsD>}

示例配置文件：

1. {
2. port: 8125
3. , backends: ["./backends/repeater"]
4. , repeater: [{ host: '127.0.0.1', port: 6044}]
5. }

增加如下内容后启动 StatsD（假设配置文件修改为 config.js）。

1. npm install
2. node stats.js config.js &

icinga2 OpenTSDB writer

配置 taosAdapter

配置 taosAdapter 接收 icinga2 数据的方法：

• 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项

1. ...
2. [opentsdb_telnet]
3. enable = true
4. maxTCPConnections = 250
5. tcpKeepAlive = false
6. dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"]
7. ports = [6046, 6047, 6048, 6049]
8. user = "root"
9. password = "taosdata"
10. ...

其中 taosAdapter 默认写入的数据库名称为 icinga2，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过 taosAdapter 需重新启动。

• 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 icinga2 数据功能，具体细节请参考 taosAdapter 的参考手册

配置 icinga2

• 使能 icinga2 的 opentsdb-writer（参考链接 https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer）
• 修改配置文件 /etc/icinga2/features-enabled/opentsdb.conf 填写 <taosAdapter’s host> 为运行 taosAdapter 的服务器的域名或 IP 地址，<port for icinga2> 填写 taosAdapter 支持接收 icinga2 数据的相应端口（默认为 6048）

1. object OpenTsdbWriter "opentsdb" {
2. host = "<taosAdapter's host>"
3. port = <port for icinga2>
4. }

示例文件：

1. object OpenTsdbWriter "opentsdb" {
2. host = "127.0.0.1"
3. port = 6048
4. }

TCollector

配置 taosAdapter

配置 taosAdapter 接收 TCollector 数据的方法：

• 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项

1. ...
2. [opentsdb_telnet]
3. enable = true
4. maxTCPConnections = 250
5. tcpKeepAlive = false
6. dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"]
7. ports = [6046, 6047, 6048, 6049]
8. user = "root"
9. password = "taosdata"
10. ...

其中 taosAdapter 默认写入的数据库名称为 tcollector，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。

• 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 tcollector 数据功能，具体细节请参考 taosAdapter 的参考手册

配置 TCollector

使用 TCollector 需下载其源代码。其配置项在其源代码中。注意：TCollector 各个版本区别较大，这里仅以当前 master 分支最新代码 (git commit: 37ae920) 为例。

修改 collectors/etc/config.py 和 tcollector.py 两个文件中相应内容。将原指向 OpenTSDB 宿主机的地址修改为 taosAdapter 被部署的服务器域名或 IP 地址，修改端口为 taosAdapter 支持 TCollector 使用的相应端口（默认为 6049）。

示例为源代码修改内容的 git diff 输出：

1. index e7e7a1c..ec3e23c 100644
2. --- a/collectors/etc/config.py
3. +++ b/collectors/etc/config.py
4. @@ -59,13 +59,13 @@ def get_defaults():
5. 'http_password': False,
6. 'reconnectinterval': 0,
7. 'http_username': False,
8. -        'port': 4242,
9. +        'port': 6049,
10. 'pidfile': '/var/run/tcollector.pid',
11. 'http': False,
12. 'http_api_path': "api/put",
13. 'tags': [],
14. 'remove_inactive_collectors': False,
15. -        'host': '',
16. +        'host': '127.0.0.1',
17. 'logfile': '/var/log/tcollector.log',
18. 'cdir': default_cdir,
19. 'ssl': False,
20. diff --git a/tcollector.py b/tcollector.py
21. index 21f9b23..4c71ba2 100755
22. --- a/tcollector.py
23. +++ b/tcollector.py
24. @@ -64,7 +64,7 @@ ALIVE = True
25. # exceptions, something is not right and tcollector will shutdown.
26. # Hopefully some kind of supervising daemon will then restart it.
27. MAX_UNCAUGHT_EXCEPTIONS = 100
28. -DEFAULT_PORT = 4242
29. +DEFAULT_PORT = 6049
30. MAX_REASONABLE_TIMESTAMP = 2209212000  # Good until Tue  3 Jan 14:00:00 GMT 2040
31. # How long to wait for datapoints before assuming
32. # a collector is dead and restarting it
33. @@ -943,13 +943,13 @@ def parse_cmdline(argv):
34. 'http_password': False,
35. 'reconnectinterval': 0,
36. 'http_username': False,
37. -            'port': 4242,
38. +            'port': 6049,
39. 'pidfile': '/var/run/tcollector.pid',
40. 'http': False,
41. 'http_api_path': "api/put",
42. 'tags': [],
43. 'remove_inactive_collectors': False,
44. -            'host': '',
45. +            'host': '127.0.0.1',
46. 'logfile': '/var/log/tcollector.log',
47. 'cdir': default_cdir,
48. 'ssl': False,

node_exporter

Prometheus 使用的由 *NIX 内核暴露的硬件和操作系统指标的输出器

• 启用 taosAdapter 的配置 node_exporter.enable
• 设置 node_exporter 的相关配置
• 重新启动 taosAdapter

prometheus

配置 Prometheus 是通过编辑 Prometheus 配置文件 prometheus.yml （默认位置 /etc/prometheus/prometheus.yml）完成的。

配置第三方数据库地址

将其中的 remote_read url 和 remote_write url 指向运行 taosAdapter 服务的服务器域名或 IP 地址，REST 服务端口（taosAdapter 默认使用 6041），以及希望写入 TDengine 的数据库名称，并确保相应的 URL 形式如下：

• remote_read url : http://<taosAdapter's host>:<REST service port>/prometheus/v1/remote_read/<database name>
• remote_write url : http://<taosAdapter's host>:<REST service port>/prometheus/v1/remote_write/<database name>

配置 Basic 验证

• username： <TDengine’s username>
• password： <TDengine’s password>

prometheus.yml 文件中 remote_write 和 remote_read 相关部分配置示例

1. remote_write:
2. - url: "http://localhost:6041/prometheus/v1/remote_write/prometheus_data"
3. basic_auth:
4. username: root
5. password: taosdata

7. remote_read:
8. - url: "http://localhost:6041/prometheus/v1/remote_read/prometheus_data"
9. basic_auth:
10. username: root
11. password: taosdata
12. remote_timeout: 10s
13. read_recent: true

获取 table 的 VGroup ID

可以访问 http 接口 http://<fqdn>:6041/rest/vgid?db=<db>&table=<table> 获取 table 的 VGroup ID。

内存使用优化方法

taosAdapter 将监测自身运行过程中内存使用率并通过两个阈值进行调节。有效值范围为 -1 到 100 的整数，单位为系统物理内存的百分比。

• pauseQueryMemoryThreshold
• pauseAllMemoryThreshold

当超过 pauseQueryMemoryThreshold 阈值时时停止处理查询请求。

http 返回内容：

• code 503
• body “query memory exceeds threshold”

当超过 pauseAllMemoryThreshold 阈值时停止处理所有写入和查询请求。

http 返回内容：

• code 503
• body “memory exceeds threshold”

当内存回落到阈值之下时恢复对应功能。

状态检查接口 http://<fqdn>:6041/-/ping

• 正常返回 code 200
• 无参数 如果内存超过 pauseAllMemoryThreshold 将返回 code 503
• 请求参数 action=query 如果内存超过 pauseQueryMemoryThreshold 或 pauseAllMemoryThreshold 将返回 code 503

对应配置参数

1. monitor.collectDuration              监测间隔                                    环境变量 "TAOS_MONITOR_COLLECT_DURATION" (默认值 3s)
2. monitor.incgroup                     是否是cgroup中运行(容器中运行设置为 true)      环境变量 "TAOS_MONITOR_INCGROUP"
3. monitor.pauseAllMemoryThreshold      不再进行插入和查询的内存阈值                   环境变量 "TAOS_MONITOR_PAUSE_ALL_MEMORY_THRESHOLD" (默认值 80)
4. monitor.pauseQueryMemoryThreshold    不再进行查询的内存阈值                        环境变量 "TAOS_MONITOR_PAUSE_QUERY_MEMORY_THRESHOLD" (默认值 70)

您可以根据具体项目应用场景和运营策略进行相应调整，并建议使用运营监控软件及时进行系统内存状态监控。负载均衡器也可以通过这个接口检查 taosAdapter 运行状态。

taosAdapter 监控指标

taosAdapter 采集 REST/WebSocket 相关请求的监控指标。将监控指标上报给 taosKeeper，这些监控指标会被 taosKeeper 写入监控数据库，默认是 log 库，可以在 taoskeeper 配置文件中修改。以下是这些监控指标的详细介绍。

adapter_requests 表

adapter_requests 记录 taosadapter 监控数据。

结果返回条数限制

taosAdapter 通过参数 restfulRowLimit 来控制结果的返回条数，-1 代表无限制，默认无限制。

该参数控制以下接口返回

• http://<fqdn>:6041/rest/sql
• http://<fqdn>:6041/prometheus/v1/remote_read/:db

配置 http 返回码

taosAdapter 通过参数 httpCodeServerError 来设置当 C 接口返回错误时是否返回非 200 的 http 状态码。当设置为 true 时将根据 C 返回的错误码返回不同 http 状态码。具体见 HTTP 响应码。

配置 schemaless 写入是否自动创建 DB

taosAdapter 从 3.0.4.0 版本开始，提供参数 smlAutoCreateDB 来控制在 schemaless 协议写入时是否自动创建 DB。默认值为 false 不自动创建 DB，需要用户手动创建 DB 后进行 schemaless 写入。

故障解决

您可以通过命令 systemctl status taosadapter 来检查 taosAdapter 运行状态。

您也可以通过设置 —logLevel 参数或者环境变量 TAOS_ADAPTER_LOG_LEVEL 来调节 taosAdapter 日志输出详细程度。有效值包括： panic、fatal、error、warn、warning、info、debug 以及 trace。

如何从旧版本 TDengine 迁移到 taosAdapter

在 TDengine server 2.2.x.x 或更早期版本中，taosd 进程包含一个内嵌的 http 服务。如前面所述，taosAdapter 是一个使用 systemd 管理的独立软件，拥有自己的进程。并且两者有一些配置参数和行为是不同的，请见下表：