К основному содержанию
скилл CX Codex

tencentcloud-cls — скилл для Claude Code: поиск логов и установка

Скилл ищет и анализирует логи Tencent Cloud CLS: помогает находить ошибки API, трассировать запросы и запускать CQL/SQL-запросы.

Apache-2.0 221 установок ★ 17 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add AceDataCloud/Skills --skill tencentcloud-cls -a claude-code
Открыть на GitHub

Что делает tencentcloud-cls

Скилл работает с топиками Tencent Cloud CLS через официальный клиент tencentcloud-sdk-python. Он умеет искать записи по фильтрам CQL или Lucene, находить ответы 5xx, извлекать поля и искать один trace ID в нескольких топиках. Для SQL-аналитики к фильтру добавляется запрос с агрегацией, группировкой и сортировкой.

В комплекте есть CLI scripts/cls.py: через него можно получить список топиков, выполнить поиск по времени, trace ID или запросу и выбрать формат JSON. Для более сложных сценариев предусмотрены вызовы SDK, включая работу с Context для постраничной выборки и чтения новых записей. Установите библиотеку командой pip install tencentcloud-sdk-python. Без TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY и TENCENTCLOUD_REGION клиент не получит учётные данные и регион.

Какие задачи решает

  • найти ошибки 5xx в логах сервиса
  • трассировать запрос по trace ID в нескольких топиках
  • отфильтровать записи через CQL или Lucene
  • посчитать вызовы API с помощью SQL-агрегации
  • извлечь поля для аудиторского или платёжного отчёта

Примеры запросов агенту

  • Найди ошибки 5xx в топике <topic-id> за последний час.
  • Проверь запрос с trace ID <uuid> во всех указанных топиках.
  • Посчитай число вызовов по api_name за сутки и верни результат в JSON.

Как установить tencentcloud-cls

1Через Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill tencentcloud-cls -a claude-code

2Вручную: положить файлы

~/.claude/skills/tencentcloud-cls/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/tencentcloud-cls/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о tencentcloud-cls

Как установить tencentcloud-cls в Claude Code?

Выполните npx skills add AceDataCloud/Skills --skill tencentcloud-cls -a claude-code, затем проверьте файл ~/.claude/skills/tencentcloud-cls/SKILL.md.

Что делает tencentcloud-cls?

Скилл ищет записи в Tencent Cloud CLS, фильтрует их через CQL или Lucene, анализирует логи SQL-запросами и помогает связывать события по trace ID.

Что нужно подготовить для поиска логов?

Нужны переменные TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY и TENCENTCLOUD_REGION, а также ID топика CLS. ID топика нельзя надёжно вывести из имени сервиса.

Исходный текст

SKILL.md · Apache-2.0
---
name: tencentcloud-cls
description: |
  Search and analyze Tencent Cloud CLS (Cloud Log Service) logs. Use
  whenever the user asks to: search logs, debug API errors, trace
  requests by trace ID, find 5xx errors, run CQL/SQL analytics over
  log topics, extract structured fields. Backed by the official
  tencentcloud-sdk-python CLS client.
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
connections: [tencentcloud]
---

# Tencent Cloud CLS (Log Service) — Search & Analysis

Search and run CQL / SQL analytics over Tencent Cloud CLS log topics.

> **Setup:** See [tencentcloud authentication](../_shared/tencentcloud.md). The SDK reads `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY` / `TENCENTCLOUD_REGION` from the environment.
>
> **Companion skill:** Use `tencentcloud-cls-alarm` for alarm policy / notice group / shield management. This skill is only about searching log content.

## CLI (preferred)

The skill ships [`scripts/cls.py`](scripts/cls.py) — a self-contained CLI for the most common operations.

```bash
# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
CLS="$SKILL_DIR/scripts/cls.py"; [ -f "$CLS" ] || CLS=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/cls.py' 2>/dev/null | head -1)
[ -f "$CLS" ] || { echo "tencentcloud-cls script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

python3 $CLS topics                                              # list topics
python3 $CLS search --topic <topic-id> --query 'level:ERROR' --time 1h
python3 $CLS search --topic <topic-id> --trace-id <uuid>
python3 $CLS search --topic <topic-id> --time 1d \
    --query '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20' \
    --format json
```

