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	* (all)
--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
--json	—	Output JSON, suitable for script consumption	—

Example

# View all logs from the last 1 hour
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)

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
Gateway Access	logType:accesslog	HTTP access logs

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.