Supported Regions:上海

Log Alert Guide

The alerts built into the CloudBase console are Metric Alerts. They work on aggregated metrics such as invocation count, latency, and error rate, and cannot be broken down by a specific status code. To monitor log content, for example "alert when statusCode is 502", use the approach in this guide: deliver environment logs to Tencent Cloud Log Service (CLS), then use the CLS alerting capability to monitor the log content.

This guide uses CloudBase gateway errors as the example. It describes two ways to configure the alert: Console and CLI / API. Choose either one.

Overview

Step	Content
1	Deliver environment logs to CLS and get the log topic
2	Confirm the index of the log topic so that alert fields are searchable
3	Verify with search statements that the target logs can be found
4	Create a notification channel group
5	Create an alert policy
6	Verify that the alert actually triggers (common to both ways; see Verify the Alert Triggers)

Prerequisites

Item	Requirement
Account permissions	The root account, or a sub-account granted CLS read and write permissions
Cost	After logs are written to CLS, CLS bills them separately (write volume, indexing, storage, and alert policies). Set a reasonable log retention period
CLS console	Tencent Cloud/Cloud Log Service

Configure in the Console

Step 1: Deliver Logs to CLS

Deliver the environment logs to CLS by following Deliver Logs to CLS.

After the delivery, generate some real access requests before you verify in CLS. Otherwise the delivery may be mistaken as failed.

Step 2: Confirm the Index

Alerts depend on field search. Without an index, an alert cannot find data.

In the CLS console, select the same region as the CloudBase environment, and run the following statement on the search and analysis page. If records are returned, the log topic is correct:

logType:"accesslog"

Then open Index Configuration of the log topic and confirm:

Full-text index: enabled.
Key-value index: contains at least statusCode, logType, host, path, method, module, resourceName, timeCost, and requestId. See Log Field Reference for the field meanings.

⚠️ An index only applies to logs written after it is modified. Configure the index right after delivering to CLS, then verify the search, and create the alert last.

Step 3: Verify Search Statements

Do not create the alert right away. On the Search and Analysis page of the CLS console, run the following three statements in order and confirm that all of them return results:

-- 1. Count gateway 502 responses
logType:"accesslog" AND statusCode:"502"
| select count(*) as bad_gateway_cnt

-- 2. View the 502 distribution by host and path
logType:"accesslog" AND statusCode:"502"
| select host, path, count(*) as cnt
  group by host, path
  order by cnt desc
  limit 20

-- 3. Get samples and the request IDs for troubleshooting
logType:"accesslog" AND statusCode:"502"
| select requestId, host, path, method, timeCost, sourceIp
  order by timeCost desc
  limit 20

If statement 1 returns 0, there are currently no 502 records, which is normal. You can replace 502 with 200 first to verify that the statement runs.

Step 4: Create a Notification Channel Group

Create a notification channel group: In the CLS console, go to Monitoring Alarm > Notification Channel Group > Create, and add the channels you need: WeCom, email, SMS, phone, and custom webhook (callback to your own system).

We recommend routing by alert level:

Level	Notification method
Notice	WeCom group
Warning	WeCom group, email
Critical	WeCom group, SMS or phone

Customize the notification content (optional): In the CLS console, go to Monitoring Alarm > Notification Content Template > Create. WeCom, DingTalk, and Lark support Markdown. After you create the template, select it in the notification channel group:

## CloudBase Gateway 502 Alert
- **Domain**: {{index .ConditionGroup "$1.host"}}
- **Path**: {{index .ConditionGroup "$1.path"}}
- **502 count in 5 minutes**: {{index .QueryResult[0] "cnt"}}
- **Condition**: {{.Condition}}
- **Triggered at**: {{.StartTime}}
- **Duration**: {{.Duration}} minutes

Step 5: Create an Alert Policy

In the CLS console, go to Monitoring Alarm > Alarm Policy > Create. Choose one of the following three options. Option B is recommended. For more log fields you can use in query statements and trigger conditions, see Log Field Reference.

Option A: Basic, alert by count

Setting	Value
Alert name	CloudBase gateway 502 alert
Monitoring object	The log topic delivered in step 1
Query statement 1	`logType:"accesslog" AND statusCode:"502" \| select count(*) as bad_gateway_cnt`
Query time range	Last 5 minutes
Execution period	Every 1 minute
Trigger condition	`$1.bad_gateway_cnt >= 5`
Alert level	Warning; Critical is recommended for core production environments
Continuous periods	1 period is more sensitive; 2 periods tolerate jitter better

