跳转至

观测云工具包 / 导出 DQL 查询数据函数

「导出 DQL 查询数据函数」是用于方便导出 DQL 数据的函数。

工作原理为：通过指定的 DQL 查询语句，从观测云查询数据，并导出到 DataFlux Func 的资源目录下。

导出成功后，用户可以前往 DataFlux Func「管理 / 文件管理器」下载。

如果找不到「文件管理器」，可以在「管理 / 实验性功能」中开启

1. 快速开始

自行编写启动代码，并调用相关函数，如：

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import guance_toolkit__api as guance_toolkit

@DFF.API('导出 gin 日志')
def run():
    # DQL 语句（注意不要指定时间范围）
    dql = '''L::re(`.*`):(log_time,message,message_length){ `source` IN ['gin'] }'''

    # 时间范围
    start_time = '2022-09-14T12:00:00+08:00'
    end_time   = '2022-09-14T12:00:10+08:00'

    # 工作空间 Token
    workspace_token = 'tkn_xxxxx'

    # 启动执行
    guance_toolkit.dql_export(dql=dql,
                              start_time=start_time,
                              end_time=end_time,
                              workspace_token=workspace_token)

您在实现自己的代码时，可以根据需要将部分导出参数作为函数的输入参数，实现更通用的导出函数或接口

完成代码后，在「管理 / 异步 API（旧版：批处理）」中为此函数创建一个「异步 API（旧版：批处理）」，并根据示例调用即可。

创建异步 API（旧版：批处理）并调用：

查看异步 API（旧版：批处理）执行日志：

获取异步 API（旧版：批处理）执行生成的文件：

2. dql_export(...)

guance_toolkit.dql_export(...) 函数用于将 DQL 查询结果保存至单个文件。

如需要将 DQL 查询结果切分保存，请参考 guance_toolkit.dql_export_split(...) 函数

参数列表：

参数 类型 必须 / 默认值 说明
dql str 必须 需要查询的 DQL 语句（不含时间范围）
start_time str 必须 符合 ISO 格式的开始时间，如："2022-01-01T00:00:00+08:00"
end_time str 必须 符合 ISO 格式的结束时间，如："2022-01-01T00:00:00+08:00"
workspace_token str 必须 工作空间 Token
guance_node str 观测云节点，默认国内杭州节点
详细见 观测云工具包 / 连接到其他观测云节点
file_path str 输出文件路径，资源目录下的相对路径，可在「管理 / 文件管理器」中查看
file_format str "jsonl" 输出文件格式
可选："jsonl", "csv"
time_format str "human" 输出 time 字段格式
可选："human", "iso", "timestamp", "timestamp_ms"
time_zone str "Asia/Shanghai" 输出 time 字段时区
query_limit int 10000 分页查询时的分页大小，单位条
interval int 自动按照时间分段查询，单位秒

自动重试

本函数基于 guance_toolkit__guance.OpenWay 来执行 DQL 查询，因此与 OpenWay 具有相同的自动重试处理。

自动分页

本函数在执行查询时，会自动使用 search_after 参数进行分页获取数据，默认每页 10000 条数据。

每次翻页都会同步写入导出文件，避免大量内存驻留。

分页大小可以通过 query_limit 参数调整，详见下文

file_path 参数

可以通过指定本参数选择文件的输出地址（「管理 / 文件管理器」下相对地址）。

默认输出地址为 guance_toolkit/gaunce-dql-export-{执行时间}.{输出格式}

如指定的地址以 / 结尾，表示输出至特定目录，文件名自动生成

如指定的地址中，文件名无扩展名或扩展名与输出格式不一致的，会自动追加扩展名。

假设当前时间为 2022-01-01 00:00:00；文件格式为 "jsonl"，那么：

file_path 参数值 说明 文件输出地址
不指定 默认 guance_toolkit/gaunce-dql-export-20220101_000000.jsonl
"my_folder/" 以 / 结尾 my_folder/gaunce-dql-export-20220101_000000.jsonl
"my_folder/data" 没有扩展名 my_folder/data.jsonl
"my_folder/data.csv" 与实际文件输出格式不符 my_folder/data.csv.jsonl

file_format 参数

可以通过指定本参数选择 JSONL 或 CSV 格式输出：

  • JSONL 性能及兼容性更好。但输出的文件适合作为数据供其他程序处理，不适合直接人眼阅读。
  • CSV 性能较差，且要求 DQL 返回的所有数据具有相同的字段，会存在编码问题。但输出的文件可以通过 Excel 等软件打开直接阅读。

