Log Search

v3.0.0+

The tcb logs command has been available since v3.0.0.

CloudBase CLI provides a unified log search entry, supporting SCF, Cloud Run, database, large models, and all types of logs using CLS search syntax queries.

Prerequisites

Using the log feature requires that the log service is enabled for the current environment. If not enabled, the CLI will automatically prompt and guide you to enable it (free, with no additional charges).

tcb logs search

Search logs in the current environment.

tcb logs search [options]

Parameters

Parameter	Abbreviation	Description	Default Value
--env-id <envId>	-e	Environment ID	—
--query <queryString>	-q	CLS search statement	Default statement for --module
--timeRange <range>	-t	Time range, relative or absolute	1h
--limit <n>	-l	Number of entries to return (1–100)	20
--sort <order>	—	Sort order: desc / asc	desc
--context <cursor>	—	Pagination cursor to transparently pass the last returned value	—
--service <svc>	—	Log service: tcb / tcbr	tcb
--module <module>	-m	Log module, see Query by module	function
--json	—	Output JSON, suitable for script consumption	—

Query by module

v3.9.1+

The --module parameter has been available since v3.9.1.

-m, --module limits the search to one type of resource. When -q is omitted, the CLI queries with the built-in conditions for that module, and renders the results with that module's field rules. Add --verbose to see the statement actually executed.

Value	Resource
function	SCF (default)
tcbr	Cloud Run
database	Document database
rdb	SQL database
model	Data model
workflow	Approval workflow
automation	Workflow
auth	User authentication
llm	LLM
app	Application
gateway	Gateway access
http-gateway	HTTP gateway
cloudbase-api	CloudBase API
mini-app-api	Mini Program API

Behavior notes:

• --module omitted and --service tcbr absent: queries SCF logs and groups rows by request_id into one invocation. Other modules are not aggregated.
• -q provided: -q runs as-is. --module is not merged into the statement and only decides which field rules render the results. Grouping by invocation only happens for function (or no module) when the statement contains no |.
• --module tcbr is equivalent to --service tcbr. Cloud Run logs use a separate log service, so --service tcbr is not needed.
• --module and --service must point to the same log service. tcbr only maps to Cloud Run, and every other module belongs to tcb. Combinations such as --module database --service tcbr fail immediately.
• An unsupported value fails the command and lists all valid values.
• With --json: SCF outputs the invocation array grouped by call, while other modules output raw LogResults.

# Document database logs only
tcb logs search -m database -t 24h -e my-env-id

# Cloud Run logs only, equivalent to --service tcbr
tcb logs search -m tcbr -t 6h -e my-env-id

# Mini Program API calls only
tcb logs search -m mini-app-api -t 1h -e my-env-id

# Custom statement, results still rendered with database field rules
tcb logs search -m database -q 'module:database AND eventType:MongoSlowQuery' -t 24h -e my-env-id

Example

# View SCF logs from the last 1 hour (default module)
tcb logs search -e my-env-id

# Filter by Function Name, Last 6 Hours
tcb logs search -q 'function_name:"myFunc"' -t 6h -e my-env-id

# View error logs (status codes not 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

# Exact search by requestId for a single invocation (asc order restores execution sequence)
tcb logs search -q 'function_name:"myFunc" AND request_id:"abc123"' --sort asc -e my-env-id

# View Cloud Run Logs
tcb logs search --service tcbr -q '"error" AND "timeout"' -e my-env-id

# Specify Absolute Time Range
tcb logs search -t "2026-03-10 14:00:00,2026-03-10 15:00:00" -e my-env-id

# Obtain next page
tcb logs search -q 'function_name:"myFunc"' --context "eyJUb2tlb..." -e my-env-id

# Output JSON, suitable for script or AI consumption
tcb logs search --json -e my-env-id

CLS Search Statement Syntax

SCF Available Log Fields

Field	Description	Example
function_name	Function name	function_name:"myFunc"
request_id	Unique ID for this invocation. The field name in the cloud function log index is request_id, which all CLI versions can query directly	function_name:"myFunc" AND request_id:"abc123"
status_code	Status code, 200=success, 202=intermediate state (should be filtered)	status_code>200 AND status_code!=202
src	Log source: system=system logs, app=user code logs	src:app
log	log body	log:"Error"
namespace	Environment ID	namespace:"my-env"
qualifier	Function version	qualifier:"$LATEST"
retry_num	Retry count (filter retries with retry_num=0)	retry_num=0

How to write the request id field

