Diagnostic skill-AnalyticDB(AnalyticDB)-阿里云帮助中心

The AnalyticDB for MySQL Diagnostic Skill (alibabacloud-analyticdb-mysql-copilot) is built into ADBAgent and enables cluster queries, performance monitoring, slow query diagnostics, and table-level analysis through natural language conversations.

In the ADBClaw platform chat box, enter / and select /alibabacloud-analyticdb-mysql-copilot from the slash command list to activate the diagnostic skill.

Prerequisites

Create a RAM role

In the Resource Access Management (RAM) console, create a RAM role named adbclaw-diagnosis-role. For trusted entity type, select Alibaba Cloud Service. For Trusted service, select AnalyticDB for MySQL. For detailed instructions, see Create a RAM role for a trusted Alibaba Cloud service.

The trust policy for the role is configured as follows:
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::1358535755******:root"
        ],
        "Service": [
          "ads.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}
```

Grant permissions

Grant the RAM role the permissions required for the Diagnostic Skill. For detailed instructions, see Grant permissions to a RAM role.

Note

If this role does not exist when you enable ADBAgent, it may take up to 5 minutes for the role to take effect after you create it.

System policy

To use the Diagnostic Skill, attach any of the following system policies to the RAM role:

Policy name	Description
`AliyunADBReadOnlyAccess`	Grants read-only access to AnalyticDB for MySQL. Recommended for operations and diagnostics to prevent accidental modifications.
`AliyunADBDeveloperAccess`	Grants developer access to AnalyticDB for MySQL, supporting both diagnostics and read/write operations.
`AliyunADBFullAccess`	Grants full access to AnalyticDB for MySQL. Not recommended. Includes all read and write operations. Use with caution.

Custom policy

If you need fine-grained control over permissions, you can create a custom policy. The policy must include at least the following permissions:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "adb:DescribeDBClusters",
        "adb:DescribeDBClusterAttribute",
        "adb:DescribeDBClusterPerformance",
        "adb:DescribeDBClusterSpaceSummary",
        "adbai:DescribeChatMessage"
      ],
      "Resource": "*"
    }
  ]
}

Enable the public endpoint

The Diagnostic Skill requires an internet connection. To enable it, see Step 5: (Optional) Enable the public endpoint.

Key features

Cluster query

Query cluster lists and attributes for a complete overview of your cluster assets.

Supported queries:

Cluster list (filterable by region)
Detailed cluster properties, such as specifications, version, and status
Storage space overview

In the ADBClaw chat interface, select the /alibabacloud-analyticdb-mysql-copilot skill and the qwen3-max model. Enter a natural language query in the input box, such as "Help me find my AnalyticDB for MySQL instances in China (Zhangjiakou) and their space overview", and click Send.

Slow query diagnostics

Detect bad SQL, analyze SQL patterns, and trace root causes in a single conversational step.

Diagnostic capabilities:

Bad SQL detection: Automatically identifies abnormal SQL queries that affect cluster stability.
SQL pattern analysis: Aggregates SQL pattern metrics such as average duration, maximum duration, and scanned data volume, with sorting by multiple dimensions.
Running SQL analysis: View currently executing SQL queries to identify high-resource-consumption operations.

In the ADBClaw platform, select the /alibabacloud-analyticdb-mysql-copilot skill. In the chat input box, enter a slow query diagnostics request, such as For the China (Zhangjiakou) instance amv-8vb519f35856z4gd, run slow query diagnostics for the last 2 hours. Select the qwen3-max model and click Send.

Space diagnostics

Runs multiple checks in parallel and generates a consolidated cluster health report.

Diagnostic scope:

Detection of oversized non-partitioned tables
Partition design diagnostics
Primary key design diagnostics
Data skew diagnostics
Replicated table usage diagnostics
Optimization suggestions for idle indexes
Optimization suggestions for hot/cold tables

In the ADBClaw platform, select the /alibabacloud-analyticdb-mysql-copilot skill. In the input box, enter a space diagnostics request, such as "Run space diagnostics on the China (Zhangjiakou) instance amv-8vb519f35856z4gd". Select the qwen3-max model and click Send.

Usage examples

Enter the following natural language instructions in the ADBAgent dialog box to run diagnostic operations:

Scenario	Natural language instruction
Find an instance	What AnalyticDB for MySQL instances are available in the China (Hangzhou) region?
Slow query diagnostics	Perform slow query diagnostics on instance amv-xxx in China (Zhangjiakou) for the last 2 hours.
Space diagnostics	Run space diagnostics on instance amv-xxx in China (Zhangjiakou).
Data skew	Are there any tables with data skew in instance amv-xxx? Check the skew status of fact tables.
Partition reasonableness	Run a partition design diagnosis on amv-xxx to see if any tables have poorly designed partitions.
Oversized non-partitioned table	Check for oversized non-partitioned tables in amv-xxx.
Replicated table diagnostics	Run replicated table diagnostics on amv-xxx. Are there any inefficiently used replicated tables?
Idle index	Does amv-xxx have any idle indexes that I can remove? I want to reduce storage and write overhead.
Hot/cold table optimization	Provide hot/cold table optimization recommendations for amv-xxx. Which tables can be moved to cold storage?

FAQ

Unresponsive skill or unrecognized instructions

Check the following items in order:

The format of the cluster ID (am-xxx or amv-xxx)
The specified region
The role configuration
The public NAT gateway configuration

Insufficient permissions

If an API call fails with a permission error, grant the required RAM permission to your account.

Query returns no results

If a query returns no results, confirm the following:

The time range is reasonable (by default, the query covers the last 1 hour).
The cluster is running properly.
Diagnostic data is available (for example, optimization suggestions are generated in the early morning each day and may not yet be available for the current day).