CLS Skill
Query and analyze Tencent Cloud CLS logs.
Setup
- Install clscli (Homebrew):
brew tap dbwang0130/clscli
brew install dbwang0130/clscli/clscli
- Get credentials and region list: https://cloud.tencent.com/document/api/614/56474
- Set environment variables (same as Tencent Cloud API common parameters):
export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"
- Specify region via
--region (e.g. ap-guangzhou).
Usage
!IMPORTANT: If you do not know the log topic, list topics first.
List log topics
List topics in a region to determine which --region and topic ID to use for query/context.
clscli topics --region <region> [--topic-name name] [--logset-name name] [--logset-id id] [--limit 20] [--offset 0]
Examples: --output=json, --output=csv, -o topics.csv
| Option |
Required |
Description |
| --region |
yes |
CLS region, e.g. ap-guangzhou |
| --topic-name |
no |
Filter by topic name (fuzzy match) |
| --logset-name |
no |
Filter by logset name (fuzzy match) |
| --logset-id |
no |
Filter by logset ID |
| --limit |
no |
Page size, default 20, max 100 |
| --offset |
no |
Pagination offset, default 0 |
| --output, -o |
no |
Output: json, csv, or file path |
Output columns: Region, TopicId, TopicName, LogsetId, CreateTime, StorageType.
Get log by query
clscli query -q "[query condition] | [SQL statement]" --region <region> -t <TopicId> --last 1h
Examples:
- Time:
--last 1h, --last 30m; or --from/--to (Unix ms)
- Multiple topics:
--topics <id1>,<id2> or multiple -t <id>
- Auto pagination and cap:
--max 5000 (paginate until 5000 logs or ListOver)
- Output:
--output=json, --output=csv, -o result.json (write to file)
| Option |
Required |
Description |
| --region |
yes |
CLS region, e.g. ap-guangzhou |
| -q, --query |
yes |
Query condition or SQL, e.g. level:ERROR or * | select count(*) as cnt |
| -t, --topic |
one of -t/--topics |
Single log topic ID |
| --topics |
one of -t/--topics |
Comma-separated topic IDs, max 50 |
| --last |
one of --last/--from/--to |
Time range, e.g. 1h, 30m, 24h |
| --from, --to |
one of --last/--from/--to |
Start/end time (Unix ms) |
| --limit |
no |
Logs per request, default 100, max 1000 |
| --max |
no |
Max total logs; when non-zero, auto-paginate until reached or ListOver |
| --output, -o |
no |
Output: json, csv, or file path |
| --sort |
no |
Sort: asc or desc, default desc |
Query condition syntax
Two syntaxes are supported:
- CQL (CLS Query Language): CLS-specific query syntax for logs, easy to use, recommended.
- Lucene: Open-source Lucene syntax; not designed for log search, has more restrictions on special chars, case, wildcards; not recommended.
CQL syntax
| Syntax |
Description |
key:value |
Key-value search; logs where field (key) contains value, e.g. level:ERROR |
value |
Full-text search; logs containing value, e.g. ERROR |
AND |
Logical AND, case-insensitive, e.g. level:ERROR AND pid:1234 |
OR |
Logical OR, case-insensitive, e.g. level:ERROR OR level:WARNING, level:(ERROR OR WARNING) |
NOT |
Logical NOT, case-insensitive, e.g. level:ERROR NOT pid:1234, level:ERROR AND NOT pid:1234 |
() |
Grouping for precedence, e.g. level:(ERROR OR WARNING) AND pid:1234. Note: AND has higher precedence than OR when no parentheses. |
" " |
Phrase search; double-quoted string, words and order must match, e.g. name:"john Smith". No logical operators inside phrase. |
' ' |
Phrase search; single quotes, same as ""; use when phrase contains double quotes, e.g. body:'user_name:"bob"' |
* |
Wildcard; zero or more chars, e.g. host:www.test*.com. No prefix wildcard. |
>, >=, <, <=, = |
Range operators for numeric values, e.g. status>400, status:>=400 |
\ |
Escape; escaped char is literal. Escape space, :, (), >, =, <, ", ', * in values. |
key:* |
text: field exists (any value). long/double: field exists and is numeric, e.g. response_time:* |
key:"" |
text: field exists and is empty. long/double: value is not numeric or field missing, e.g. response_time:"" |
SQL statement syntax
| Syntax |
Description |
| SELECT |
Select from table; data from current log topic matching query condition |
| AS |
Alias for column (KEY) |
| GROUP BY |
With aggregate functions, group by one or more columns (KEY) |
| ORDER BY |
Sort result set by KEY |
| LIMIT |
Limit rows, default 100, max 1M |
| WHERE |
Filter raw data |
| HAVING |
Filter after GROUP BY, before ORDER BY; WHERE filters raw data |
| Nested subquery |
One SELECT inside another for multi-step analysis |
| SQL functions |
Richer analysis: IP geo, time format, string split/join, JSON extract, math, distinct count, etc. |
Describe log context
Retrieve log context around a given log.
clscli context <PkgId> <PkgLogId> --region <region> -t <TopicId>
Examples: --output=json, --output=csv, -o context.json (write to file)
| Option |
Required |
Type |
Description |
Example |
| --region |
yes |
String |
CLS region |
ap-guangzhou |
| -t, --topic |
yes |
String |
Log topic ID |
- |
| PkgId |
yes |
String |
Log package ID, i.e. SearchLog Results[].PkgId |
528C1318606EFEB8-1A7 |
| PkgLogId |
yes |
Integer |
Index within package, i.e. SearchLog Results[].PkgLogId |
65536 |
| --output, -o |
no |
- |
Output: json, csv, or file path |
- |
1---2name: clscli3description: Query and analyze Tencent Cloud CLS logs4---5
6# CLS Skill
7
8Query and analyze Tencent Cloud CLS logs.
9
10## Setup
111. Install clscli (Homebrew):
12 ```bash
13 brew tap dbwang0130/clscli
14 brew install dbwang0130/clscli/clscli
15 ```
162. Get credentials and region list: https://cloud.tencent.com/document/api/614/56474
173. Set environment variables (same as Tencent Cloud API common parameters):
18 ```bash
19 export TENCENTCLOUD_SECRET_ID="your-secret-id"
20 export TENCENTCLOUD_SECRET_KEY="your-secret-key"
21 ```
224. Specify region via `--region` (e.g. ap-guangzhou).
23
24## Usage
25
26!IMPORTANT: If you do not know the log topic, list topics first.
27
28### List log topics
29List topics in a region to determine which `--region` and topic ID to use for query/context.
30
31```bash
32clscli topics --region <region> [--topic-name name] [--logset-name name] [--logset-id id] [--limit 20] [--offset 0]
33```
34Examples: `--output=json`, `--output=csv`, `-o topics.csv`
35
36| Option | Required | Description |
37|--------|----------|-------------|
38| --region | yes | CLS region, e.g. ap-guangzhou |
39| --topic-name | no | Filter by topic name (fuzzy match) |
40| --logset-name | no | Filter by logset name (fuzzy match) |
41| --logset-id | no | Filter by logset ID |
42| --limit | no | Page size, default 20, max 100 |
43| --offset | no | Pagination offset, default 0 |
44| --output, -o | no | Output: json, csv, or file path |
45
46Output columns: Region, TopicId, TopicName, LogsetId, CreateTime, StorageType.
47
48### Get log by query
49```bash
50clscli query -q "[query condition] | [SQL statement]" --region <region> -t <TopicId> --last 1h
51```
52Examples:
53- Time: `--last 1h`, `--last 30m`; or `--from`/`--to` (Unix ms)
54- Multiple topics: `--topics <id1>,<id2>` or multiple `-t <id>`
55- Auto pagination and cap: `--max 5000` (paginate until 5000 logs or ListOver)
56- Output: `--output=json`, `--output=csv`, `-o result.json` (write to file)
57
58| Option | Required | Description |
59|--------|----------|-------------|
60| --region | yes | CLS region, e.g. ap-guangzhou |
61| -q, --query | yes | Query condition or SQL, e.g. `level:ERROR` or `* \| select count(*) as cnt` |
62| -t, --topic | one of -t/--topics | Single log topic ID |
63| --topics | one of -t/--topics | Comma-separated topic IDs, max 50 |
64| --last | one of --last/--from/--to | Time range, e.g. 1h, 30m, 24h |
65| --from, --to | one of --last/--from/--to | Start/end time (Unix ms) |
66| --limit | no | Logs per request, default 100, max 1000 |
67| --max | no | Max total logs; when non-zero, auto-paginate until reached or ListOver |
68| --output, -o | no | Output: json, csv, or file path |
69| --sort | no | Sort: asc or desc, default desc |
70
71#### Query condition syntax
72
73Two syntaxes are supported:
74- **CQL** (CLS Query Language): CLS-specific query syntax for logs, easy to use, recommended.
75- **Lucene**: Open-source Lucene syntax; not designed for log search, has more restrictions on special chars, case, wildcards; not recommended.
76
77##### CQL syntax
78| Syntax | Description |
79|--------|-------------|
80| `key:value` | Key-value search; logs where field (key) contains value, e.g. `level:ERROR` |
81| `value` | Full-text search; logs containing value, e.g. `ERROR` |
82| `AND` | Logical AND, case-insensitive, e.g. `level:ERROR AND pid:1234` |
83| `OR` | Logical OR, case-insensitive, e.g. `level:ERROR OR level:WARNING`, `level:(ERROR OR WARNING)` |
84| `NOT` | Logical NOT, case-insensitive, e.g. `level:ERROR NOT pid:1234`, `level:ERROR AND NOT pid:1234` |
85| `()` | Grouping for precedence, e.g. `level:(ERROR OR WARNING) AND pid:1234`. **Note: AND has higher precedence than OR when no parentheses.** |
86| `" "` | Phrase search; double-quoted string, words and order must match, e.g. `name:"john Smith"`. No logical operators inside phrase. |
87| `' '` | Phrase search; single quotes, same as `""`; use when phrase contains double quotes, e.g. `body:'user_name:"bob"'` |
88| `*` | Wildcard; zero or more chars, e.g. `host:www.test*.com`. No prefix wildcard. |
89| `>`, `>=`, `<`, `<=`, `=` | Range operators for numeric values, e.g. `status>400`, `status:>=400` |
90| `\` | Escape; escaped char is literal. Escape space, `:`, `()`, `>`, `=`, `<`, `"`, `'`, `*` in values. |
91| `key:*` | text: field exists (any value). long/double: field exists and is numeric, e.g. `response_time:*` |
92| `key:""` | text: field exists and is empty. long/double: value is not numeric or field missing, e.g. `response_time:""` |
93
94#### SQL statement syntax
95| Syntax | Description |
96|--------|-------------|
97| SELECT | Select from table; data from current log topic matching query condition |
98| AS | Alias for column (KEY) |
99| GROUP BY | With aggregate functions, group by one or more columns (KEY) |
100| ORDER BY | Sort result set by KEY |
101| LIMIT | Limit rows, default 100, max 1M |
102| WHERE | Filter raw data |
103| HAVING | Filter after GROUP BY, before ORDER BY; WHERE filters raw data |
104| Nested subquery | One SELECT inside another for multi-step analysis |
105| SQL functions | Richer analysis: IP geo, time format, string split/join, JSON extract, math, distinct count, etc. |
106
107
108### Describe log context
109
110Retrieve log context around a given log.
111
112```bash
113clscli context <PkgId> <PkgLogId> --region <region> -t <TopicId>
114```
115Examples: `--output=json`, `--output=csv`, `-o context.json` (write to file)
116
117| Option | Required | Type | Description | Example |
118|--------|----------|------|-------------|---------|
119| --region | yes | String | CLS region | ap-guangzhou |
120| -t, --topic | yes | String | Log topic ID | - |
121| PkgId | yes | String | Log package ID, i.e. SearchLog Results[].PkgId | 528C1318606EFEB8-1A7 |
122| PkgLogId | yes | Integer | Index within package, i.e. SearchLog Results[].PkgLogId | 65536 |
123| --output, -o | no | - | Output: json, csv, or file path | - |
modbender