In the CloudBase log spec the request id field is named requestId, but cloud function logs are reported by the underlying service and the field name in the CLS index is request_id. When querying cloud function logs, always use request_id, e.g. function_name:"myFunc" AND request_id:"abc123". The SQL analysis segment (| select …) also uses request_id.

Cloud Run Available Log Fields (--service tcbr or --module tcbr)

Field	Description	Example
__CONTENT__	full-text search of log content	"error" AND "timeout"
__TAG__.container_name	service name + instance, supports regex	/servername-[0-9]+/
__TAG__.pod_name	Pod name	__TAG__.pod_name:"xxx"

Platform logs (filtering by module:xxx)

Module	Query Statement	Use Case
Document Database	module:database	Database operation logs, eventType:MongoSlowQuery filters slow queries
SQL database	module:rdb	eventType:MysqlSlowQuery / MysqlFreeze / MysqlRecover
Data Model	module:model	—
Approval Workflow	module:workflow	—
User Authentication	module:auth	Login and authentication events
Large Language Model	module:llm AND logType:llm-tracelog	AI invocation tracing
Application Deployment	module:app	eventType:AppProdPub / AppProdDel
Workflow	module:automation	—
Gateway Access	logType:accesslog	HTTP access logs
HTTP gateway	accessSource:http_service_default_domain / accessSource:http_service_custom_domain	Access through default and custom domains
CloudBase API	accessSource:http_openapi	—
Mini Program API	accessSource:wx*	—

Prefer --module

You can write the conditions above into -q, or query directly with -m gateway / -m http-gateway / -m cloudbase-api / -m mini-app-api. The CLI adds the matching accessSource conditions for you.

SQL Analytical Syntax

CLS supports appending SQL analytical statements via the pipe symbol |:

<search condition> | select <field> [where <condition>] [group by <field>] [limit N]

Example: Counting failure counts per function

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

Time range format

Format	Example	Description
Relative time	30m / 6h / 1d	Last N minutes/hours/days
Absolute time range	"2026-03-10 14:00:00,2026-03-10 15:00:00"	Start and end time, separated by commas

---

Typical Query Scenarios

Scenario 1: Troubleshooting errors in a function today

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

Scenario 2: Tracing complete logs of a single call

# Include the function name, query by request_id, then sort in asc order to restore the chronological sequence
tcb logs search \
  -q 'function_name:"myFunc" AND request_id:"abc-request-id-123"' \
  --sort asc \
  --limit 100 \
  -e my-env-id

Scenario 3: Checking slow database queries

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

Scenario 4: Check Cloud Run Service Exceptions

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

Scenario 5: Tracing one request across services with requestId

Platform logs (database, auth, gateway access, etc.) all carry the requestId of the current request, so you can pull every kind of log triggered by the same request in one query:

tcb logs search \
  -q 'requestId:"req-abc-123"' \
  -t 1h \
  --sort asc \
  -e my-env-id

To narrow down to one module, combine requestId with the module condition in -q:

Module	-q query
Document database	module:database AND requestId:"req-abc-123"
SQL database	module:rdb AND requestId:"req-abc-123"
Data model	module:model AND requestId:"req-abc-123"
Approval workflow	module:workflow AND requestId:"req-abc-123"
User auth	module:auth AND requestId:"req-abc-123"
LLM	module:llm AND logType:llm-tracelog AND requestId:"req-abc-123"
App deployment	module:app AND requestId:"req-abc-123"
Gateway access	logType:accesslog AND requestId:"req-abc-123"

For example, to see only the database operations triggered by this request:

tcb logs search \
  -q 'module:database AND requestId:"req-abc-123"' \
  -t 1h \
  -e my-env-id

Note: cloud function logs are reported by SCF and their index field is request_id rather than requestId; use request_id:"..." when querying cloud function logs (see Scenario 2).

---

Collaborating with AI

The --json output of tcb logs search is processed in a structured format, suitable for direct consumption by large models. Recommended workflow:

# 1. Let the AI first learn the syntax of log commands via tcb docs
tcb docs read "logs"

# 2. Execute the query and output for AI analysis
tcb logs search -q 'function_name:"myFunc"' -t 6h --json -e my-env-id | \
  # Pass the results to AI for analysis

Best Practices for AI-Generated Commands

If letting a large model generate tcb commands, it is recommended to first use tcb docs search <keyword> or tcb docs read <module> to let the model obtain the real command signatures, avoiding the model 'guessing' commands based on training data and generating hallucinations.