{"id":"ca16d496-e71f-4616-8eb2-6266bd7ee19f","shortId":"HyeacG","kind":"skill","title":"tencentcloud-cls","tagline":"Search and analyze Tencent Cloud CLS (Cloud Log Service) logs. Use\nwhenever the user asks to: search logs, debug API errors, trace\nrequests by trace ID, find 5xx errors, run CQL/SQL analytics over\nlog topics, extract structured fields. Backed by the official\ntencentcloud-sdk-pyth","description":"# Tencent Cloud CLS (Log Service) — Search & Analysis\n\nSearch and run CQL / SQL analytics over Tencent Cloud CLS log topics.\n\n> **Setup:** See [tencentcloud authentication](../_shared/tencentcloud.md). The SDK reads `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY` / `TENCENTCLOUD_REGION` from the environment.\n>\n> **Companion skill:** Use `tencentcloud-cls-alarm` for alarm policy / notice group / shield management. This skill is only about searching log content.\n\n## CLI (preferred)\n\nThe skill ships [`scripts/cls.py`](scripts/cls.py) — a self-contained CLI for the most common operations.\n\n```bash\nCLS=$SKILL_DIR/scripts/cls.py\n\npython3 $CLS topics                                              # list topics\npython3 $CLS search --topic <topic-id> --query 'level:ERROR' --time 1h\npython3 $CLS search --topic <topic-id> --trace-id <uuid>\npython3 $CLS search --topic <topic-id> --time 1d \\\n    --query '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20' \\\n    --format json\n```\n\n`--time` accepts `30m / 1h / 6h / 1d / 7d`. `--query` is CQL by default; pass `--lucene` to switch dialect. Append `| SELECT ... GROUP BY ...` to a query for SQL analytics.\n\nFor anything beyond what the CLI exposes (custom field projections, raw paginated walks, `Context`-based tailing) drop down to the SDK calls below.\n\n## When to Use\n\n- Find recent errors / 5xx responses for a service\n- Look up a single request by trace ID across multiple topics\n- Run CQL filters (`status_code:>=500 AND service:\"openai\"`)\n- Run SQL analytics (`SELECT api_name, COUNT(*) GROUP BY api_name`)\n- Chain trace logs to reconstruct a request lifecycle\n- Extract specific fields for billing / audit reports\n\n## Dependencies\n\n```bash\npip install tencentcloud-sdk-python\n```\n\n## Quick start\n\n```python\nimport os\nimport json\nfrom tencentcloud.common import credential\nfrom tencentcloud.cls.v20201016 import cls_client, models\n\ncred = credential.EnvironmentVariableCredential().get_credential()\nclient = cls_client.ClsClient(cred, os.environ[\"TENCENTCLOUD_REGION\"])\n```\n\n## Workflows\n\n### Discover topics\n\n```python\nreq = models.DescribeTopicsRequest()\nresp = client.DescribeTopics(req)\nfor t in resp.Topics:\n    print(t.TopicId, t.TopicName, t.LogsetId)\n```\n\n> Tip: ask the user for the topic ID up front. Topic IDs look like `751a7350-dc5d-41c3-a6ca-c178bae05807` and aren't guessable from a service name.\n\n### Search logs (CQL)\n\n```python\nimport time\n\nreq = models.SearchLogRequest()\nreq.TopicId = \"<topic-id>\"\nreq.From = int((time.time() - 3600) * 1000)   # 1 hour ago, ms epoch\nreq.To = int(time.time() * 1000)\nreq.Query = 'status_code:>=500 AND service:\"openai\"'\nreq.Limit = 100\nreq.Sort = \"desc\"\nreq.SyntaxRule = 1                             # 1 = CQL, 0 = Lucene\n\nresp = client.SearchLog(req)\nfor line in resp.Results:\n    fields = {f.Key: f.Value for f in line.LogJson and []}  # see below\n    print(line.Time, line.PkgLogId, fields.get(\"status_code\"), fields.get(\"api_name\"))\n```\n\n> CLS hands you `Results` with `LogJson` as a JSON string per record. Decode with `json.loads(line.LogJson)` to get a flat dict of all the indexed fields the topic stores.\n\n### Look up a trace ID across multiple topics\n\n```python\nTRACE_ID = \"34341776-0835-422a-956d-ac8d5b404db1\"\nTOPICS = {\n    \"trace\": \"<trace-topic-id>\",\n    \"api-usages\": \"<api-usages-topic-id>\",\n}\n\nfor label, topic_id in TOPICS.items():\n    req = models.SearchLogRequest()\n    req.TopicId = topic_id\n    req.From = int((time.time() - 86400) * 1000)\n    req.To = int(time.time() * 1000)\n    req.Query = f'trace_id:\"{TRACE_ID}\"'\n    req.Limit = 100\n    req.SyntaxRule = 1\n    resp = client.SearchLog(req)\n    print(f\"--- {label}: {len(resp.Results)} records ---\")\n    for line in resp.Results:\n        print(line.Time, line.LogJson)\n```\n\n### SQL analytics\n\nCLS supports a SQL-on-logs subset for aggregation. Append `| <SQL>` to a CQL filter:\n\n```python\nreq.Query = '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20'\nreq.SyntaxRule = 1\nresp = client.SearchLog(req)\n# When the query has a `|`, results land in resp.Analysis (rows of column→value)\nfor row in resp.AnalysisResults or []:\n    print(row)\n```\n\n### Tail recent logs\n\n```python\n# Poll every 5s for new lines after the last cursor\nlast_cursor = None\nwhile True:\n    req = models.SearchLogRequest()\n    req.TopicId = topic_id\n    req.From = int((time.time() - 30) * 1000)\n    req.To = int(time.time() * 1000)\n    req.Query = 'level:ERROR'\n    req.Limit = 100\n    req.Sort = \"asc\"\n    req.SyntaxRule = 1\n    if last_cursor:\n        req.Context = last_cursor\n    resp = client.SearchLog(req)\n    for line in resp.Results:\n        print(line.Time, line.LogJson)\n    last_cursor = resp.Context\n    time.sleep(5)\n```\n\n## CQL cheatsheet\n\n| Pattern | Meaning |\n|---|---|\n| `status_code:500` | exact match |\n| `status_code:>=500` | range |\n| `status_code:[500 TO 599]` | range with bounds |\n| `service:\"openai\"` | quoted phrase (use for values containing spaces) |\n| `NOT level:DEBUG` | negation |\n| `service:openai AND status_code:>=400` | conjunction |\n| `(api:foo OR api:bar)` | grouping |\n| `* | SELECT ... GROUP BY ...` | switch into SQL analytics |\n\n## Pagination\n\nCLS returns up to 1000 records per call. For larger result sets, iterate with `Context`:\n\n```python\nall_records = []\ncontext = None\nwhile True:\n    req = models.SearchLogRequest()\n    req.TopicId = topic_id\n    req.From = ...\n    req.To = ...\n    req.Query = '...'\n    req.Limit = 1000\n    req.SyntaxRule = 1\n    if context:\n        req.Context = context\n    resp = client.SearchLog(req)\n    all_records.extend(resp.Results)\n    context = resp.Context\n    if not context or len(resp.Results) < 1000:\n        break\n```\n\n## Error patterns\n\n| Symptom | Likely cause |\n|---|---|\n| `InvalidParameter.QueryError` | Quote phrases that contain `:` or spaces; check `SyntaxRule` matches the query |\n| `LimitExceeded` | Concurrent `SearchLog` calls exceed the 30-QPS quota — back off & retry |\n| `OperationDenied.AccountIsolated` | CLS service is suspended for billing — check the console |\n| Empty `Results` but logs visible in console | Time range is wrong (`From` / `To` are ms epoch, not seconds), or topic has different field names than the query expects |\n\n## Console links\n\n- CLS console: <https://console.cloud.tencent.com/cls/topic>\n- CQL syntax: <https://www.tencentcloud.com/document/product/614/47044>\n- SQL analytics syntax: <https://www.tencentcloud.com/document/product/614/58978>","tags":["tencentcloud","cls","skills","acedatacloud","acedata-cloud","agent-skills","agentskills","ai-image","ai-music","ai-tools","ai-video","claude-code"],"capabilities":["skill","source-acedatacloud","skill-tencentcloud-cls","topic-acedata-cloud","topic-agent-skills","topic-agentskills","topic-ai-image","topic-ai-music","topic-ai-tools","topic-ai-video","topic-claude-code","topic-cursor","topic-gemini-cli","topic-github-copilot","topic-mcp"],"categories":["Skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/AceDataCloud/Skills/tencentcloud-cls","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add AceDataCloud/Skills","source_repo":"https://github.com/AceDataCloud/Skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (6,493 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:04.226Z","embedding":null,"createdAt":"2026-05-18T13:21:35.312Z","updatedAt":"2026-05-18T19:14:04.226Z","lastSeenAt":"2026-05-18T19:14:04.226Z","tsv":"'-0835':472 '-422':473 '/_shared/tencentcloud.md':73 '/cls/topic':833 '/document/product/614/47044':838 '/document/product/614/58978':844 '0':403 '1':379,400,401,512,565,630,740 '100':396,510,626 '1000':378,387,498,502,617,621,711,738,758 '1d':157,182 '1h':144,180 '20':174,563 '30':616,783 '30m':179 '34341776':471 '3600':377 '400':691 '41c3':354 '5':651 '500':254,391,658,663,667 '599':669 '5s':595 '5xx':31,233 '6h':181 '751a7350':352 '751a7350-dc5d-41c3-a6ca-c178bae05807':351 '7d':183 '86400':497 '956d':476 'a-956d-ac8d5b404db1':474 'a6ca':355 'ac8d5b404db1':477 'accept':178 'across':246,465 'aggreg':540 'ago':381 'alarm':94,96 'all_records.extend':748 'analysi':56 'analyt':35,62,203,260,530,705,840 'analyz':6 'anyth':205 'api':23,160,167,262,267,429,481,549,556,693,696 'api-usag':480 'append':194,541 'aren':358 'asc':628 'ask':18,338 'audit':282 'authent':72 'back':42,786 'bar':697 'base':218 'bash':127,285 'beyond':206 'bill':281,795 'bound':672 'break':759 'c178bae05807':356 'call':225,714,780 'caus':764 'chain':269 'cheatsheet':653 'check':772,796 'cli':110,121,209 'client':308,314 'client.describetopics':327 'client.searchlog':406,514,567,638,746 'cloud':8,10,51,65 'cls':3,9,52,66,93,128,132,137,146,153,307,431,531,707,790,829 'cls_client.clsclient':315 'cnt':164,171,553,560 'code':253,390,427,657,662,666,690 'column':580 'common':125 'companion':88 'concurr':778 'conjunct':692 'consol':798,805,827,830 'console.cloud.tencent.com':832 'console.cloud.tencent.com/cls/topic':831 'contain':120,680,769 'content':109 'context':217,721,725,742,744,750,754 'count':162,264,551 'cql':60,186,250,367,402,544,652,834 'cql/sql':34 'cred':310,316 'credenti':302,313 'credential.environmentvariablecredential':311 'cursor':602,604,633,636,648 'custom':211 'dc5d':353 'debug':22,684 'decod':443 'default':188 'depend':284 'desc':172,398,561 'dialect':193 'dict':451 'differ':820 'dir/scripts/cls.py':130 'discov':321 'drop':220 'empti':799 'environ':87 'epoch':383,814 'error':24,32,142,232,624,760 'everi':594 'exact':659 'exceed':781 'expect':826 'expos':210 'extract':39,277 'f':416,504,517 'f.key':413 'f.value':414 'field':41,212,279,412,456,821 'fields.get':425,428 'filter':251,545 'find':30,230 'flat':450 'foo':694 'format':175 'front':346 'get':312,448 'group':99,165,196,265,554,698,700 'guessabl':360 'hand':432 'hour':380 'id':29,79,151,245,344,348,464,470,486,493,506,508,612,733 'import':295,297,301,306,369 'index':455 'instal':287 'int':375,385,495,500,614,619 'invalidparameter.queryerror':765 'iter':719 'json':176,298,439 'json.loads':445 'key':82 'label':484,518 'land':575 'larger':716 'last':601,603,632,635,647 'len':519,756 'level':141,623,683 'lifecycl':276 'like':350,763 'limit':173,562 'limitexceed':777 'line':409,523,598,641 'line.logjson':418,446,528,646 'line.pkglogid':424 'line.time':423,527,645 'link':828 'list':134 'log':11,13,21,37,53,67,108,271,366,537,591,802 'logjson':436 'look':238,349,460 'lucen':190,404 'manag':101 'match':660,774 'mean':655 'model':309 'models.describetopicsrequest':325 'models.searchlogrequest':372,490,609,730 'ms':382,813 'multipl':247,466 'name':161,168,263,268,364,430,550,557,822 'negat':685 'new':597 'none':605,726 'notic':98 'offici':45 'openai':257,394,674,687 'oper':126 'operationdenied.accountisolated':789 'order':169,558 'os':296 'os.environ':317 'pagin':215,706 'pass':189 'pattern':654,761 'per':441,713 'phrase':676,767 'pip':286 'polici':97 'poll':593 'prefer':111 'print':333,422,516,526,587,644 'project':213 'pyth':49 'python':291,294,323,368,468,546,592,722 'python3':131,136,145,152 'qps':784 'queri':140,158,184,200,571,776,825 'quick':292 'quot':675,766 'quota':785 'rang':664,670,807 'raw':214 'read':76 'recent':231,590 'reconstruct':273 'record':442,521,712,724 'region':84,319 'report':283 'req':324,328,371,407,489,515,568,608,639,729,747 'req.context':634,743 'req.from':374,494,613,734 'req.limit':395,509,625,737 'req.query':388,503,547,622,736 'req.sort':397,627 'req.syntaxrule':399,511,564,629,739 'req.to':384,499,618,735 'req.topicid':373,491,610,731 'request':26,242,275 'resp':326,405,513,566,637,745 'resp.analysis':577 'resp.analysisresults':585 'resp.context':649,751 'resp.results':411,520,525,643,749,757 'resp.topics':332 'respons':234 'result':434,574,717,800 'retri':788 'return':708 'row':578,583,588 'run':33,59,249,258 'scripts/cls.py':115,116 'sdk':48,75,224,290 'search':4,20,55,57,107,138,147,154,365 'searchlog':779 'second':816 'secret':78,81 'see':70,420 'select':159,195,261,548,699 'self':119 'self-contain':118 'servic':12,54,237,256,363,393,673,686,791 'set':718 'setup':69 'shield':100 'ship':114 'singl':241 'skill':89,103,113,129 'skill-tencentcloud-cls' 'source-acedatacloud' 'space':681,771 'specif':278 'sql':61,202,259,529,535,704,839 'sql-on-log':534 'start':293 'status':252,389,426,656,661,665,689 'store':459 'string':440 'structur':40 'subset':538 'support':532 'suspend':793 'switch':192,702 'symptom':762 'syntax':835,841 'syntaxrul':773 't.logsetid':336 't.topicid':334 't.topicname':335 'tail':219,589 'tencent':7,50,64 'tencentcloud':2,47,71,77,80,83,92,289,318 'tencentcloud-cl':1 'tencentcloud-cls-alarm':91 'tencentcloud-sdk-pyth':46 'tencentcloud-sdk-python':288 'tencentcloud.cls':304 'tencentcloud.common':300 'time':143,156,177,370,806 'time.sleep':650 'time.time':376,386,496,501,615,620 'tip':337 'topic':38,68,133,135,139,148,155,248,322,343,347,458,467,478,485,492,611,732,818 'topic-acedata-cloud' 'topic-agent-skills' 'topic-agentskills' 'topic-ai-image' 'topic-ai-music' 'topic-ai-tools' 'topic-ai-video' 'topic-claude-code' 'topic-cursor' 'topic-gemini-cli' 'topic-github-copilot' 'topic-mcp' 'topics.items':488 'trace':25,28,150,244,270,463,469,479,505,507 'trace-id':149 'true':607,728 'usag':482 'use':14,90,229,677 'user':17,340 'v20201016':305 'valu':581,679 'visibl':803 'walk':216 'whenev':15 'workflow':320 'wrong':809 'www.tencentcloud.com':837,843 'www.tencentcloud.com/document/product/614/47044':836 'www.tencentcloud.com/document/product/614/58978':842","prices":[{"id":"c5aa4e30-321f-4db9-a8a3-6278985feea3","listingId":"ca16d496-e71f-4616-8eb2-6266bd7ee19f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"AceDataCloud","category":"Skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:35.312Z"}],"sources":[{"listingId":"ca16d496-e71f-4616-8eb2-6266bd7ee19f","source":"github","sourceId":"AceDataCloud/Skills/tencentcloud-cls","sourceUrl":"https://github.com/AceDataCloud/Skills/tree/main/skills/tencentcloud-cls","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:35.312Z","lastSeenAt":"2026-05-18T19:14:04.226Z"}],"details":{"listingId":"ca16d496-e71f-4616-8eb2-6266bd7ee19f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"AceDataCloud","slug":"tencentcloud-cls","github":{"repo":"AceDataCloud/Skills","stars":7,"topics":["acedata-cloud","agent-skills","agentskills","ai-image","ai-music","ai-tools","ai-video","claude-code","cursor","gemini-cli","github-copilot","mcp","npm","openai-codex","roo-code"],"license":"other","html_url":"https://github.com/AceDataCloud/Skills","pushed_at":"2026-05-18T07:35:03Z","description":"Agent Skills for AceDataCloud AI services — music, image, video generation, web search, and more. Compatible with Claude Code, GitHub Copilot, Gemini CLI, and all agentskills.io-compatible agents.","skill_md_sha":"7c93f5d7f31b0f124683a21d0f3c5f86d06777e2","skill_md_path":"skills/tencentcloud-cls/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/AceDataCloud/Skills/tree/main/skills/tencentcloud-cls"},"layout":"multi","source":"github","category":"Skills","frontmatter":{"name":"tencentcloud-cls","license":"Apache-2.0","description":"Search and analyze Tencent Cloud CLS (Cloud Log Service) logs. Use\nwhenever the user asks to: search logs, debug API errors, trace\nrequests by trace ID, find 5xx errors, run CQL/SQL analytics over\nlog topics, extract structured fields. Backed by the official\ntencentcloud-sdk-python CLS client."},"skills_sh_url":"https://skills.sh/AceDataCloud/Skills/tencentcloud-cls"},"updatedAt":"2026-05-18T19:14:04.226Z"}}