Terminal
Terminal/Skill
Runs a health check on Alibaba Cloud PolarDB MySQL instances and produces a visual HTML report covering resources, space, slow queries and alerts.
By Alibaba Cloud
Works with
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-polardb-mysql-inspectionComprehensive health inspection for PolarDB MySQL instances with visual HTML reports.
Inspection Dimensions:
Architecture: PolarDB MySQL + Aliyun CLI + DAS API + CloudMonitor → HTML/Markdown/Text Report
You do not need to run any scripts manually! This is an AI Agent skill — simply describe your needs in natural language.
Example 1: Single instance inspection
Inspect PolarDB instance pc-bp1715bzkcrateo69
Example 2: Multi-instance inspection
Inspect instances pc-bp1715bzkcrateo69 and pc-bp12n05ogr61b5929
Example 3: Full account inspection (all instances)
Inspect all PolarDB MySQL instances in my account
Example 4: Specify Region
Inspect PolarDB instance pc-bp1715bzkcrateo69 in cn-hangzhou region
Example 5: Resource usage only
Show CPU and memory usage for pc-bp1715bzkcrateo69
Maps to --item resource
Example 6: Slow logs only
Analyze recent slow logs for pc-bp1715bzkcrateo69
Maps to --item slowlog
Example 7: Combined inspection items
Show slow logs and alert history for pc-bp1715bzkcrateo69
Maps to --item slowlog --item alert
Example 8: Batch + specific items
Show CPU usage for all instances in the last 3 days
Maps to --all --days 3 --item resource
Runtime Environment:
Required CLI Tools:
Python Dependencies:
# Uses only Python standard library: subprocess, json, os, sys, datetime
# All Alibaba Cloud API calls are made through aliyun CLI
Installation Verification:
Pre-check: Aliyun CLI >= 3.3.3 required Run
aliyun versionto verify >= 3.3.3. If not installed or version too low, runcurl -fsSL https://aliyuncli.alicdn.com/setup.sh | bashto install/update, or seereferences/cli-installation-guide.mdfor installation instructions. Then [MUST] runaliyun configure set --auto-plugin-install trueto enable automatic plugin installation. Then [MUST] runaliyun plugin updateto ensure that any existing plugins on your local machine are always up-to-date. Routine CLI self-update (>= 3.3.5):aliyun upgrade
Pre-check: Alibaba Cloud Credentials Required
Security Rules:
- NEVER read, echo, or print AK/SK values
- NEVER ask the user to input AK/SK directly in the conversation or command line
- ONLY use
aliyun configure listto check credential statusaliyun configure listCheck the output for a valid profile.
If no valid profile exists, STOP here. Guide the user to configure credentials outside of this session.
This skill uses read-only APIs only. No write permissions are required.
For the full permission policy and descriptions, see references/ram-policies.md.
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
- Read
references/ram-policies.mdto get the full list of permissions required by this SKILL- Use
ram-permission-diagnoseskill to guide the user through requesting the necessary permissions- Pause and wait until the user confirms that the required permissions have been granted
IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance IDs, output paths, time ranges, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
Before any cloud API invocation, read references/manifest.json from this skill's root and use only its top-level non-empty string version as {skill-version}. If the file is missing, invalid, or the field is absent/empty/not a string, STOP and report the error. NEVER invent, guess, or reuse a version from another skill.
Bind version and session to the current skill name and skill root. Before this skill's first cloud API invocation in a conversation, generate a fresh random 32-character lowercase hexadecimal session ID. Reuse that session ID for this skill throughout the conversation; each skill MUST use a distinct session ID. NEVER copy one from documentation, examples, another skill, or a previous conversation, and NEVER send the literal {session-id} placeholder. When switching skills or returning to this skill, reread this skill's manifest; never cross-skill reuse either value.
Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag.
Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.
Markdown examples may omit the flag for brevity. The Agent MUST append the exact flag below to every actual execution, including commands generated or extended at runtime; do not repeat UA boilerplate in every example block.
--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-polardb-mysql-inspection/{session-id} skill-version/{skill-version}"
The entire UA value MUST be double-quoted because it contains a space. Do not skip, alter, or omit it on any aliyun API command.
Script execution: Inject both scoped values inline:
SKILL_SESSION_ID={session-id} SKILL_VERSION={skill-version} python3 scripts/health-inspect.py
Scripts MUST require both values and construct the same UA product.
| Parameter | Required/Optional | Description | Default |
|---|---|---|---|
| DBClusterId | Required (omit with --all) | PolarDB cluster ID (pc-xxx), supports multiple | User must provide |
| RegionId | Optional | Instance region (auto-discovered if not provided) | Auto-discover |
| Days | Optional | Inspection time range (days) | 7 |
| Item | Optional | Specify inspection items (multiple allowed); omit for full inspection | Full |
| Profile | Optional | aliyun CLI profile name | Default profile |
| Output | Optional | Report output directory or file path | ~/Downloads/ |
Item values:
| item | Inspection Content |
|---|---|
resource | CPU/memory/IOPS/connections + Proxy monitoring trends |
space | Space usage Top 20 + auto-increment primary key usage |
slowlog | Slow log statistics |
session | Current session information |
alert | Alert history |
python3 scripts/health-inspect.py <CLUSTER_ID> [options]
CLI Arguments:
| Argument | Short | Description |
|---|---|---|
CLUSTER_ID | (positional) | PolarDB cluster ID, supports multiple; omit with --all |
--all | Inspect all PolarDB MySQL instances in the current account | |
--region | -r | Specify Region (auto-discovers if not specified) |
--days | -d | Inspection time range (days), default 7 |
--item | Specify inspection item (can be used multiple times); omit for full. Options: resource, space, slowlog, session, alert | |
--profile | -p | Specify aliyun CLI profile name |
--output | -o | Specify report output directory or file path |
--format | -f | Report format: html (default), markdown, text |
Examples:
# Single instance (auto-discover Region)
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69
# Multi-instance
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69 pc-bp12n05ogr61b5929
# All instances in account
python3 scripts/health-inspect.py --all
# All instances in specific Region
python3 scripts/health-inspect.py --all --region cn-hangzhou
# Custom time range (last 3 days)
python3 scripts/health-inspect.py --all --days 3
# Custom time range (last 30 days)
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69 --days 30
# Resource usage only (CPU/memory/IOPS/connections)
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69 --item resource
# Slow logs and alerts only
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69 --item slowlog --item alert
# Batch + specific items
python3 scripts/health-inspect.py --all --item resource --item slowlog
# Custom output directory
python3 scripts/health-inspect.py --all -o /tmp/polardb_report
# Full parameters
python3 scripts/health-inspect.py pc-bp1715bzkcrateo69 -p myprofile -r cn-hangzhou -d 14 -o ./report
The script completes all inspection steps automatically. For multi-instance runs, reports are output to a single directory with a summary page (index.html).
For manual step-by-step API call details, see
references/manual-workflow.md(only use when the script is unavailable).
For report output format templates (text + HTML/ECharts layout specs), see
references/report-format.md(only reference when adjusting report styles).
Core Rule: All inspections MUST be executed via
python3 scripts/health-inspect.py. The script encapsulates all correct API calls internally. The AI MUST NOT callaliyunCLI directly to collect inspection data.
health-inspect.py. The AI must not bypass the script by running aliyun polardb, aliyun cms, aliyun das, etc. The only aliyun commands allowed for direct AI invocation are: aliyun configure list (check credentials), aliyun version (check version), aliyun configure set (set configuration), aliyun plugin (plugin management)describe-metric-list / describe-metric-data: Performance monitoring data is obtained by the script via PolarDB native APIs (describe-db-cluster-performance, describe-db-node-performance, describe-db-proxy-performance). NEVER use aliyun cms describe-metric-list as a substituteSELECT ... FROM information_schema)reset-account-password, create-account, modify-db-cluster* or any other APIs that modify instance state--allhealth-inspect pc-xxx pc-yyyhealth-inspect pc-xxx--item parameters
--item resource--item space--item slowlog--item session--item alert--item (e.g., --item resource --item slowlog)--item, default to full inspection--all has built-in instance discoverypython3 scripts/health-inspect.py <params> — one command completes all data collectionA successful inspection produces:
✅ completion markers for each data collection phase📄 Report saved: {path} (single instance) or 📊 Summary report: {path} (multi-instance)For detailed verification steps including report content checks and error state identification, see references/verification-method.md.
This skill is read-only:
--all for full-account inspection: Instead of manually collecting instance IDs, use the --all flag which has built-in instance discovery across all regions (or a specific region with --region).--days based on the investigation scope: Default is 7 days. Use shorter ranges (1-3 days) for recent incident analysis; use longer ranges (14-30 days) for trend analysis.--item to focus on specific dimensions: When the user only cares about a specific aspect (e.g., slow queries), specifying --item slowlog reduces API calls and speeds up the inspection.aliyun version >= 3.3.3 and run aliyun plugin update to avoid stale plugin issues.scripts/health-inspect.py — One-command inspection main scriptscripts/find-instance-region.py — Auto-discover instance Regionscripts/check-write-operation.sh — Write operation detection hookreferences/manifest.json — Skill name and version metadatareferences/manual-workflow.md — Manual step-by-step API call detailsreferences/report-format.md — Inspection report output format specification (text + HTML/ECharts)references/ram-policies.md — Required RAM permission policyreferences/acceptance-criteria.md — Correct/incorrect invocation patternsreferences/verification-method.md — Script execution and report content verificationreferences/related-commands.md — Cloud API and local utility command reference