Option B: Grouped, locate the domain and path directly

Setting	Value
Query statement 1	`logType:"accesslog" AND statusCode:"502" \| select host, path, count(*) as cnt group by host, path order by cnt desc limit 20`
Query time range	Last 5 minutes
Execution period	Every 1 minute
Trigger condition	`$1.cnt >= 5`
Group trigger	Enabled, with the group fields set to `host,path`
Alert classification	`{{index .ConditionGroup "$1.host"}}`, `{{index .ConditionGroup "$1.path"}}`
Multi-dimensional analysis	Custom search and analysis: `logType:"accesslog" AND statusCode:"502" AND host:"{{index .ConditionGroup "$1.host"}}" AND path:"{{index .ConditionGroup "$1.path"}}"`

With group trigger enabled, each "domain + path" combination is evaluated and notified separately, so you can see which path has the problem instead of receiving a single total.

Option C: Error rate, for services with large traffic fluctuations

An absolute count tends to miss alerts on low-traffic sites and cause false alarms on high-traffic sites. A ratio is more stable.

Setting	Value
Query statement 1	`logType:"accesslog" AND statusCode:"502" \| select count(*) as err_cnt`
Query statement 2	`logType:"accesslog" \| select count(*) as total_cnt`
Query time range	Last 5 minutes, the same for both statements
Trigger condition	`$2.total_cnt > 100 AND $1.err_cnt >= 10 AND $1.err_cnt * 1.0 / $2.total_cnt > 0.01`

Common settings required by all three options:

Setting	Recommended value
Notification channel group	The group created in step 4
Alert interval	15 minutes; 30 minutes for continuous failures, to avoid repeated disturbance
Recovery notification	Enabled, so that you receive a confirmation when the failure recovers
Merge unrecovered alerts	Enabled

Configure with the CLI / API

Prepare Credentials

The CLI / API way requires two kinds of credentials:

Credential	How to get it	What it can do
CloudBase environment API Key	CloudBase platform, API Key management of the environment	Use the `tcb` CLI, including log search with `tcb logs search`
Tencent Cloud account key (SecretId, SecretKey)	Cloud Access Management (CAM) console, keys of a sub-account	Call all CLS APIs: log topics, indexes, search, and alert policies

⚠️ An API Key alone cannot complete the alert configuration. Log topics, indexes, search, and alert policies are CLS product APIs and do not accept CloudBase API Key authentication. Prepare an additional sub-account key with the QcloudCLSFullAccess permission. In multi-tenant scenarios, you can limit the permission to a specific topic/<TopicId>.

Configure the credentials and common variables:

# CloudBase environment API Key
tcb login --cloudbase-api-key <CLOUDBASE_API_KEY> -e <ENV_ID>
tcb env use <ENV_ID>

# Tencent Cloud account key, required for CLS APIs
tccli configure
export TENCENTCLOUD_SECRET_ID=<SecretId>
export TENCENTCLOUD_SECRET_KEY=<SecretKey>

# Common variables; the region must match the region of the CloudBase environment
export REGION=ap-shanghai
export ENV_ID=<environment ID>

Step 1: Get the Log Topic

Enable the environment log service (asynchronous; skip if already enabled):

tccli tcb CreateEnvResource --region $REGION --EnvId $ENV_ID --Resources '["log"]'

Get the default log topic of the environment and the account UIN:

tcb env detail --env-id $ENV_ID --json

Take the logset, the log topic, and the UIN from the result:

{
  "LogServices": [
    { "LogsetId": "<LogsetId>", "TopicId": "<TopicId>" }
  ],
  "UserInfo": { "Uin": 100000000000 }
}

export LOGSET_ID=<LogsetId>
export TOPIC_ID=<TopicId>
export UIN=<UserInfo.Uin>

If tcb env detail does not return the UIN, run the following command. The returned AccountId is the UIN:

tccli sts GetCallerIdentity --version 2018-08-13

After the log service is enabled, gateway access logs, cloud functions, CloudRun, and database logs are all written to this default topic. Create the index and alerts directly on the default topic:

export ALARM_LOGSET_ID=$LOGSET_ID
export ALARM_TOPIC_ID=$TOPIC_ID

