前言
本文主要介绍了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语句的特点
- 语句
select *是无效的。SELECT * WHERE [predicate]是有效的。在[metric expression]不是*的情况下可以省略[predicate]。 - 大小写不敏感。
- 可以使用分号将多个TSQL语句连接起来。例如：
select cpu_user_rate where roleType=DATANODE; select health_bad_rate
3. 指标表达式(metric expression)
-
指标表达式生成时间序列是一个由逗号分隔的一个或多个指标表达式语句的列表。指标表达式语句是指标名称、指标表达式函数或常数值，由一个或多个指标表达式操作符连接。
-
指标表达式支持二进制操作符：+，-，*，/。
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中的一些属性，这些属性可以帮助我们更精确地检索所需的时间序列数据。
