CLS Log Investigator

Overview

This skill enables intelligent log investigation across the Training & Certification (培训认证) platform's 6 CLS log environments. Given a bug description, requestId, error message, or keywords, it automatically searches the correct CLS topic, retrieves relevant logs, expands context around key entries, and provides a structured root-cause analysis.

Prerequisites — Topic ID Configuration

Before using this skill, verify the Topic IDs below match the actual CLS environment. Update them if the team provisions new topics.

Read the Environment Configuration file to load the full topic mapping.

Topic ID Quick Reference

Investigation Workflow

Follow this workflow for every log investigation request.

Step 1: Parse User Intent

Extract from the user's request:

1. Keywords / Identifiers: requestId, traceId, error message, user ID, API path, HTTP status code, or any search terms.
2. Target Environment: Determine which environment(s) to search. Map user language to environment keys:
• "测试" / "test" / "测试环境" → test
• "生产" / "prod" / "production" / "线上" / "正式" → prod + gray (默认同时查询生产和灰度两个环境，因为灰度流量是生产的子集，排查生产问题时必须同时查看灰度环境)
• "灰度" / "gray" / "canary" / "预发布" → gray (仅查灰度)
• If unspecified, default to prod + gray.
3. Site (Region): Determine domestic or international:
• "国内" / "domestic" / "内网" → domestic (Region: ap-guangzhou)
• "国际" / "international" / "海外" / "intl" / "外网" → international (Region: ap-singapore)
• If unspecified, default to domestic.
4. Time Range: Extract time window from the request:
• If a specific time is mentioned, use that as the center point ± 15 minutes.
• If "最近" / "刚才" / "just now" → last 15 minutes.
• If "今天" / "today" → last 6 hours (or since midnight if morning).
• If "昨天" / "yesterday" → yesterday 00:00 to 23:59.
• If no time is mentioned, default to last 30 minutes.

If the user mentions multiple environments (e.g., "查一下生产和灰度"), search both sequentially and present results together.

Step 2: Resolve Topic and Region

Based on Step 1, read references/env_config.md to look up the correct TopicId and Region code.

Construct the environment key as: {site}_{environment} (e.g., domestic_prod, intl_test).

Step 3: Build Search Query

Construct the CLS search query based on the extracted keywords:

For requestId / traceId searches:

requestId:"VALUE" OR traceId:"VALUE"

Replace VALUE with the actual requestId or traceId string.

For error message searches:

"error message text here"

Replace the quoted text with the actual error message.

For keyword-based searches:

keyword1 AND keyword2

Replace keyword1, keyword2 with the actual search terms.

For complex natural language queries:

Use the TextToSearchLogQuery MCP tool to convert the user's description into a valid CLS query. Parameters:

• Text: the user's natural language description
• Region: resolved region code
• TopicId: resolved topic ID

Step 4: Execute Log Search

Call the SearchLog MCP tool with:

• Region: the resolved region code (e.g., ap-guangzhou)
• TopicId: the resolved topic ID
• From: start timestamp in milliseconds (use ConvertTimeStringToTimestamp to convert)
• To: end timestamp in milliseconds
• Query: the constructed query string
• Limit: start with 20 for initial search. Increase to 50-100 if needed.
• Sort: desc (newest first)

Important: Always use ConvertTimeStringToTimestamp to get accurate timestamps. Calculate the time range first as ISO 8601 strings, then convert both From and To.

Time range guidelines:

• For requestId lookups: use a ±30 minute window around the suspected time, or last 1 hour if unknown.
• For error pattern searches: use 15-30 minutes to keep results manageable.
• Never exceed 24 hours in a single query — split into smaller windows if needed.

Step 5: Analyze Results

After receiving search results:

1. If results are empty:
• Broaden the time range (double it) and retry.
• Try a looser query (fewer keywords, wildcard matching).
• If still empty, try alternative environments (e.g., gray instead of prod).
• Report to the user which environments and time ranges were searched.

1. If results are found:
• Identify the most relevant log entries (matching requestId, error patterns, timestamps).
• For each critical log entry, call DescribeLogContext to fetch surrounding logs (±10-20 lines) for full context:
• Region: same region
• TopicId: same topic ID
• Time: from the log entry's Time field
• PkgId: from the log entry's PkgId field
• PkgLogId: from the log entry's PkgLogId field
• PrevLogs: 15
• NextLogs: 15

1. Cross-environment comparison (when requested or useful):
• If an issue appears in prod but not in gray, compare timestamps and error patterns.
• If an issue appears in domestic but not international, highlight environment-specific differences.

Step 6: Present Analysis Report

Structure the output as:

## 🔍 日志排查报告

### 排查环境
- **站点**: 国内/国际
- **环境**: 测试/生产/灰度
- **时间范围**: YYYY-MM-DD HH:mm:ss ~ YYYY-MM-DD HH:mm:ss
- **搜索关键词**: xxx

### 关键发现
1. [Summary of the most important finding]
2. [Additional findings...]

### 关键日志条目
[Present the most relevant log entries with timestamps and context]

### 根因分析
[Based on the log evidence, provide root cause analysis]

### 建议
1. [Actionable recommendation based on findings]
2. [Additional recommendations...]

Multi-Environment Investigation

When the user asks to compare across environments or the initial search suggests cross-environment impact:

1. Search the primary environment first.
2. Use findings (e.g., requestId, error pattern) to search related environments.
3. Present a comparison table showing which environments are affected.

Error Recovery

• CLS API timeout: Reduce the time range and retry. Split large queries into smaller windows.
• No results found: Systematically widen search — first broaden time, then loosen keywords, then try adjacent environments.
• Too many results: Add more specific filters (time range, specific field values, error level).
• Region mismatch: If domestic query returns nothing for an international user's issue, try the international region and vice versa.

References

references/

• env_config.md — Full environment configuration with topic IDs, region codes, and environment descriptions. Must be read at the start of every investigation to resolve the correct topic and region.