Optional: Deliver to a Custom Log Topic

If you need an independent storage period or business isolation, deliver the default topic as a whole to a custom topic. Environment logs are written to the default topic by the platform, and the public API has no entry for rebinding to a custom topic, so a full copy through data transformation is required.

Create a custom logset and log topic:

tccli cls CreateLogset --region $REGION --LogsetName "tcb-gateway-logset"
export CUSTOM_LOGSET_ID=<LogsetId>

cat > topic.json <<'EOF'
{
  "LogsetId": "<CUSTOM_LOGSET_ID>",
  "TopicName": "tcb-accesslog-custom",
  "PartitionCount": 1,
  "AutoSplit": true,
  "MaxSplitPartitions": 10,
  "StorageType": "hot",
  "Period": 30,
  "Describes": "CloudBase environment logs (full delivery through data transformation)",
  "BizType": 0,
  "BillingMode": 0
}
EOF
tccli cls CreateTopic --region $REGION --cli-input-json file://topic.json
export CUSTOM_TOPIC_ID=<TopicId>

Period is the retention period in days, and 3640 means permanent retention. StorageType can be hot (standard storage) or cold (infrequent access storage, retention of at least 7 days).

Create a data transformation task for full delivery:

cat > transform.json <<'EOF'
{
  "Name": "tcb-accesslog-to-custom-topic",
  "FuncType": 1,
  "TaskType": 3,
  "SrcTopicId": "<TOPIC_ID>",
  "DstResources": [
    { "TopicId": "<CUSTOM_TOPIC_ID>", "Alias": "tcb-env-accesslog" }
  ],
  "EtlContent": "log_keep(true)",
  "EnableFlag": 1,
  "DataTransformType": 0,
  "KeepFailureLog": 2
}
EOF
tccli cls CreateDataTransform --region $REGION --cli-input-json file://transform.json

Parameter	Description
`FuncType`	`1` specifies the target topic; `2` creates it dynamically (`EtlContent` must then use `log_auto_output`)
`TaskType`	`1` and `2` are previews; `3` creates a real task
`SrcTopicId`	The default log topic of the environment
`DstResources[].TopicId`	The custom log topic
`EtlContent`	The transformation statement. Use `log_keep(true)` for full delivery, or `log_keep(regex_match(...))` to filter
`EnableFlag`	`1` enables, `2` disables
`ProcessFromTimestamp`, `ProcessToTimestamp`	Optional start and end time to process (second-level timestamps). If `ProcessToTimestamp` is omitted, the task runs continuously

Create the index and alerts on the custom topic from now on:

export ALARM_LOGSET_ID=$CUSTOM_LOGSET_ID
export ALARM_TOPIC_ID=$CUSTOM_TOPIC_ID

⚠️ Data transformation only applies to logs written after the task is created (or after ProcessFromTimestamp). It does not backfill historical data, and the target topic is billed for an additional copy of storage.

Step 2: Configure the Index

Alerts depend on field search. Without an index, an alert cannot find data. See Log Field Reference for the field meanings.

View the existing index first:

tccli cls DescribeIndex --region $REGION --TopicId $ALARM_TOPIC_ID

Add the alert fields if they are missing. resourceName identifies the resource the request actually accessed and is used to locate where an error comes from. Not every request carries this field; it is empty for authentication APIs.