因此，如需要导出少量数据作为报告阅读时，建议使用 CSV 格式输出；如需要备份数据时，建议使用 JSONL 格式输出。

time_format 参数

可以通过指定本参数自动转换 DQL 查询结果中的 time 字段格式。

假设 time 为 1640966400000（即：北京时间 2022-01-01 00:00:00），那么：

time_format 参数值 说明 time 字段输出值
不指定 默认 "2022-01-01 00:00:00"
"iso" ISO 标准格式 "2022-01-01T00:00:00+08:00"
"timestamp" UNIX 时间戳（秒） 1640966400
"timestamp_ms" UNIX 时间戳（毫秒） 1640966400000

query_limit 参数

如果需要导出的数据单条数据量过大，默认的分页配置（10000条/页）可能会产生 DQL 查询缓慢、超时、Func 运行内存占用过大等问题。

此时，可以额外指定分页大小 query_limit 参数，使程序按照指定的分页大小进行分页查询。

默认值 10000 已经可以满足绝大多数情况，改小本参数可能导致查询变得缓慢

interval 参数

如果需要导出的数据时间范围过大，直接执行可能导致 DQL 超时。

此时，可以额外指定时间间隔 interval 参数，使程序自动按照指定的时间间隔，将查询时间切分为多个小时间段依次查询。

interval 参数单位为秒，如指定 3600 则表示，在 start_time 和 end_time 范围内，按 1 小时分段查询导出。

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import guance_toolkit__api as guance_toolkit

@DFF.API('导出 gin 日志')
def run():
    # ...其他代码略

    # 启动执行
    guance_toolkit.dql_export(dql=dql,
                              start_time=start_time,
                              end_time=end_time,
                              workspace_token=workspace_token,
                              interval=3600) # 按照 3600 秒分时间段导出

即使指定了 interval 参数，如果尝试一次导出巨量日志，也可能由于运行时间过长等原因导致任务失败

3. dql_export_split(...)

guance_toolkit.dql_export_split(...) 函数是 guance_toolkit.dql_export(...) 函数的「切分版」。

本函数额外增加了 split_interval 参数，用于指定任务拆分粒度。同时，导出的文件也会按照此参数拆分。

参数列表：

参数 类型 必须 / 默认值 说明
split_interval int 自动按照时间分段拆分任务，单位秒
其他参数 - 与 guance_toolkit.dql_export(...) 函数同名参数相同

使用示例

假设需要查询 2022-10-21 00:00:00 ~ 2022-10-21 00:00:05 共 5 秒范围的数据，并按照每 2 秒 1 个任务拆分。

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import guance_toolkit__api as guance_toolkit

@DFF.API('导出 gin 日志')
def run():
    # DQL 语句（注意不要指定时间范围）
    dql = '''L::re(`.*`):(log_time,message,message_length){ `source` IN ['gin'] }'''

    # 时间范围
    start_time = '2022-10-21T00:00:00+08:00'
    end_time   = '2022-10-21T00:00:05+08:00'

    # 工作空间 Token
    workspace_token = 'tkn_xxxxx'

    # 指定输出目录
    file_path = 'export_data'

    # 启动执行
    guance_toolkit.dql_export(dql=dql,
                              start_time=start_time,
                              end_time=end_time,
                              workspace_token=workspace_token,
                              file_path=file_path,
                              split_interval=2)

输出位置

由于本函数为拆分任务后运行，最终输出为多个文件，这些文件会保存在单独的文件夹中。

文件夹名为单文件版的文件名（不含扩展名），分片文件名格式固定为 part-{切分开始时间}-{切分结束时间}.{输出格式}。

如上述示例，输出的文件列表如下：

异步 API（旧版：批处理）的任务记录如下：

注意事项

由于本函数的特殊性，请仔细阅读本注意事项

  1. 在调试本函数时（直接在 Web 界面运行），请大幅缩短时间范围，保证调试运行时只拆分为几个小任务
  2. 调用本函数会直接返回，其产生的子任务会进入队列依次运行，每个子任务的超时时间独立
  3. 请根据 start_time、end_time 以及实际数据量，合理指定 split_interval 的值，避免切分后的任务过多或者过少

我搞砸了！

如果您在调试本函数时（直接在 Web 界面运行）直接启动了需要耗时数小时的大任务。那么函数的调试通道将被阻塞，在任务停止前将无法在 Web 界面执行任何函数。

此时，请按照如下步骤尝试恢复：

  1. 使用「管理员工具」清空 Redis（请参考部署和维护 / 日常维护 / 管理员工具 admin-tool.py / 清空 Redis）
  2. 重启 DataFlux Func（请参考部署和维护 / 日常维护 / 重启系统）