Using CLS via Skill
Download
Focus Mode
Font Size
Overview
CLS Skill is the official skill package for Tencent Cloud Log Service (CLS), designed specifically for intelligent collaboration tools like WorkBuddy. After installation, users can directly perform full-link operations such as log search, resource management, metric query, and alarm Ops using natural language, without needing to log in to the CLS console.
Core Value:
Natural Language Interaction, Zero Syntax Barrier: Users can directly and precisely search logs, query metrics, and configure alarms by describing their requirements in everyday language, without needing to learn professional query syntax such as CQL or PromQL. This significantly reduces the learning cost and operational complexity of log analysis.
Immersive Workspace, No Console Switching: Users can perform full log lifecycle management in a one-stop manner within tools like WorkBuddy. When troubleshooting issues, they no longer need to repeatedly switch between multiple pages in the CLS console, which helps maintain focus and improve the continuity of troubleshooting.
Multi-turn Contextual Interaction for Precise Problem Localization: This feature supports continuous analysis based on the conversation context. For example, users can first query error logs, then analyze error distribution trends, and finally expand the contextual details of key logs, drilling down layer by layer until the root cause is located.
Parallel Diagnostic Capability for Rapid Full-Link Troubleshooting: In complex scenarios such as collection link troubleshooting, users can simultaneously check machine group status, Agent operation, collection configurations, and binding relationships. This multi-dimensional parallel diagnosis shortens the time required for fault localization.
CLS Skill provides you with the following capabilities:
Feature Category | Core Sub-feature | Detailed Description |
Log search and analysis | Keyword Search | Supports multiple search methods, including full-text search, key-value search, fuzzy matching, and range query, to quickly locate target logs. |
| Viewing Context | View the N records before and after any log entry to restore the complete context of an issue. |
| Statistical Analysis | Supports SQL aggregate analysis (GROUP BY, ORDER BY, LIMIT, and so on) to perform grouping statistics and trend analysis on massive logs. |
Resource management | Managing Log Topics | Search and view log topics by conditions such as name, ID, Tag, and storage type. |
| Managing Logsets | Search and view logsets to understand the organizational hierarchy of log resources. |
| Index management | View index configuration information and track the status and progress of index rebuild tasks. |
Machine Groups and Collection | Managing a Machine Group | View the server group list and member status (online/offline), and support filtering by conditions such as IP address, operating system, and version. |
| Collection Settings | View collection rule configurations and check the binding relationship between collection settings and server groups. |
Metric query | Querying Metric Tags | View the Tag dimensions of metrics, with support for filtering by matching rules. |
| PromQL Query | Performs range queries on metric data using PromQL syntax and is compatible with the Prometheus ecosystem. |
Alarm Ops | Managing Alarm Policies | View the alarm policy list, with support for filtering by conditions such as name and status. |
| Alarm History | View alarm triggered and recovery records, with support for filtering by alarm level (warning/reminder/critical) and recovery status. |
| Execution Details | View alarm policy execution logs in detail to analyze the cause of alarm triggers. |
| Shielding rules | View alarm suppression configurations and check whether alarms are muted. |
Prerequisites
Enabling a Service
Obtaining a Key
Go to the CAM console to obtain TencentCloud API keys (SecretId and SecretKey). For details, refer to Root Account Access Key Management.
Note:
The SecretKey is sensitive information. Please securely store it and never send it directly in AI conversations.
If you use a sub-account, ensure that the sub-account has been granted the relevant CLS CAM permissions. For the minimum permission policy, refer to:
Log Search: QcloudCLSReadOnlyAccess
Log Search + Management Operations: QcloudCLSFullAccess
For more granular control, see CLS CAM Authorization to customize policies.
Installing a Skill
CLS Skill has been listed on WorkBuddy and SkillHub. You can choose the installation method based on your usage scenario.
Method 1: Installing in WorkBuddy
1. Open the WorkBuddy client, select Experts·Skills·Connectors on the left, and go to the management page.
2. Search for tencentcloud-cls in the skill market.
3. Click Install and wait for the process to complete. Alternatively, you can directly enter the following command in a conversation: Install the Tencent Cloud CLS skill for me.
Method 2: Installing via SkillHub
For users of AI tools other than WorkBuddy, copy the following content to the AI chat window to install:
Install tencentcloud-cls by following the instructions at https://skillhub.cn/install/skillhub.md.
Configuring Credentials
After installation, you need to configure SecretId and SecretKey to use CLS Skill normally. Configure SecretId and SecretKey into the system's environment variables according to the AI prompts or the following method.
macOS / Linux Configuration Guide
First, run the following command in the terminal to confirm your Shell type:
echo $SHELL
If the output is /bin/zsh, run the following command to write the key to ~/.zshrc and make it take effect immediately:
# 1. Append the environment variables to ~/.zshrcecho 'export TENCENTCLOUD_SECRET_ID="Your SecretId"' >> ~/.zshrcecho 'export TENCENTCLOUD_SECRET_KEY="Your SecretKey"' >> ~/.zshrc# 2. Make the configuration take effect immediately in the current terminalsource ~/.zshrc
If the output is /bin/bash, run the following command to write the key to ~/.bashrc and make it take effect immediately:
# 1. Append the environment variables to ~/.bashrcecho 'export TENCENTCLOUD_SECRET_ID="Your SecretId"' >> ~/.bashrcecho 'export TENCENTCLOUD_SECRET_KEY="Your SecretKey"' >> ~/.bashrc# 2. Make the configuration take effect immediately in the current terminalsource ~/.bashrc
Windows Configuration Guide
Run the following command to write the key to the system environment variables. Note: The configuration takes effect only for newly opened terminal windows. Restart your terminal or AI tool to apply the changes.
setx TENCENTCLOUD_SECRET_ID "Your SecretId"setx TENCENTCLOUD_SECRET_KEY "Your SecretKey"
Verifying the Installation
In the conversation, enter: List all my log topics across all regions. If a list of log topics (including an empty list) is returned, the installation is successful.
Note:
If your account has no log topics, returning an empty list is also considered a success. If you have any questions, you can enter "View log topics in the Guangzhou region" for further verification.
User Guide
After configuration is complete, you can directly describe your requirements in natural language within the conversation window. When you describe your requirements, it is recommended to include the following elements. The more specific you are, the more accurate the results will be:
Element | Description | Example |
① Region | Guangzhou / Shanghai / Beijing, and so on | Guangzhou |
② Object | Topic name / Service name / Log type | payment-topic |
③ Time Range | Last 1 hour / Today / Last 7 days | Last 1 hour |
④ Action | Searching for errors / Statistical analysis / Viewing context | Error logs |
Complete Example: "Help me check the error logs for the payment-topic in the Guangzhou region over the past hour, and then count the number of each error type."
Vague Query Example: "Has that log topic in Guangzhou reported any errors recently?"
Note:
For a vague query, all topics in that region are first listed, and then recent error logs are checked one by one.
Scenario Practice
Scenario 1: Searching Error Logs in 30 Seconds
When an online error occurs suddenly, quickly identify what the problem is, when it started, and the scope of its impact.
Scenario Description | Example Natural Language |
Basic Search | Query error logs for the default-topic in the Guangzhou region at 6 PM today. |
Add Filter Conditions. | Show only timeout errors for payment-service in the last 30 minutes. |
Filter by Status Code. | Find all requests with a statusCode of 500, sorted in reverse chronological order. |
Applicable scenarios: reviewing last night's errors before the morning meeting, locating issues after an alarm is received, and pulling historical error data during schedule review.
Scenario 2: In-Depth Analysis of Error Distribution
It not only displays a list of errors but also performs statistical analysis by service, error code, and time dimension.
Analysis Objective | Example Natural Language |
Group statistics by service | Count the number of various errors, grouped by service. |
TOP N error categories | Group statistics by error code, showing only the TOP 10. |
Time trend | Hourly error rate change curve for the last 24 hours |
Multi-dimensional cross analysis | Cross statistics by service and error level dimensions |
Scenario 3: Viewing Log Context with One Click
After finding a critical error log, you can view what happened before and after the error, without needing to manually adjust the time range to page through results.
Scenario Description | Example Natural Language |
Viewing Context | Expand the context of this DB_CONNECTION_TIMEOUT log entry, including 2 records before and after it. |
Logs preceding and following the target log are returned to reconstruct the cascading failure chain.
Scenario 4: Quick Troubleshooting of Collection Pipelines
When logs are not being collected, you can complete the diagnosis with a single command, without needing to SSH into each machine for troubleshooting.
Scenario Description | Example Natural Language |
One-click diagnosis of the collection pipeline | Check the server groups and collection configurations associated with this topic for me. |
Automatic Parallel Check: The system checks the machine group list, the online status of the Agent on each machine, the collection configuration, and the configuration binding relationships, and then outputs a complete diagnostic result.
Billing Overview
CLS Skill itself is a free-to-use AI skill package and incurs no additional costs. However, charges for the CLS service used through the Skill are generated based on actual usage. For billing details, please see CLS Billing Overview.
FAQs
Authentication Failure After the Key is Configured for Skill?
1. Ensure that the environment variable names are spelled correctly: TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY.
2. After the configuration is confirmed, restart the terminal or AI tool.
3. Confirm that the key is not expired: You can log in to the CAM console to check its status.
Query Returns Empty Results?
1. Confirm that the log topic name is correct and the region matches.
2. Confirm that logs are indeed being written within the specified time range.
3. Confirm that full-text indexing or key-value indexing is enabled for the topic; otherwise, search is not possible.
Permission Error for SubUser Sub-Account?
Ensure that the sub-account is bound to at least the QcloudCLSReadOnlyAccess policy. To perform management operations, the QcloudCLSFullAccess policy is required.
Query Timeout or Slow Response?
Narrow the time range or add filter conditions.
Help and Support
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback