CDH-TSQL详解（超详细）

---

前言

本文主要介绍了TSQL（Time Series Query Language）的语法和使用方法。TSQL是一种用于从Cloudera Manager时间序列数据存储中检索时间序列数据的查询语言。通过使用TSQL，我们可以方便地从CDH的API中检索CDH集群各项服务的指标。本文首先介绍了TSQL的基本概念和使用方法，然后详细介绍了TSQL的语法和各种功能，包括指标表达式、predicate、时间过滤等。最后，本文还介绍了TSQL中的一些属性，这些属性可以帮助我们更精确地检索所需的时间序列数据。

---

一、TSQL简介

1. TSQL是什么

TSQL是Time Series Query Language(时间序列查询语言)的简称。TSQL用于指定从 Cloudera Manager 时间序列数据存储中检索时间序列数据的语句。 一般用于从CDH的API中检索CDH集群各项服务的指标。

2. 用法

API前缀：http://localhost:7180/api/v33

/timeseries?query=TSQL statement

注意：若使用curl命令来发送请求，需要把TSQL statement中间的空格编码为UTF-8字符集。

3. TSQL的常见的查询方法

3.1 检索角色类型为 DataNode 的所有指标的时间序列数据。

select * where roleType=DATANODE

使用示例：

curl -u admin:admin -X GET --header 'Accept: application/json' 'http://localhost:7180/api/v33/timeseries?query=select%20*%20where%20roleType=DATANODE'

3.2 检索角色类型为 DataNode 的 cpu_user_rate 指标的时间序列数据

select cpu_user_rate where roleType=DATANODE

使用示例：

curl -u admin:admin -X GET --header 'Accept: application/json' 'http://localhost:7180/api/v33/timeseries?query=select%20cpu_user_rate%20where%20roleType=DATANODE'

3.3 检索所有实体的health_bad_rate指标的时间序列数据

select health_bad_rate

使用示例：

curl -u admin:admin -X GET --header 'Accept: application/json' 'http://localhost:7180/api/v33/timeseries?query=select%20health_bad_rate'

---

二、TSQL语法

1. 语法

SELECT [metric expression] WHERE [predicate]

2. TSQL语句的特点

1. 语句 select * 是无效的。SELECT * WHERE [predicate]是有效的。在[metric expression]不是*的情况下可以省略[predicate]。
2. 大小写不敏感。
3. 可以使用分号将多个TSQL语句连接起来。例如：select cpu_user_rate where roleType=DATANODE; select health_bad_rate

3. 指标表达式(metric expression)

1. 指标表达式生成时间序列是一个由逗号分隔的一个或多个指标表达式语句的列表。指标表达式语句是指标名称、指标表达式函数或常数值，由一个或多个指标表达式操作符连接。

2. 指标表达式支持二进制操作符：+，-，*，/。

4. 指标表达式函数

函数	是否返回标量(Y/N)	描述
avg(metric expression)	N	计算时间序列的平均值
count_service_roles()	Y	返回角色的数量。1. count_service_roles(roleType, roleState) - 返回指定roleType和roleState的角色数量。例如，count_service_roles(datanode, running) 返回正在运行的DataNode数量。2. count_service_roles(roleType) - 返回具有指定roleType的角色数量。3. count_service_roles() - 返回角色总数。例如，select events_critical where count_service_roles() > 100 将返回角色数大于100时 event_critical 指标的数据。
dt(metric expression)	N	负值的导数。表示每秒指标表达式的变化。
dt0(metric expression)	N	跳过负值的导数（用于处理计数器重置）
getClusterFact(string factName, double defaultValue)	Y	获取有关集群的事实。目前支持一个事实：numCores（核心数）。如果无法确定核心数，则返回defaultValue。
getHostFact(string factName, double defaultValue)	Y	获取有关主机的事实。目前支持一个事实：numCores（核心数）。如果无法确定核心数，则返回defaultValue。
greatest(metric expression, scalar metric expression)	N	比较两个指标表达式，其中一个是标量指标表达式。返回一个时间序列，其中每个点的结果是通过评估 max(point, scalar metric expression) 得到的。
integral(metric expression)	N	计算流的积分值，并返回一个时间序列流，其中每个数据点是原始流对应数据点的积分值。例如，select integral(maps_failed_rate) 将返回maps失败数量的计数。
counter_delta(metric expression)	N	计算流中计数器的差值，并返回一个时间序列流，其中每个数据点是原始流中相应数据点的计数器值与前一个数据点的差值。例如：select counter_delta(maps_failed_rate)返回失败maps的数量。此方法比integral()函数更准确。注意事项：1. 此函数仅适用于单个时间序列流。对于跨实体聚合的流，继续使用integral()函数。2. 如果您将此方法应用于版本低于5.7的Cloudera Manager创建的时间序列流，Cloudera Manager会使用integral()函数填充旧数据点。
last(metric expression)	Y	返回时间序列的最后一个数据点。例如，要检索cpu_percent指标时间序列的最后一个数据点，使用表达式 select last(cpu_percent)。
least(metric expression, scalar metric expression)	N	比较两个指标表达式，其中一个是标量指标表达式。返回一个时间序列，其中每个点是评估min(point，scalar metric expression)的结果。
max(metric expression)	Y	计算时间序列的最大值。例如：select max(cpu_percent)
min(metric expression)	Y	计算时间序列的最小值。
moving_avg(metric expression, time_window_sec)	N	计算时间序列在以秒为单位指定的时间窗口time_window_sec上的移动平均值(2、0.1等)
stats(metric expression, stats name)	N	某些时间序列流对每个数据点都有额外的统计信息。这些包括time-series streams, cross-entity aggregates, 和 rate指标。以下统计信息可用于聚合和跨实体聚合:max、min、avg、std_dev和sample。对于rate度量，可以使用“计数器”统计信息获得底层计数器值。例如，stats(fd_open_across_datanode, max)或stats(swap_out_rate, counter)。
sum(metric expression)	Y	计算时间序列的和值。

5. predicate

predicate用于限制返回序列中的流的数量，并可以采用以下形式之一：

5.1 time_series_attribute operator value

• time_series_attribute 是支持的属性之一。
• operator 是 = 和 rlike 之一。
• value 是一个属性值，符合以下约束条件：
  • 对于包含空格或以 xxxName 形式（如 displayName）的属性值，使用带引号的字符串。
  • rlike 运算符对应的值必须用引号括起来。例如：hostname rlike "host[0-2]+.*"。
  • value 支持任何正则表达式。

5.2 scalar_producing_function(metric_expression) comparator number

• scalar_producing_function 是任何接受时间序列并产生标量结果的函数。例如： min 或 max。
• metric_expression 是有效的指标表达式。
• comparator是比较运算符：<, <=, =, !=, >=, >。
• number 可以是任何数字表达式或带单位的数字表达式。例如: 3、3mb、3s 都是有效数字表示法. 合法单位有:
  • 时间 - ms (毫秒), s (秒), m (分钟), h (小时)，d(天)。
  • 字节 - b(字节)，kb 或 kib(千字节)，mb 或 mib(兆字节)，gb 或 gib(吉字节），tb 或 tib，pb 或 pib。
  • 每秒钟传输的字节数 - 字节和时间：bps, kbps, kibps, mbps，mibps等。例如，每秒传输5千字节为 5kb/s。
  • 字节数乘以时间 - 字节和时间的组合：bms、bs、bm、bh、bd 等。例如，每秒传输5千字节为 5ks 或者 5kis。
• 可以使用 AND 和 OR 运算符来组合复合predicate。

5.3 根据时间过滤

5.3.1 按天过滤

day in()表达式接受一个参数，该参数包含一个用逗号分隔的星期列表。一周的天数从数字1到数字7。
语法:

day in (#, #, ...)

例如，下面的表达式将流限制为只在工作日发生的事件:

day in (1,2,3,4,5)

在WHERE子句后面添加日期或时间范围表达式。不使用AND关键字。例如:

select fd_open where category = ROLE and roleType = SERVICEMONITOR day in (1,2,3,4,5) 

5.3.2 按小时过滤

hour in 表达式接受一个参数，该参数的时间范围由冒号分隔。有效值为0 ~ 23的整数.
语法：

hour in [#:#]

例如，下面的表达式将流限制为只发生在上午9:00到下午5:00之间的事件:

hour in [9:17]

表达式中组合day in和hour。总是将日表达式放在小时表达式之前。以下示例将流限制为工作日上午9:00到下午5:00:

select fd_open where category = ROLE and roleType = SERVICEMONITOR day in (1,2,3,4,5) hour in [9:17]

---

三、属性

1. 时间序列属性

属性名和大多数属性值不区分大小写。displayName和serviceType是两个区分大小写的属性。

名称	描述
active	指示要检索的实体是否必须是活动的。非活动实体是指已从集群中移除或删除的实体。默认情况下，只检索活动实体(即active=true)。要访问已删除或已移除实体的时间序列，请在查询中指定active=false。例如：fd_open WHERE roleType=DATANODE and active=false
agentName	Flume代理名称
applicationName	Cloudera Manager监视守护进程的应用程序名称
cacheId	HDFS缓存指令ID
category	1. 查询返回的实体类别:CLUSTER、DIRECTORY、DISK、FILESYSTEM、FLUME_SOURCE、FLUME_CHANNEL、FLUME_SINK、HOST、HTABLE、IMPALA_QUERY_STREAM、NETWORK_INTERFACE、ROLE、SERVICE、USER、YARN_APPLICATION_STREAM、YARN_QUEUE。有些指标是为不止一种类型的实体收集的。例如，total_cpu_user收集类别是HOST和ROLE的实体。要检索仅针对主机的数据，使用: total_cpu_user where category=HOST 2. ROLE类别适用于所有角色类型。SERVICE类别适用于所有服务类型。例如，要检索host1上所有角色的已提交堆，使用:jvm_committed_heap_mb where category=ROLE and hostname=“host1”
clusterDisplayName	用户自定义的集群显示名称
clusterName	集群ID。要通过显示名称指定集群，请使用clusterDisplayName属性。
componentName	Flume组件名称。例如，channel1, sink1。
device	磁盘设备名称。例如，sda。
entityName	实体名称，显示名加上唯一标识符。例如:HDFS-1-DATANODE-692d141f436ce70aac080aedbe83f887。
expired	指示HDFS缓存指令是否过期的布尔值
groupName	用户组名
hbaseNamespace	HBase命名空间的名称
hostId	主机ID(唯一且不可改变)，Cloudera Manager中主机的规范标识符。例如:3d645222-2f7e-4895-ae51-cd43b91f1e7a。
hostname	主机名称
hregionName	HBase的区域名称。例如:4cd887662e5c2f3cd5dd227bb03dd760
hregionStartTimeMs	从Cloudera Manager监控开始收集HBase区域的指标到UNIX的毫秒数
htableName	HBase表名
iface	网络接口名称。例如eth0
logicalPartition	指示磁盘是否为逻辑分区的布尔值。适用于磁盘实体类型。
mountpoint	挂载点名称。例如:/var、/mnt/homes
nameserviceName	HDFS名称服务的名称
ownerName	所有者用户名
partition	分区名称。适用于分区实体类型。
path	与时间序列实体相关联的文件系统路径
poolName	池名。例如hdfs cache pool, yarn pool
queueName	YARN队列的名称
rackId	挂载点ID。例如，/default。
roleConfigGroup	角色所属的角色组
roleName	角色ID。例如HBASE-1-REGIONSERVER-0b0ad09537621923e2b460e5495569e7。
roleState	角色状态:BUSY、HISTORY_NOT_AVAILABLE、NA、RUNNING、STARTING、STOPPED、STOPPED、UNKNOWN
roleType	角色类型:ACTIVITYMONITOR、AGENT、ALERTPUBLISHER、BEESWAX_SERVER、CATALOGSERVER、DATANODE、EVENTSERVER、FAILOVERCONTROLLER、HBASE_INDEXER、HBASERESTSERVER、HBASETHRIFTSERVER、hiveetastore、HIVESERVER2、HOSTMONITOR、HTTPFS、HUESERVER、IMPALAD、JOBHISTORY、JOBTRACKER、JOURNALNODE、KT_RENEWER、LLAMA、MASTER、NAVIGATOR、REGIONSERVER、SERVICEMONITOR、NAMENODE、NODEMANAGER、REPORTSMANAGER、SECONDARYNAMENODE、SERVER、SOLR_SERVER、SQOOP_SERVER、STATESTORE、TASKTRACKER。
rollup	时间序列存储表汇总类型
schedulerType	与池服务关联的调度器类型
serviceDisplayName	自定义的服务实体显示名称
serviceName	服务ID。要通过显示名称指定服务，请使用serviceDisplayName属性。
serviceState	服务状态:HISTORY_NOT_AVAILABLE、NA、RUNNING、STARTING、STOPPED、STOPPED、UNKNOWN
serviceType	服务类型:ACCUMULO、FLUME、HDFS、HBASE、HIVE、HUE、IMPALA、KS_INDEXER、MAPREDUCE、MGMT、OOZIE、SOLR、SPARK、SQOOP、YARN、ZOOKEEPER
solrCollectionName	Solr集合名称。例如，my_collection。
solrReplicaName	Solr副本名称。例如，my_collection_shard1_replica1。
solrShardName	Solr分片名称。例如，shard1。
systemTable	一个布尔值，表示该HBase表是否是系统表。
tableName	表的名称
userName	用户名
version	集群的版本号。可以是支持的任意CDH主版本。

2. 时间序列实体及其属性

下表显示了可以出现在查询语句的predicate("where"子句)中的实体和相关属性。

实体	属性
All Roles	roleType, hostId, hostname, rackId, serviceType, serviceName
All Services	serviceName, serviceType, clusterId, version, serviceDisplayName, clusterDisplayName
Agent	roleType, hostId, hostname, rackId, serviceType, serviceName, clusterId, version, agentName, serviceDisplayName, clusterDisplayName
Cluster	clusterId, version, clusterDisplayName
Directory	roleName, hostId, path, roleType, hostname, rackId, serviceType, serviceName, clusterId, version, agentName, hostname, clusterDisplayName
Disk	device, logicalPartition, hostId, rackId, clusterId, version, hostname, clusterDisplayName
File System	hostId, mountpoint, rackId, clusterId, version, partition, hostname, clusterDisplayName
Flume Channel	serviceName, hostId, rackId, roleName, flumeComponent, roleType, serviceType, clusterId, version, agentName, serviceDisplayName, clusterDisplayName
Flume Sink	serviceName, hostId, rackId, roleName, flumeComponent, roleType, serviceType, clusterId, version, agentName, serviceDisplayName, clusterDisplayName
Flume Source	serviceName, hostId, rackId, roleName, flumeComponent, roleType, serviceType, clusterId, version, agentName, serviceDisplayName, clusterDisplayName
HDFS Cache Pool	serviceName, poolName, nameserviceName, serviceType, clusterId, version, groupName, ownerName, serviceDisplayName, clusterDisplayName
HNamespace	serviceName, namespaceName, serviceType, clusterId, version, serviceDisplayName, clusterDisplayName
Host	hostId, rackId, clusterId, version, hostname, clusterDisplayName
HRegion	htableName, hregionName, hregionStartTimeMs, namespaceName, serviceName, tableName, serviceType, clusterId, version, roleType, hostname, roleName, hostId, rackId , serviceDisplayName, clusterDisplayName
HTable	namespaceName, serviceName, tableName, serviceType, clusterId, version, serviceDisplayName, clusterDisplayName
Network	Interface hostId, networkInterface, rackId, clusterId, version, hostname, clusterDisplayName
Rack	rackId
Service	serviceName, serviceType, clusterId, serviceDisplayName
Solr Collection	serviceName, serviceType, clusterId, version, serviceDisplayName, clusterDisplayName
Solr Replica	serviceName, solrShardName, solrReplicaName, solrCollectionName, serviceType, clusterId, version, roleType, hostId, hostname, rackId, roleName, serviceDisplayName, clusterDisplayName
Solr Series	Shard serviceName, solrCollectionName, solrShardName, serviceType, clusterId, version, serviceDisplayName, clusterDisplayName
Time	Table tableName, roleName, roleType, applicationName, rollup, path
User	userName
YARN Pool	serviceName, queueName, schedulerType

---

总结

通过学习本文，我们了解了TSQL的基本概念和使用方法，学会了如何使用TSQL从Cloudera Manager时间序列数据存储中检索时间序列数据。我们还详细了解了TSQL的语法和各种功能，包括指标表达式、predicate、时间过滤等。此外，我们还学习了TSQL中的一些属性，这些属性可以帮助我们更精确地检索所需的时间序列数据。

希望本教程对您有所帮助！如有任何疑问或问题，请随时在评论区留言。感谢阅读！