cat > index.json <<'EOF'
{
  "TopicId": "<ALARM_TOPIC_ID>",
  "Status": true,
  "Rule": {
    "FullText": { "CaseSensitive": false, "Tokenizer": "-=/?;,.\"", "ContainZH": true },
    "KeyValue": {
      "CaseSensitive": false,
      "KeyValues": [
        { "Key": "logType",      "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "statusCode",   "Value": { "Type": "long", "Tokenizer": "", "SqlFlag": true, "ContainZH": false } },
        { "Key": "path",         "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "method",       "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "resourceName", "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "module",       "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "requestId",    "Value": { "Type": "text", "Tokenizer": "@&?|#()='\",;:<>[]{}/ \n\t\r\\", "SqlFlag": true, "ContainZH": true } },
        { "Key": "timeCost",     "Value": { "Type": "long", "Tokenizer": "", "SqlFlag": true, "ContainZH": false } }
      ]
    }
  },
  "IncludeInternalFields": true,
  "MetadataFlag": 1
}
EOF
tccli cls ModifyIndex --region $REGION --cli-input-json file://index.json

⚠️ An index only applies to logs written after it is modified. Only one index modification is allowed on the same log topic at a time. Run batch operations in sequence.

Step 3: Verify Search Statements

Do not create the alert right away. Use search commands to confirm that the target logs can be found first.

Use the tcb CLI (the API Key credential is enough; recommended):

# Error rate overview: number of 5xx responses and the total
tcb logs search --env-id $ENV_ID \
  --query 'logType:"accesslog" | select sum(case when cast(statusCode as bigint) >= 500 then 1 else 0 end) as err_cnt, count(*) as total_cnt, round(sum(case when cast(statusCode as bigint) >= 500 then 1 else 0 end) * 100.0 / count(*), 2) as err_rate' \
  --timeRange 1h --json

# Break down errors by resource and path to locate which resource reports the error
tcb logs search --env-id $ENV_ID \
  --query 'logType:"accesslog" | select resourceName, path, count(*) as err_cnt where cast(statusCode as bigint) >= 500 group by resourceName, path order by err_cnt desc limit 20' \
  --timeRange 1h --json

Parameter	Description
`--query`	CLS query statement; `\| select` aggregation is supported
`--timeRange`	`30m`, `1h`, `6h`, `1d`, or an absolute range such as `"2026-10-26 19:00:00,2026-10-26 20:00:00"`
`--limit`	Number of returned records, up to 100
`--sort`	`desc` for newest first, `asc` for oldest first
`--service`	`tcb` for cloud functions, databases, gateway, and so on (default); `tcbr` for CloudRun

Use the CLS API SearchLog (requires the Tencent Cloud key; time in millisecond timestamps):

FROM=$(( $(date -v-1H +%s) * 1000 )); TO=$(( $(date +%s) * 1000 ))   # macOS
tccli cls SearchLog --region $REGION --TopicId $ALARM_TOPIC_ID --From $FROM --To $TO \
  --QueryString 'logType:"accesslog" | select resourceName, path, count(*) as err_cnt where cast(statusCode as bigint) >= 500 group by resourceName, path order by err_cnt desc limit 20' \
  --QuerySyntax 1 --UseNewAnalysis true

The aggregated result is in the returned AnalysisRecords. statusCode is a string in logs, so SQL comparisons need cast(statusCode as bigint).

Step 4: Create a Notification Channel Group

The UIN of the receiver comes from UserInfo.Uin in step 1. The following example notifies by email:

cat > notice.json <<'EOF'
{
  "Name": "CloudBase gateway error alert group",
  "Type": "All",
  "NoticeReceivers": [
    {
      "ReceiverType": "Uin",
      "ReceiverIds": [<UIN>],
      "ReceiverChannels": ["Email"],
      "StartTime": "00:00:00",
      "EndTime": "23:59:59",
      "NoticeContentId": "Default-zh",
      "Index": 1
    }
  ]
}
EOF
tccli cls CreateAlarmNotice --region $REGION --cli-input-json file://notice.json
export NOTICE_ID=<AlarmNoticeId>

Field	Description
`Type`	`Trigger` notifies only on trigger, `Recovery` only on recovery, `All` on both
`ReceiverType`	`Uin` for a user (enter the UIN), `Group` for a user group (enter the group ID)
`ReceiverIds`	Array of receiver IDs (integers); multiple values are allowed
`ReceiverChannels`	`Email`, `Sms`, `Phone`, `WeChat`
`StartTime`, `EndTime`	The time period during which notifications are allowed
`NoticeContentId`	Notification content template; `Default-zh` is the default Chinese template

Emails are sent to the mailbox bound to the account in the Tencent Cloud message center. To send to a group, use WebCallbacks instead, where CallbackType can be WeCom, DingTalk, or Lark, and set the webhook Url of the bot.

Step 5: Create an Alert Policy

The following example is "error rate + group": within a 5-minute window, an alert is triggered when the request count of a single resourceName + path combination is greater than 100 and the share of 5xx responses exceeds 5%. The policy is checked every 1 minute, and the repeat notification interval is 30 minutes. For more log fields you can use in query statements and trigger conditions, see Log Field Reference.

cat > alarm.json <<'EOF'
{
  "Name": "CloudBase gateway error rate alert",
  "MonitorObjectType": 0,
  "AlarmTargets": [
    {
      "TopicId": "<ALARM_TOPIC_ID>",
      "LogsetId": "<ALARM_LOGSET_ID>",
      "Number": 1,
      "Query": "logType:\"accesslog\" | select resourceName, path, count(*) as err_cnt where cast(statusCode as bigint) >= 500 group by resourceName, path",
      "StartTimeOffset": -5,
      "EndTimeOffset": 0,
      "SyntaxRule": 1
    },
    {
      "TopicId": "<ALARM_TOPIC_ID>",
      "LogsetId": "<ALARM_LOGSET_ID>",
      "Number": 2,
      "Query": "logType:\"accesslog\" | select resourceName, path, count(*) as total_cnt group by resourceName, path",
      "StartTimeOffset": -5,
      "EndTimeOffset": 0,
      "SyntaxRule": 1
    }
  ],
  "MonitorTime": { "Type": "Period", "Time": 1 },
  "TriggerCount": 2,
  "AlarmPeriod": 30,
  "Condition": "$2.total_cnt > 100 AND $1.err_cnt * 1.0 / $2.total_cnt > 0.05",
  "AlarmLevel": 1,
  "Status": true,
  "GroupTriggerStatus": true,
  "GroupTriggerCondition": ["$1.resourceName", "$1.path"],
  "AlarmNoticeIds": ["<NOTICE_ID>"],
  "Analysis": [
    {
      "Name": "5xx raw logs",
      "Type": "query",
      "Content": "logType:\"accesslog\" | select requestId, resourceName, path, method, statusCode, timeCost, sourceIp where cast(statusCode as bigint) >= 500 limit 20",
      "ConfigInfo": [{ "Key": "SyntaxRule", "Value": "1" }]
    }
  ],
  "MessageTemplate": "CloudBase gateway error rate alert: {{.Topic}}, condition {{.Condition}}, time {{.StartTime}}"
}
EOF
tccli cls CreateAlarm --region $REGION --cli-input-json file://alarm.json
export ALARM_ID=<AlarmId>

Parameters

Parameter	Description
`AlarmTargets[].Query`	Query statement. It must contain a `\| select` analysis statement; search conditions alone never trigger
`AlarmTargets[].Number`	Statement number, starting from 1; reference it in the condition with `$1.`, `$2.`
`StartTimeOffset`, `EndTimeOffset`	Minute offsets relative to the execution time. Both are non-positive, and `StartTimeOffset` is not greater than `EndTimeOffset`. `-5` to `0` means the last 5 minutes
`SyntaxRule`	`1` for CQL (recommended), `0` for Lucene
`MonitorTime`	`{ "Type": "Period", "Time": 1 }` runs every 1 minute
`TriggerCount`	Number of consecutive periods that must match before alerting; `2` tolerates single-period jitter
`AlarmPeriod`	Repeat notification interval, in minutes
`AlarmLevel`	`0` warning, `1` notice, `2` critical
`Condition`	Trigger condition, referenced as `$N.field-name`; the field name must match the `select` alias
`GroupTriggerStatus`	Enables group trigger. When enabled, `Query` must contain `group by`, and `GroupTriggerCondition` holds the group fields
`Analysis`	Multi-dimensional analysis; the notification carries a link that goes straight to the raw logs
`MessageTemplate`	Supports `{{.Topic}}`, `{{.Condition}}`, `{{.StartTime}}`, `{{.Duration}}`

Common variants

Scenario	How to change
Absolute number of 5xx responses only	Use a single statement `... where cast(statusCode as bigint) >= 500 \| select count(*) as err_cnt` with the condition `$1.err_cnt >= 10`
Include 4xx	Change `>= 500` to `>= 400`
Global error rate without groups	Set `GroupTriggerStatus` to `false`, remove `group by` from both statements, and use the condition `$1.err_cnt * 1.0 / $2.total_cnt > 0.05`
Slow requests	Use `timeCost` in the condition, for example `$1.max_cost > 3000`

Manage Alert Policies

# View a policy
tccli cls DescribeAlarms --region $REGION --Filters '[{"Key":"alarmId","Values":["<ALARM_ID>"]}]'

# Adjust the repeat notification interval
tccli cls ModifyAlarm --region $REGION --AlarmId $ALARM_ID --AlarmPeriod 30

# Mute temporarily: keep the policy and only stop notifications
tccli cls ModifyAlarm --region $REGION --AlarmId $ALARM_ID --Status false

# Delete the policy (cannot be recovered)
tccli cls DeleteAlarm --region $REGION --AlarmId $ALARM_ID

To mute temporarily during a release, use CreateAlarmShield. Setting Enable to false archives the policy.

API Cheatsheet

Action	CLI	API Action
Enable environment log resources	`tccli tcb CreateEnvResource`	`tcb CreateEnvResource`
Query environment, log topic, and UIN	`tcb env detail --json`	`tcb DescribeEnvs`
Search logs	`tcb logs search`	`cls SearchLog`
Create logset and log topic	`tccli cls CreateLogset`, `CreateTopic`	`cls CreateLogset`, `cls CreateTopic`
Full delivery to a custom topic	`tccli cls CreateDataTransform`	`cls CreateDataTransform`
Query and modify index	`tccli cls DescribeIndex`, `ModifyIndex`	`cls DescribeIndex`, `cls ModifyIndex`
Notification channel group	`tccli cls CreateAlarmNotice`	`cls CreateAlarmNotice`, `cls DescribeAlarmNotices`
Alert policy	`tccli cls CreateAlarm`, `ModifyAlarm`, `DeleteAlarm`	`cls CreateAlarm`, `cls ModifyAlarm`, `cls DeleteAlarm`, `cls DescribeAlarms`
Alert shield	None	`cls CreateAlarmShield`
Get the UIN of the current account	`tccli sts GetCallerIdentity --version 2018-08-13`	`sts GetCallerIdentity`

Call Cloud APIs with an SDK

CLS APIs use TC3-HMAC-SHA256 signatures, which are costly to implement by hand, so we recommend using an SDK. The following Python example uses the same request parameters as alarm.json in step 5:

pip install tencentcloud-sdk-python-cls

import os
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.cls.v20201016 import cls_client, models

cred = credential.Credential(
    os.environ["TENCENTCLOUD_SECRET_ID"], os.environ["TENCENTCLOUD_SECRET_KEY"])
hp = HttpProfile(endpoint="cls.tencentcloudapi.com")
client = cls_client.ClsClient(cred, "ap-shanghai", ClientProfile(httpProfile=hp))

req = models.CreateAlarmRequest()
with open("alarm.json", encoding="utf-8") as f:
    req.from_json_string(f.read())
print(client.CreateAlarm(req).to_json_string())

CreateLogset, CreateTopic, CreateDataTransform, ModifyIndex, and CreateAlarmNotice are called in the same way. Just switch to the matching models.XxxRequest().

Verify the Alert Triggers

After you configure the alert in either way, run an end-to-end verification instead of finding out that the alert does not work only when a failure happens:

Temporarily change the query statement to one that is sure to match, for example replace statusCode:"502" with statusCode:"200".
Temporarily change the trigger condition to >= 1 and set the execution period to 1 minute.
Wait 1 to 3 minutes and confirm that you receive the notification. Open the link in the notification and confirm that it goes to the CLS search page and shows the raw logs.
Change the statement and threshold back to the target configuration and save.

Troubleshoot After an Alert

Click the multi-dimensional analysis link in the alert notification to go straight to the CLS search page.

Run the following statement to get the requestId of the failed request:

logType:"accesslog" AND statusCode:"502"
| select requestId, host, path, method, timeCost, sourceIp
  order by timeCost desc
  limit 20

Use the requestId to look up the logs of that request in cloud functions and CloudRun, and decide whether the problem is in the gateway or the backend:
```
requestId:"9be5592e-11ea-4f45-9c83-e44ff20e7ed4"
```
Common causes of 502: cold start timeout of the backend instance, container restart or scale-in to 0, upstream connection reset, and oversized response body.
Check with timeCost: a duration close to the gateway timeout usually means a timeout-type 502; a very short duration generally means the upstream is unavailable.

Statement Cheatsheet

Scenario	Statement
Count 502 responses	`logType:"accesslog" AND statusCode:"502" \| select count(*) as cnt`
502 by path	`logType:"accesslog" AND statusCode:"502" \| select host, path, count(*) as cnt group by host, path order by cnt desc limit 20`
All 5xx responses	`logType:"accesslog" \| select count(*) as cnt where cast(statusCode as bigint) >= 500`
Slow requests (over 3000 ms)	`logType:"accesslog" \| select count(*) as cnt where cast(timeCost as bigint) > 3000`
Error distribution by module	`logType:"accesslog" AND statusCode:"502" \| select module, count(*) as cnt group by module order by cnt desc`
Trace a single request	`requestId:"<requestId>"`

FAQ

No logs found in CLS after delivery?

Check in order: whether there are new access requests after the delivery time; whether the region of the CLS console matches the environment region; whether the search time range covers the time of the request; and whether the field has an index.

Can I configure alerts with only a CloudBase API Key?

No. The topic, index, search, and alert APIs of CLS only accept signatures made with a Tencent Cloud SecretId and SecretKey. Prepare an additional sub-account key with QcloudCLSFullAccess, or limited to a specific topic. The API Key can be used to search logs with tcb logs search.

LogServices returned by tcb env detail is empty?

The log service is not enabled for the environment. Run tccli tcb CreateEnvResource --Resources '["log"]', then poll tcb env detail. Enabling is asynchronous and takes up to about 5 minutes.

The statement returns results on the search page, but the alert does not trigger?

Check each item:

The query statement must contain a | select analysis statement. Search conditions alone cannot trigger an alert.
The trigger condition references fields with $1.field-name, and the name matches the select alias.
When group trigger is enabled, the query statement must have group by.
StartTimeOffset is non-positive and not greater than EndTimeOffset.
The index has taken effect for newly written data.

Alerts are missed with a 1-minute window?

Gateway logs take seconds to about 1 minute to be written to CLS after they are produced. A window that is too narrow can miss a whole round. Widen the query time range to 5 minutes and increase the alert interval to avoid repeated notifications.

Too many alerts, or notifications surge after group trigger is enabled?

The number of notifications scales with the number of groups. Raise the threshold, lengthen the execution period, set continuous periods to 2, and set the alert interval to 30 minutes. Disable group trigger if necessary.

Numeric comparison of statusCode fails?

statusCode is a string in logs. In SQL, write cast(statusCode as bigint) >= 500.

How do I monitor only one domain or path?

Append a filter to the search condition, for example:

logType:"accesslog" AND statusCode:"502" AND host:"xxx.api.tcloudbasegateway.com"
| select count(*) as cnt

How do I distinguish multiple environments?

Deliver each environment to its own log topic and create a separate alert policy for each topic, or add the topic name variable {{.Topic}} to the notification content.

How do I control costs?

Set a log retention period in the CLS console (for example 7 or 30 days), and enable key-value indexes only for necessary fields.

Errors on concurrent operations?

CreateAlarm is rate limited to 20 requests per second. Only one ModifyIndex operation is allowed on the same log topic at a time, so run them in sequence.

Overview​

Prerequisites​

Configure in the Console​

Step 1: Deliver Logs to CLS​

Step 2: Confirm the Index​

Step 3: Verify Search Statements​

Step 4: Create a Notification Channel Group​

Step 5: Create an Alert Policy​

Configure with the CLI / API​

Prepare Credentials​

Step 1: Get the Log Topic​

Optional: Deliver to a Custom Log Topic​

Step 2: Configure the Index​

Step 3: Verify Search Statements​

Step 4: Create a Notification Channel Group​

Step 5: Create an Alert Policy​

Manage Alert Policies​

API Cheatsheet​

Call Cloud APIs with an SDK​

Verify the Alert Triggers​

Troubleshoot After an Alert​

Statement Cheatsheet​

FAQ​

Related Documentation​

Overview

Prerequisites

Configure in the Console

Step 1: Deliver Logs to CLS

Step 2: Confirm the Index

Step 3: Verify Search Statements

Step 4: Create a Notification Channel Group

Step 5: Create an Alert Policy

Configure with the CLI / API

Prepare Credentials

Step 1: Get the Log Topic

Optional: Deliver to a Custom Log Topic

Step 2: Configure the Index

Step 3: Verify Search Statements

Step 4: Create a Notification Channel Group

Step 5: Create an Alert Policy

Manage Alert Policies

API Cheatsheet

Call Cloud APIs with an SDK

Verify the Alert Triggers

Troubleshoot After an Alert

Statement Cheatsheet

FAQ

Related Documentation