1. 简介

提供统一的 SQL 接口查询所有类型的观测数据，可作为 Grafana 的 DataSource，或基于此实现自己的 GUI。

2. SQL 服务端点

获取服务端点端口号：

port=$(kubectl get --namespace deepflow -o jsonpath="{.spec.ports[0].nodePort}" services deepflow-server)

3. SQL 查询语句

3.1 获取所有数据库

SQL 语句：

show databases

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "sql=show databases"

3.2 获取指定数据库的所有表

SQL 语句：

show tables

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "db=${db_name}" \
    --data-urlencode "sql=show tables"

3.3 获取指定数据表中的 Tag

SQL 语句：

show tags from ${table_name}

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "db=${db_name}" \
    --data-urlencode "sql=show tags from ${table_name}"

输出示例：

{
  "OPT_STATUS": "SUCCESS",
  "DESCRIPTION": "",
  "result": {
    "columns": [
      "name",
      "client_name",
      "server_name",
      "display_name",
      "type" // int, int_enum, string, string_enum, resource_name, resource_id, ip
    ],
    "values": [
      ["chost", "chost_0", "chost_1", "云服务器", "resource_id"],
      [
        "chost_name",
        "chost_name_0",
        "chost_name_1",
        "云服务器名称",
        "resource_name"
      ]
    ]
  }
}

3.4 获取指定 Tag 的取值

3.4.1 获取 Tag 的所有取值

SQL 语句：

show tag ${tag_name} values from ${table_name}

上述语句也可通过 limit 和 offset 关键词减少返回的取值数量：

show tag ${tag_name} values from ${table_name} limit 100 offset 100

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "db=${db_name}" \
    --data-urlencode "sql=show tag ${tag_name} values from ${table_name}"

输出示例：

{
  "OPT_STATUS": "SUCCESS",
  "DESCRIPTION": "",
  "result": {
    "columns": ["value", "display_name", "uid"],
    "values": [[348, "deepflow", "i-2ze3bpa0o5cy8edplozi"]]
  }
}

3.4.2 使用 Tag 自身名称过滤

注意到上述 Tag 的取值会返回三列：value、display_name、uid。我们可以利用这些信息进行过滤，例如：

show tag ${tag_name} values from ${table_name} where display_name like '*abc*'

API 调用方式和输出示例同上。

3.4.3 使用其他 Tag 关联过滤

有时候我们希望使用 Tag 进行关联过滤，减少候选项取值范围。这个时候我们可以选择查询某个数据表，对 Tag1 进行过滤的同时对 Tag2 进行聚合。例如，我们希望查询所有 pod_cluster="cluster1" 中的 pod 名称：

SELECT pod FROM `network.1m` WHERE pod_cluster = 'cluster1' GROUP BY pod

以上语句会利用 flow_metrics 数据库中的 network.1m 表中的 pod_cluster 字段对 pod 的候选项进行过滤和分组。当然我们也可通过查询 DeepFlow 中的任意表来实现此需求，但应尽量避免使用数据量很大的表。另外，我们也可在 SQL 中加入时间等其他维度来加速查找：

SELECT pod FROM `network.1m` WHERE pod_cluster = 'cluster1' AND time > 1234567890 GROUP BY pod

注意：仅当 pod 中曾经有流量（且不使用 HostNetwork 时）才能在 flow_metrics 中查到数据。当我们在集成 Prometheus 或 Telegraf 数据以后，也可借用这其中恒定存在的指标来辅助获取 Tag 取值。例如，我们可使用 ext_metrics 中的 Prometheus 指标实现上述需求：

SELECT pod FROM `prometheus.kube_pod_start_time` WHERE pod_cluster = 'cluster1' GROUP BY pod

在 Grafana 中，我们也可利用上述能力实现 Variable 候选项的联动过滤，例如我们使用一个自定义的 Variable $cluster 和内置的 Variable $**from、$**to (opens new window) 对另一个 Variable pod 进行联动过滤：

• cluster 的值为 id 时, 使用 $cluster:

  cluster = [1, 2]
  result: 1, 2
  

  // Add 5 minutes before and after the time range to avoid frequent changes of candidates
  SELECT pod_id as `value`, pod as `display_name` FROM `network.1m` WHERE pod_cluster IN ($cluster) AND time >= ${__from:date:seconds}-500 AND time <= ${__to:date:seconds}+500 GROUP BY `value`
  

• cluster 的值为 name 时, 使用 ${cluster:singlequote}:

  cluster = [deepflow-a, deepflow-b]
  result: 'deepflow-a', 'deepflow-b'
  

  SELECT pod as `value`, pod as `display_name` FROM `network.1m` WHERE pod_cluster IN (${cluster:singlequote}) AND  time >= ${__from:date:seconds}-500 AND time <= ${__to:date:seconds}+500 GROUP BY `value`
  

3.5 获取指定数据表中的 Metrics

SQL 语句：

show metrics from ${table_name}

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "db=${db_name}" \
    --data-urlencode "sql=show metrics from ${table_name}"

3.6 查询观测数据

SQL 语句：

SELECT col_1, col_2, col_3 \
FROM   tbl_1 \
WHERE  col_4 = y \
GROUP BY col_1, col_2 \
HAVING   col_5 > 100 \
ORDER BY col_3 \
LIMIT 100

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "db=${db_name}" \
    --data-urlencode "sql=${sql}"

当db=flow_metric时，需要通过--data-urlencode "data_precision=${data_precision}"指定数据精度，data_precision的可选值为1m和1s。

4. SQL 查询函数

4.1 Tag 支持的函数

• enum
  • 说明：enum(observation_point) 将枚举字段转化为值
  • 示例：SELECT enum(observation_point) ...、... WHERE enum(observation_point) = 'xxx' ...
  • 注意：仅string_enum、int_enum类型的 Tag 支持

4.2 Metrics 支持的函数

执行如下 SQL 语句可获取所有的函数：

show metric function

API 调用方式：

curl -XPOST "http://${deepflow_server_node_ip}:${port}/v1/query/" \
    --data-urlencode "sql=show metrics functions"

5. SQL 语法

• 左值不支持空格、单引号、反引号
• 右值中的单引号，需要使用转义符 \ 进行转义