腾讯云 CLS 日志检索与分析
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/acedatacloud-skills-tencentcloud-cls。
技能介绍
要解决什么问题
服务线上出现 5xx 或错误日志飙升时,你往往要在腾讯云 CLS 里反复切主题、拼查询、再手工把 LogJson 解开才能看到字段。跨多个日志主题按 Trace ID 串请求链路,或按 API 维度做 COUNT(*) 聚合,控制台点选效率低,也不适合交给 AI 助手按自然语言执行。
本技能聚焦 CLS 日志内容的检索与分析,不负责告警策略与通知组(那部分请用伴生技能 tencentcloud-cls-alarm)。
技能如何工作
认证依赖环境变量 TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY、TENCENTCLOUD_REGION,与腾讯云通用鉴权一致。日常操作优先走自带的 scripts/cls.py CLI:--time 支持 30m / 1h / 6h / 1d / 7d 等相对窗口;默认 CQL 查询,加 --lucene 可切换方言。在 CQL 后追加 | SELECT ... GROUP BY ... 即可切入 CLS 支持的 SQL-on-logs 聚合。
典型流程包括:向用户确认 Topic ID(形如 751a7350-dc5d-41c3-a6ca-c178bae05807,无法从服务名猜出)、执行 CQL 过滤(如 status_code:>=500 AND service:"openai")、对返回结果用 json.loads(line.LogJson) 展开索引字段。大批量结果单次最多 1000 条,需用 Context 分页继续拉取;自定义字段投影、原始分页遍历、基于 Context 的 tail 等超出 CLI 的能力,则直接调用 SDK。
边界与注意点
查询语法要与主题的 SyntaxRule 一致;含空格或冒号的值需加引号,否则会碰到 InvalidParameter.QueryError。并发 SearchLog 超过约 30 QPS 会触发 LimitExceeded,需要退避重试。若控制台能看到日志但 API 结果为空,优先核对 From/To 是否为毫秒时间戳,以及字段名是否与主题索引一致。账户欠费隔离时会出现 OperationDenied.AccountIsolated。
使用场景
- 线上服务 5xx 突增,需要在指定 CLS 主题里按时间窗筛 `status_code:>=500` 并快速列出错误样本
- 一次用户投诉对应某个 Trace ID,要在多个日志主题里交叉检索并串起完整请求生命周期
- 运营或 SRE 要对网关访问日志跑 `SELECT api_name, COUNT(*) GROUP BY api_name` 统计各接口调用量
- 出账或审计前,从 CLS 按 CQL 过滤后抽取指定索引字段导出为报表素材
适合人员
- 负责 on-call 的后端/SRE,需要在告警后几分钟内在 CLS 里定位近期错误与 5xx 根因
- 维护多微服务链路的工程师,习惯用 Trace ID 跨主题查日志并核对单请求全路径
- 需要按 API、状态码等维度做日志聚合、输出用量统计的平台或运维同学
- 要把 CLS 原始检索结果整理成审计或计费字段、又不想在控制台重复点选的开发或财务侧协作同学