| cls_convert_timeA | 时间与时间戳转换工具。在调用需要时间戳参数的 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_search_logA | 检索分析 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，不传则使用默认地域
|
| cls_get_log_contextA | 获取日志上下文。根据一条日志的定位信息，查看其前后的日志记录，用于排查问题时了解完整的日志上下文。 参数说明topic_id: 日志主题 ID（必填） btime: 目标日志的时间（字符串），支持两种格式： 毫秒时间戳字符串（如 "1774537847429"）：工具内部自动按 UTC+8 时区转换为所需格式，可直接使用 cls_search_log 返回的"时间（Time）"对应的毫秒时间戳 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
使用流程先用 cls_search_log 查找目标日志 从结果中获取 PkgId、PkgLogId，以及"时间"对应的毫秒时间戳（或自行构造 UTC+8 时间字符串） 用这些信息调用本工具获取上下文
注意事项btime 的时间字符串必须为 UTC+8 时区 传入毫秒时间戳字符串时，工具会自动按 UTC+8 转换，无需手动处理时区 毫秒精度会影响定位准确性，建议尽量使用精确的时间值 region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域
|
| cls_get_log_histogramA | 获取日志数量直方图。统计指定时间范围内日志在时间维度上的分布情况，用于观察日志量趋势和异常波动。 参数说明topic_id: 日志主题 ID（必填） query: CQL 检索语句（必填），如 level:ERROR 或 *（全部日志） start_time: 起始时间，Unix 时间戳（毫秒） end_time: 结束时间，Unix 时间戳（毫秒） interval: 时间间隔（毫秒），系统会自动选择合适间隔，也可手动指定
适用场景注意事项⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算 💡 编写 SQL 分析语句前，建议先调用 cls_describe_index 获取目标主题的索引配置，确认字段名称、类型及是否开启统计，避免因字段信息不明确导致查询失败 region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域
|
| cls_get_log_countA | 快速获取日志数量。相比 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 查询所有可用地域
适用场景快速确认某类日志是否存在 统计特定时间范围内的日志总量
注意事项 |
| cls_describe_search_syntaxA | CQL 检索分析语法完整参考文档。当 cls_search_log 执行报错或不确定如何编写查询语句时使用。 返回 CLS CQL 完整语法参考文档，包含： CQL 检索语法（键值检索、短语检索、逻辑操作符、数值比较、模糊匹配、字段存在性等） CQL 与 Lucene 语法的核心区别 SQL 分析语法（管道符、FROM 省略、引号规则等） histogram（时间分桶）、time_series（时序补全）、compare（同环比）等 CLS 扩展函数 IP 地理函数、百分位数函数等特殊函数 时区处理规则、脏数据处理、类型转换等关键注意事项
调用此工具不需要任何参数。 |
| cls_query_metricA | 查询 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
注意事项 |
| cls_query_range_metricA | 查询 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 查询所有可用地域
适用场景查看指标随时间的变化趋势 告警前查看历史指标走势 对比不同时间段的指标数据
注意事项 |
| cls_list_metricsA | 列出指标主题下的所有指标名称。用于在查询指标前了解有哪些可用指标。 参数说明topic_id: 指标主题 ID（必填），注意是时序指标主题 ID，非普通日志主题 ID start_time: 起始时间，Unix 时间戳（秒） end_time: 结束时间，Unix 时间戳（秒） region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域，可通过 cls_describe_regions 查询所有可用地域
使用场景注意事项 |
| cls_describe_alarmsA | 查询告警策略列表。获取当前账号下的告警策略信息，支持分页和过滤。 参数说明返回信息告警策略 ID、名称、状态（开启/关闭） 监控条件、触发规则、通知渠道 创建和最近修改时间
|
| cls_describe_alarm_detailA | 获取告警策略详情。根据告警策略 ID 查看完整的告警配置信息。 参数说明返回信息完整的告警配置：名称、监控条件、触发规则 通知渠道配置、告警周期 关联的日志主题和查询条件
|
| cls_describe_alarm_noticesB | 查询告警通知渠道列表。获取当前账号配置的告警通知方式（如邮件、短信、回调等）。 参数说明 |
| cls_describe_alarm_recordsA | 查询告警历史记录。查看最近的告警触发记录，了解告警发生的时间、原因和处理状态。 参数说明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=紧急
适用场景排查某个告警策略的历史触发情况 查看某个日志主题关联的所有告警记录 按状态或等级筛选告警记录 了解最近告警的总体趋势
注意事项 |
| cls_get_alarm_detailA | 通过告警详情URL获取CLS告警的详细信息。从腾讯云告警详情URL中提取和解析告警信息，支持短链接和长链接格式。
该工具会自动解析URL、获取告警详情，并返回格式化的Markdown文档。 两种查询方式（二选一）方式一：通过 URL 查询 方式二：通过 record_id + region 查询 参数说明url: 告警详情 URL（可选），与 record_id+region 二选一 record_id: 告警记录 ID（可选），从 cls_describe_alarm_records 获取 region: 地域标识（可选），如 ap-guangzhou、ap-shanghai，从 cls_describe_alarm_records 获取
支持的URL格式短链接：https://alarm.cls.tencentcs.com/WeNZ5sSP 短链接：https://mc.tencent.com/xxx 长链接：https://ap-guangzhou-open-monitor.cls.tencentcs.com/cls_no_login?action=GetAlertDetailPage#/alert?RecordId=xxx
返回内容应用场景快速查看告警详情：直接粘贴告警通知中的URL即可获取完整信息 从告警记录列表查看详情：先用 cls_describe_alarm_records 获取 record_id 和 region，再调用本工具 告警问题排查：查看告警触发条件、触发值、查询语句等关键信息
注意事项 |
| cls_describe_logsetsA | 查询日志集列表。日志集是 CLS 的项目管理单元，包含多个日志主题。 参数说明返回信息日志集 ID、名称、标签 保存周期、创建时间 包含的日志主题数量
|
| cls_describe_topicsA | 查询日志主题列表。日志主题是日志数据的基本存储单元。 参数说明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、名称、所属日志集 主题类型（日志主题/指标主题） 存储类型、保存周期、分区数 采集和索引状态
|
| cls_describe_topic_detailA | 获取日志主题详情。查看日志主题的完整配置信息。 参数说明 |
| cls_describe_indexA | 查询日志主题的索引配置。索引决定了哪些字段可被检索和分析。 参数说明返回信息全文索引配置（是否开启、分词符等） 键值索引配置（字段名、类型、是否开启统计） 索引状态
|
| cls_describe_machine_groupsA | 查询机器组列表。机器组是日志采集端的管理单元，用于统一管理一组日志源机器。 参数说明 |
| cls_describe_machine_group_detailA | 获取机器组详情和机器状态。查看机器组的配置信息和组内机器的在线状态。 参数说明 |
| cls_describe_dashboardsA | 查询仪表盘列表。获取当前账号下的 CLS 仪表盘。 参数说明 |
| cls_describe_regionsA | 查询 CLS 支持的地域列表。返回所有可用地域的 ID 和中文名称，用于确认地域参数的正确取值。 无需参数直接调用即可，无需传入任何参数。 返回信息使用场景 |
| cls_describe_data_transform_tasksA | 查询数据加工任务列表。数据加工用于对日志数据进行清洗、转换、分发等处理。 参数说明返回信息任务 ID、名称、状态（运行中/已停止/异常等） 源主题和目标主题 加工语句和创建时间
|
| cls_describe_scheduled_sql_tasksA | 查询定时 SQL 任务列表。定时 SQL 用于周期性执行 SQL 分析并将结果存入目标日志主题。 参数说明返回信息任务 ID、名称、状态 源主题、SQL 语句、调度周期 目标主题、创建时间
|
