时间与时间戳转换工具。在调用需要时间戳参数的 CLS 工具前，请先使用此工具进行精确转换，避免手动计算时间戳出错。

功能

• 可读时间 → 时间戳：传入 human_readable 参数，返回对应的 Unix 毫秒时间戳和秒级时间戳

• 时间戳 → 可读时间：传入 timestamp 参数（毫秒级），返回对应的可读时间字符串

• 同时返回毫秒和秒级时间戳，方便直接用于日志查询（毫秒）或指标查询（秒）

参数说明

• timestamp: Unix 毫秒时间戳（整数），与 human_readable 二选一

• human_readable: 人类可读时间表达式（字符串），与 timestamp 二选一，支持以下格式：

  • 绝对时间: 2026-03-25 14:30:00、2026-03-25 14:30:00.123、2026-03-25 14:30、2026-03-25

  • 相对时间: now、today、yesterday、tomorrow

  • 组合格式: yesterday 12:00:00、today 09:30、tomorrow 08:00

  • 相对偏移: 3 hours ago、1 day ago、30 minutes ago、2 weeks ago

• timezone: 时区名称，默认 Asia/Shanghai

使用示例

• 查询昨天12:00到13:00: 分别调用 human_readable="yesterday 12:00:00" 和 human_readable="yesterday 13:00:00"

• 查询最近1小时: 调用 human_readable="1 hour ago" 获取 start_time，human_readable="now" 获取 end_time

• 转换时间戳: 调用 timestamp=1774396800000 查看对应的可读时间

返回格式

返回包含毫秒时间戳（用于 cls_search_log 等）、秒级时间戳（用于 cls_query_metric 等）和可读时间字符串。

检索分析 CLS 日志。支持 CQL 检索和 SQL 管道分析。

CQL 语法速查

CQL (CLS Query Language) 是 CLS 自研的检索分析语法，语句结构为：[检索条件] | [SQL 语句]。 检索条件用于过滤日志，SQL 用于统计分析。不需要分析时可省略 | 及 SQL 部分。

检索语法

• 键值检索: status:404、level:ERROR（字段值包含该词）

• 全文检索: error、timeout（全文中包含该词）

• 短语检索: "connection timeout" 或 'user_name:"bob"'（精确短语，支持通配符如 "/var/log/acc*.log"）

• 逻辑操作符: AND、OR、NOT（不区分大小写，AND 优先级高于 OR）

• 分组: level:(ERROR OR WARNING) AND pid:1234

• 数值比较: status:>400、status:>=400、status:=200、latency:<100

• 模糊匹配: host:www.test*.com（* 匹配零到多个字符，不支持前缀模糊如 *test）

• 字段存在性: key:*（字段存在）、key:""（字段存在但值为空）

• 转义: body:user_name\:bob（特殊字符用 \ 转义）

SQL 分析（检索条件 | SQL，无需 FROM 和分号）

• 字符串用单引号 ''，字段名冲突用双引号 ""

• * | SELECT COUNT(*) AS total

• * | SELECT status, COUNT(*) AS cnt GROUP BY status ORDER BY cnt DESC

• 默认返回 100 行，LIMIT 最大 100 万行

CLS 扩展函数

• histogram（时间分桶）: histogram(__TIMESTAMP__, interval 1 hour) — 直接传 LONG 型，自动 UTC+8

• time_series（时序补全）: time_series(__TIMESTAMP__, '5m', '%Y-%m-%d %H:%i:%s', '0') — 必须 GROUP BY + ORDER BY，不支持 DESC，分钟用 %i

• compare（同环比）: compare(count(*), 86400) — 返回数组下标从 1 开始，86400=日/604800=周

• IP 地理: ip_to_province/city/country/provider(ip)

• 百分位: APPROX_PERCENTILE(field, 0.99)

关键注意

• CQL 是 CLS 推荐语法（SyntaxRule=1），相比 Lucene 更简便，特殊字符限制更少

• CQL 中多个分词默认为 AND 关系（Lucene 默认为 OR）

• __TIMESTAMP__ 是 bigint 毫秒时间戳，from_unixtime 要除 1000

• 脏数据用 try_cast 代替 cast

• 时区：histogram/time_series 传 LONG 型自动 UTC+8，其他日期函数默认 UTC+0，需手动加 8 小时

参数说明

• topic_id: 日志主题 ID（必填）

• query: CQL 检索语句（必填），如 level:ERROR 或 * | SELECT COUNT(*) as cnt

• start_time: 起始时间，Unix 时间戳（毫秒）

• end_time: 结束时间，Unix 时间戳（毫秒）

• limit: 返回条数，默认 100，最大 1000（仅对原始日志有效，SQL 分析不受此限制）

• context: 翻页游标，首次查询无需传入，从上次返回结果获取

• sort: 排序方式，asc（升序）或 desc（降序，默认）

注意事项

• ⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

• 💡 编写 SQL 分析语句前，建议先调用 cls_describe_index 获取索引配置，确认字段名称和类型

• ❌ CQL 执行报错时，可调用 cls_describe_search_syntax 获取 CLS 完整扩展语法参考文档

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域

获取日志上下文。根据一条日志的定位信息，查看其前后的日志记录，用于排查问题时了解完整的日志上下文。

参数说明

• topic_id: 日志主题 ID（必填）

• btime: 目标日志的时间（字符串），支持两种格式：

  1. 毫秒时间戳字符串（如 "1774537847429"）：工具内部自动按 UTC+8 时区转换为所需格式，可直接使用 cls_search_log 返回的"时间（Time）"对应的毫秒时间戳

  2. UTC+8 时间字符串 YYYY-mm-dd HH:MM:SS.FFF（如 "2026-03-25 14:25:00.000"）：需确保为 UTC+8 时区

• pkg_id: 目标日志的包序号（从 cls_search_log 返回的 PkgId 字段获取）

• pkg_log_id: 目标日志在包内的序号（从 cls_search_log 返回的 PkgLogId 字段获取）

• prev_logs: 向前获取的日志条数，默认 10，最大 100

• next_logs: 向后获取的日志条数，默认 10，最大 100

使用流程

1. 先用 cls_search_log 查找目标日志

2. 从结果中获取 PkgId、PkgLogId，以及"时间"对应的毫秒时间戳（或自行构造 UTC+8 时间字符串）

3. 用这些信息调用本工具获取上下文

注意事项

• btime 的时间字符串必须为 UTC+8 时区

• 传入毫秒时间戳字符串时，工具会自动按 UTC+8 转换，无需手动处理时区

• 毫秒精度会影响定位准确性，建议尽量使用精确的时间值

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

获取日志数量直方图。统计指定时间范围内日志在时间维度上的分布情况，用于观察日志量趋势和异常波动。

参数说明

• topic_id: 日志主题 ID（必填）

• query: CQL 检索语句（必填），如 level:ERROR 或 *（全部日志）

• start_time: 起始时间，Unix 时间戳（毫秒）

• end_time: 结束时间，Unix 时间戳（毫秒）

• interval: 时间间隔（毫秒），系统会自动选择合适间隔，也可手动指定

适用场景

• 观察日志量随时间的变化趋势

• 发现某个时间段的日志突增或突降

• 结合 cls_search_log 定位具体异常时段

注意事项

• ⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

• 💡 编写 SQL 分析语句前，建议先调用 cls_describe_index 获取目标主题的索引配置，确认字段名称、类型及是否开启统计，避免因字段信息不明确导致查询失败

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

快速获取日志数量。相比 cls_search_log 更快，适合只需要知道日志总数的场景。

参数说明

• topic_id: 日志主题 ID（必填）。格式不固定，可能是 UUID（如 550b584b-xxxx）或自定义字符串。当用户提供的值不确定是 ID 还是名称时，优先当作 topic_id 直接使用；如果报错（如"主题不存在"），再通过 cls_describe_topics 按名称搜索获取正确的 topic_id

• query: CQL 检索语句（必填）

• start_time: 起始时间，Unix 时间戳（毫秒）

• end_time: 结束时间，Unix 时间戳（毫秒）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

适用场景

• 快速确认某类日志是否存在

• 统计特定时间范围内的日志总量

注意事项

• ⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

• 💡 编写 SQL 分析语句前，建议先调用 cls_describe_index 获取目标主题的索引配置，确认字段名称、类型及是否开启统计，避免因字段信息不明确导致查询失败

CQL 检索分析语法完整参考文档。当 cls_search_log 执行报错或不确定如何编写查询语句时使用。

返回 CLS CQL 完整语法参考文档，包含：

• CQL 检索语法（键值检索、短语检索、逻辑操作符、数值比较、模糊匹配、字段存在性等）

• CQL 与 Lucene 语法的核心区别

• SQL 分析语法（管道符、FROM 省略、引号规则等）

• histogram（时间分桶）、time_series（时序补全）、compare（同环比）等 CLS 扩展函数

• IP 地理函数、百分位数函数等特殊函数

• 时区处理规则、脏数据处理、类型转换等关键注意事项

调用此工具不需要任何参数。

查询 CLS 指标数据（单时间点）。支持 PromQL 兼容查询语法，获取某一时刻的指标值。

参数说明

• topic_id: 指标主题 ID（必填），注意是时序指标主题 ID，非普通日志主题 ID

• query: 指标查询语句（必填），PromQL 兼容语法

• time: 查询时间点，Unix 时间戳（秒），默认当前时间

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

PromQL 示例

• metric_name — 查询单个指标当前值

• rate(metric_name[5m]) — 5 分钟速率

• sum(metric_name) by (label) — 按标签汇总

• topk(5, metric_name) — 取 Top 5

注意事项

• ⏰ time 为秒级时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

查询 CLS 指标数据（时间范围）。支持 PromQL 兼容查询语法，获取一段时间内的指标变化趋势。

参数说明

• topic_id: 指标主题 ID（必填），注意是时序指标主题 ID，非普通日志主题 ID。格式不固定，可能是 UUID 或自定义字符串。当用户提供的值不确定是 ID 还是名称时，优先当作 topic_id 直接使用；如果报错，再通过 cls_describe_topics(biz_type=1) 按名称搜索获取正确的指标主题 ID

• query: 指标查询语句（必填），PromQL 兼容语法

• start_time: 起始时间，Unix 时间戳（秒）

• end_time: 结束时间，Unix 时间戳（秒）

• step: 步长（秒），数据点之间的间隔，默认 60

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

适用场景

• 查看指标随时间的变化趋势

• 告警前查看历史指标走势

• 对比不同时间段的指标数据

注意事项

• ⏰ start_time/end_time 为秒级时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

列出指标主题下的所有指标名称。用于在查询指标前了解有哪些可用指标。

参数说明

• topic_id: 指标主题 ID（必填），注意是时序指标主题 ID，非普通日志主题 ID

• start_time: 起始时间，Unix 时间戳（秒）

• end_time: 结束时间，Unix 时间戳（秒）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

使用场景

• 在使用 cls_query_metric / cls_query_range_metric 查询指标前，先列出可用指标

• 了解某个指标主题下上报了哪些指标

注意事项

• ⏰ start_time/end_time 为秒级时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

• 返回的是指定时间范围内有数据的指标名称，建议查询最近 15 分钟即可

查询告警策略列表。获取当前账号下的告警策略信息，支持分页和过滤。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20，最大 100

• name: 按告警策略名称过滤（可选，模糊匹配）

• topic_id: 按关联日志主题 ID 过滤（可选）。如不确定 ID，可先通过 cls_describe_topics 按名称搜索

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 告警策略 ID、名称、状态（开启/关闭）

• 监控条件、触发规则、通知渠道

• 创建和最近修改时间

获取告警策略详情。根据告警策略 ID 查看完整的告警配置信息。

参数说明

• alarm_id: 告警策略 ID（必填）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 完整的告警配置：名称、监控条件、触发规则

• 通知渠道配置、告警周期

• 关联的日志主题和查询条件

查询告警通知渠道列表。获取当前账号配置的告警通知方式（如邮件、短信、回调等）。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• name: 按通知名称过滤（可选）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

查询告警历史记录。查看最近的告警触发记录，了解告警发生的时间、原因和处理状态。

参数说明

• start_time: 起始时间，Unix 时间戳（毫秒），如 1700000000000（必填）

• end_time: 结束时间，Unix 时间戳（毫秒）（必填）

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• alarm_id: 按告警策略 ID 过滤（可选）

• topic_id: 按监控对象（日志主题）ID 过滤（可选）。如不确定 ID，可先通过 cls_describe_topics 按名称搜索

• status: 按告警状态过滤（可选）：0=未恢复，1=已恢复，2=已失效

• alarm_level: 按告警等级过滤（可选）：0=警告，1=提醒，2=紧急

适用场景

• 排查某个告警策略的历史触发情况

• 查看某个日志主题关联的所有告警记录

• 按状态或等级筛选告警记录

• 了解最近告警的总体趋势

注意事项

• ⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

通过告警详情URL获取CLS告警的详细信息。从腾讯云告警详情URL中提取和解析告警信息，支持短链接和长链接格式。 该工具会自动解析URL、获取告警详情，并返回格式化的Markdown文档。

两种查询方式（二选一）

方式一：通过 URL 查询

• 传入 url 参数（短链接或长链接），工具自动解析并获取告警详情

方式二：通过 record_id + region 查询

• 传入 record_id 和 region 参数，工具直接构造 API 请求获取告警详情

• 这两个参数可从 cls_describe_alarm_records 工具的返回结果中获取

参数说明

• url: 告警详情 URL（可选），与 record_id+region 二选一

• record_id: 告警记录 ID（可选），从 cls_describe_alarm_records 获取

• region: 地域标识（可选），如 ap-guangzhou、ap-shanghai，从 cls_describe_alarm_records 获取

支持的URL格式

1. 短链接：https://alarm.cls.tencentcs.com/WeNZ5sSP

2. 短链接：https://mc.tencent.com/xxx

3. 长链接：https://ap-guangzhou-open-monitor.cls.tencentcs.com/cls_no_login?action=GetAlertDetailPage#/alert?RecordId=xxx

返回内容

• ⚠️ 告警基本信息（名称、ID、级别、地域）

• 🔍 告警详细数据（监控对象、触发时间、持续时间、触发条件、当前值）

• 📝 触发语句（CQL/SQL 查询）

• 📊 多维分析结果（如有）

• 💬 告警通知内容

• 🔗 相关链接（详情页、日志查询、认领）

应用场景

1. 快速查看告警详情：直接粘贴告警通知中的URL即可获取完整信息

2. 从告警记录列表查看详情：先用 cls_describe_alarm_records 获取 record_id 和 region，再调用本工具

3. 告警问题排查：查看告警触发条件、触发值、查询语句等关键信息

注意事项

• url 与 record_id+region 二选一，不能同时提供或同时为空

• 短链接会自动跳转到长链接进行解析

• 此接口为免密接口，无需额外认证信息

查询日志集列表。日志集是 CLS 的项目管理单元，包含多个日志主题。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• logset_name: 按日志集名称过滤（可选，模糊匹配）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 日志集 ID、名称、标签

• 保存周期、创建时间

• 包含的日志主题数量

查询日志主题列表。日志主题是日志数据的基本存储单元。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• logset_id: 按日志集 ID 过滤（可选）

• topic_name: 按日志主题名称过滤（可选，模糊匹配）

• biz_type: 主题类型过滤（可选）：0 表示日志主题，1 表示指标主题（时序数据主题）。不传则返回所有类型。当需要查询指标主题时，请传入 biz_type=1

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 日志主题 ID、名称、所属日志集

• 主题类型（日志主题/指标主题）

• 存储类型、保存周期、分区数

• 采集和索引状态

获取日志主题详情。查看日志主题的完整配置信息。

参数说明

• topic_id: 日志主题 ID（必填）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

查询日志主题的索引配置。索引决定了哪些字段可被检索和分析。

参数说明

• topic_id: 日志主题 ID（必填）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 全文索引配置（是否开启、分词符等）

• 键值索引配置（字段名、类型、是否开启统计）

• 索引状态

查询机器组列表。机器组是日志采集端的管理单元，用于统一管理一组日志源机器。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• group_name: 按机器组名称过滤（可选）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

获取机器组详情和机器状态。查看机器组的配置信息和组内机器的在线状态。

参数说明

• group_id: 机器组 ID（必填）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

查询仪表盘列表。获取当前账号下的 CLS 仪表盘。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• dashboard_name: 按仪表盘名称过滤（可选）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

查询 CLS 支持的地域列表。返回所有可用地域的 ID 和中文名称，用于确认地域参数的正确取值。

无需参数

直接调用即可，无需传入任何参数。

返回信息

• 地域 ID（如 ap-guangzhou、ap-shanghai）

• 地域中文名称（如 广州、上海）

使用场景

• 不确定某个城市/地区对应的地域 ID 时，先调用此工具查询

• 需要列出所有可用地域供用户选择时使用

查询数据加工任务列表。数据加工用于对日志数据进行清洗、转换、分发等处理。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• task_name: 按任务名称过滤（可选）

• topic_id: 按源日志主题 ID 过滤（可选）。如不确定 ID，可先通过 cls_describe_topics 按名称搜索

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 任务 ID、名称、状态（运行中/已停止/异常等）

• 源主题和目标主题

• 加工语句和创建时间

查询定时 SQL 任务列表。定时 SQL 用于周期性执行 SQL 分析并将结果存入目标日志主题。

参数说明

• offset: 分页偏移量，默认 0

• limit: 每页条数，默认 20

• task_name: 按任务名称过滤（可选）

• src_topic_id: 按源日志主题 ID 过滤（可选）

• region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域

返回信息

• 任务 ID、名称、状态

• 源主题、SQL 语句、调度周期

• 目标主题、创建时间