`--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.

For anything beyond what the CLI exposes (custom field projections, raw paginated walks, `Context`-based tailing) drop down to the SDK calls below.

## When to Use

- Find recent errors / 5xx responses for a service
- Look up a single request by trace ID across multiple topics
- Run CQL filters (`status_code:>=500 AND service:"openai"`)
- Run SQL analytics (`SELECT api_name, COUNT(*) GROUP BY api_name`)
- Chain trace logs to reconstruct a request lifecycle
- Extract specific fields for billing / audit reports

## Dependencies

```bash
pip install tencentcloud-sdk-python
```

## Quick start

```python
import os
import json
from tencentcloud.common import credential
from tencentcloud.cls.v20201016 import cls_client, models

cred = credential.EnvironmentVariableCredential().get_credential()
client = cls_client.ClsClient(cred, os.environ["TENCENTCLOUD_REGION"])
```

## Workflows

### Discover topics

```python
req = models.DescribeTopicsRequest()
resp = client.DescribeTopics(req)
for t in resp.Topics:
    print(t.TopicId, t.TopicName, t.LogsetId)
```

> 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.

### Search logs (CQL)

```python
import time

req = models.SearchLogRequest()
req.TopicId = "<topic-id>"
req.From = int((time.time() - 3600) * 1000)   # 1 hour ago, ms epoch
req.To = int(time.time() * 1000)
req.Query = 'status_code:>=500 AND service:"openai"'
req.Limit = 100
req.Sort = "desc"
req.SyntaxRule = 1                             # 1 = CQL, 0 = Lucene

resp = client.SearchLog(req)
for line in resp.Results:
    fields = {f.Key: f.Value for f in line.LogJson and []}  # see below
    print(line.Time, line.PkgLogId, fields.get("status_code"), fields.get("api_name"))
```

> 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.

### Look up a trace ID across multiple topics

```python
TRACE_ID = "34341776-0835-422a-956d-ac8d5b404db1"
TOPICS = {
    "trace": "<trace-topic-id>",
    "api-usages": "<api-usages-topic-id>",
}

for label, topic_id in TOPICS.items():
    req = models.SearchLogRequest()
    req.TopicId = topic_id
    req.From = int((time.time() - 86400) * 1000)
    req.To = int(time.time() * 1000)
    req.Query = f'trace_id:"{TRACE_ID}"'
    req.Limit = 100
    req.SyntaxRule = 1
    resp = client.SearchLog(req)
    print(f"--- {label}: {len(resp.Results)} records ---")
    for line in resp.Results:
        print(line.Time, line.LogJson)
```

### SQL analytics

CLS supports a SQL-on-logs subset for aggregation. Append `| <SQL>` to a CQL filter:

```python
req.Query = '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20'
req.SyntaxRule = 1
resp = client.SearchLog(req)
# When the query has a `|`, results land in resp.Analysis (rows of column→value)
for row in resp.AnalysisResults or []:
    print(row)
```

### Tail recent logs

```python
# Poll every 5s for new lines after the last cursor
last_cursor = None
while True:
    req = models.SearchLogRequest()
    req.TopicId = topic_id
    req.From = int((time.time() - 30) * 1000)
    req.To = int(time.time() * 1000)
    req.Query = 'level:ERROR'
    req.Limit = 100
    req.Sort = "asc"
    req.SyntaxRule = 1
    if last_cursor:
        req.Context = last_cursor
    resp = client.SearchLog(req)
    for line in resp.Results:
        print(line.Time, line.LogJson)
    last_cursor = resp.Context
    time.sleep(5)
```

## CQL cheatsheet

| Pattern | Meaning |
|---|---|
| `status_code:500` | exact match |
| `status_code:>=500` | range |
| `status_code:[500 TO 599]` | range with bounds |
| `service:"openai"` | quoted phrase (use for values containing spaces) |
| `NOT level:DEBUG` | negation |
| `service:openai AND status_code:>=400` | conjunction |
| `(api:foo OR api:bar)` | grouping |
| `* | SELECT ... GROUP BY ...` | switch into SQL analytics |

## Pagination

CLS returns up to 1000 records per call. For larger result sets, iterate with `Context`:

```python
all_records = []
context = None
while True:
    req = models.SearchLogRequest()
    req.TopicId = topic_id
    req.From = ...
    req.To = ...
    req.Query = '...'
    req.Limit = 1000
    req.SyntaxRule = 1
    if context:
        req.Context = context
    resp = client.SearchLog(req)
    all_records.extend(resp.Results)
    context = resp.Context
    if not context or len(resp.Results) < 1000:
        break
```

## Error patterns

| Symptom | Likely cause |
|---|---|
| `InvalidParameter.QueryError` | Quote phrases that contain `:` or spaces; check `SyntaxRule` matches the query |
| `LimitExceeded` | Concurrent `SearchLog` calls exceed the 30-QPS quota — back off & retry |
| `OperationDenied.AccountIsolated` | CLS service is suspended for billing — check the console |
| 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 |

## Console links

- CLS console: <https://console.cloud.tencent.com/cls/topic>
- CQL syntax: <https://www.tencentcloud.com/document/product/614/47044>
- SQL analytics syntax: <https://www.tencentcloud.com/document/product/614/58978>

© acedatacloud · Apache-2.0 · AceDataCloud/Skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
relational-database-mcp-cloudbase TencentCloudBase Скилл relational-database-mcp-cloudbase управляет существующей MySQL-базой CloudBase через инструменты MCP: запросы, схема, права доступа, удаление. Для новых проектов рекомендован PostgreSQL. CX Codex +1 962установок alibabacloud-sls-data-agent aliyun Скилл alibabacloud-sls-data-agent для Claude Code подключает SLS DataAgent к Alibaba Cloud Simple Log Service. Превращает вопросы на естественном языке в выборки, агрегации и отчёты по логам. CX Codex +1 111установок Everr everr-labs MCP-сервер Everr для Claude Code, который подключает аналитику приложения и запросы к данным по протоколу Model Context Protocol. CX Codex +1 ★ 55звёзд репо cloud-functions TencentCloudBase Скилл cloud-functions для Claude Code и Codex. Ведёт агента по созданию, деплою и отладке Event и HTTP Functions в CloudBase. Требует выбрать тип функции заранее — рантайм после создания не меняется. CX Codex +1 1 200установок scylladb scylladb С восемью скиллами по ScyllaDB: моделирование данных CQL, Vector Search, Alternator, управление кластерами через MCP, развёртывание в Kubernetes и нагрузочное тестирование. ★ 9звёзд репо openobserve-api fcakyon Скилл openobserve-api для Claude Code работает с OpenObserve через REST API: ищет по логам, управляет стримами и дашбордами с панелями. Получает данные из Cloud- и self-hosted-инстансов. CX Codex +1 ★ 1 216звёзд репо

Из того же набора67

Весь набор →
short-url Скилл short-url для Claude Code создаёт короткие ссылки через AceDataCloud API. Готовит длинный URL к передаче или публикации. CX Codex +1 228установок face-transform Скилл face-transform для Claude Code, Codex, Cursor и других платформ, который подключает семь API AceDataCloud для работы с лицами: поиск ключевых точек, ретушь портретов, изменение возраста и пола, замена лиц. CX Codex +1 228установок google-calendar Скилл google-calendar для Claude Code просматривает расписание, ищет свободные окна и планирует встречи в Google Календаре через Calendar v3 REST API. Управляет событиями без перехода в браузер. CX Codex +1 222установок blogger Работает с Blogger API v3: публикует записи, читает блоги и посты, обновляет публикации. Управляет блогом из Claude Code. CX Codex +1 221установок youtube Ищет видео на YouTube, читает данные канала и помогает загружать ролики через YouTube Data API v3. Проверяет статистику и комментарии своих видео. CX Codex +1 221установок google-drive Скилл google-drive управляет конкретными файлами Google Диска через REST API v3, читает документы, экспортирует таблицы и загружает отчёты. CX Codex +1 219установок microsoft-onedrive Скилл microsoft-onedrive даёт агенту готовые вызовы Microsoft Graph: список файлов OneDrive и SharePoint, поиск, скачивание, загрузка, ссылки на шаринг. CX Codex +1 219установок gpt-image-2 Генерирует и редактирует изображения через AceDataCloud API модели OpenAI gpt-image-2. Встраивает реальные логотипы, скриншоты и QR-коды прямо в сцены с сохранением исходных форм. CX Codex +1 219установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой