日志检索

v3.0.0+

tcb logs 命令自 v3.0.0 起提供。

CloudBase CLI 提供统一的日志检索入口，支持云函数、云托管、数据库、大模型等全类型日志的 CLS 检索语法查询。

前置条件

使用日志功能需要当前环境已开通日志服务。若未开通，CLI 会自动提示引导开通（免费，无额外计费）。

tcb logs search

搜索当前环境的日志。

tcb logs search [options]

参数

参数	简写	说明	默认值
--env-id <envId>	-e	环境 ID	—
--query <queryString>	-q	CLS 检索语句	*（全部）
--timeRange <range>	-t	时间范围，相对或绝对	1h
--limit <n>	-l	返回条数（1–100）	20
--sort <order>	—	排序方式：desc / asc	desc
--context <cursor>	—	分页游标，透传上次返回值	—
--service <svc>	—	日志服务：tcb / tcbr	tcb
--json	—	输出 JSON，适合脚本消费	—

示例

# 查看最近 1 小时全部日志
tcb logs search -e my-env-id

# 按函数名过滤，最近 6 小时
tcb logs search -q 'function_name:"myFunc"' -t 6h -e my-env-id

# 查看报错日志（状态码非 200/202）
tcb logs search -q 'function_name:"myFunc" | select request_id, max(status_code) as status_code, max(ret_msg) as ret_msg where status_code>200 AND status_code!=202 AND retry_num=0 group by request_id limit 10' -e my-env-id

# 按 requestId 精确查单次调用（asc 排序还原执行时序）
tcb logs search -q 'request_id:"abc123"' --sort asc -e my-env-id

# 查看云托管日志
tcb logs search --service tcbr -q '"error" AND "timeout"' -e my-env-id

# 指定绝对时间范围
tcb logs search -t "2026-03-10 14:00:00,2026-03-10 15:00:00" -e my-env-id

# 获取下一页
tcb logs search -q 'function_name:"myFunc"' --context "eyJUb2tlb..." -e my-env-id

# 输出 JSON，适合脚本或 AI 消费
tcb logs search --json -e my-env-id

CLS 检索语句格式

云函数日志可用字段

字段	说明	示例
function_name	函数名称	function_name:"myFunc"
request_id	本次调用唯一 ID	request_id:"abc123"
status_code	状态码，200=成功，202=中间态（需过滤）	status_code>200 AND status_code!=202
src	日志来源：system=系统日志，app=用户代码日志	src:app
log	日志正文	log:"Error"
namespace	环境 ID	namespace:"my-env"
qualifier	函数版本	qualifier:"$LATEST"
retry_num	重试次数（过滤重试用 retry_num=0）	retry_num=0

云托管日志可用字段（--service tcbr）

字段	说明	示例
__CONTENT__	日志内容全文检索	"error" AND "timeout"
__TAG__.container_name	服务名+实例，支持正则	/servername-[0-9]+/
__TAG__.pod_name	Pod 名称	__TAG__.pod_name:"xxx"

平台日志（module:xxx 筛选）

模块	查询语句	适用场景
文档型数据库	module:database	数据库操作日志，eventType:MongoSlowQuery 筛慢查询
SQL 数据库	module:rdb	eventType:MysqlSlowQuery / MysqlFreeze / MysqlRecover
数据模型	module:model	—
审批流	module:workflow	—
用户鉴权	module:auth	登录、鉴权事件
大模型	module:llm AND logType:llm-tracelog	AI 调用追踪
应用部署	module:app	eventType:AppProdPub / AppProdDel
网关访问	logType:accesslog	HTTP 访问日志

SQL 分析语法

CLS 支持通过管道符 | 追加 SQL 分析语句：

<检索条件> | select <字段> [where <条件>] [group by <字段>] [limit N]

示例：统计各函数的失败次数

src:app | select function_name, count(*) as fail_count where status_code>200 AND status_code!=202 group by function_name order by fail_count desc limit 20

时间范围格式

格式	示例	说明
相对时间	30m / 6h / 1d	最近 N 分钟/小时/天
绝对时间段	"2026-03-10 14:00:00,2026-03-10 15:00:00"	起止时间，逗号分隔

---

典型查询场景

场景 1：排查某函数今天的报错

tcb logs search \
  -q 'function_name:"myFunc" AND status_code>200 AND status_code!=202' \
  -t 24h \
  --sort desc \
  -e my-env-id

场景 2：追踪一次调用的完整日志

# 先用 request_id 查，asc 排序还原时序
tcb logs search \
  -q 'request_id:"abc-request-id-123"' \
  --sort asc \
  --limit 100 \
  -e my-env-id

场景 3：查数据库慢查询

tcb logs search \
  -q 'module:database AND eventType:MongoSlowQuery' \
  -t 24h \
  -e my-env-id

场景 4：查云托管服务异常

tcb logs search \
  --service tcbr \
  -q '"ERROR" AND __TAG__.container_name:"my-service"' \
  -t 6h \
  -e my-env-id

---

与 AI 协作

tcb logs search 的 --json 输出经过结构化处理，适合大模型直接消费。推荐工作流：

# 1. 让 AI 先通过 tcb docs 了解日志命令语法
tcb docs read "日志"

# 2. 执行查询，输出给 AI 分析
tcb logs search -q 'function_name:"myFunc"' -t 6h --json -e my-env-id | \
  # 将结果传给 AI 分析

AI 生成命令的最佳实践

如果让大模型生成 tcb 命令，建议先通过 tcb docs search <关键词> 或 tcb docs read <模块> 让模型获取真实的命令签名，避免模型基于训练数据"猜测"命令而产生幻觉。