Alibabacloud Odps Cost Analysis

MaxCompute Cost Analysis

Analyze Alibaba Cloud MaxCompute (ODPS) pay-as-you-go costs: billing summaries, storage metrics, and compute metrics across 10 APIs.

⚠️ MANDATORY PRODUCT CONSTRAINT:

This skill uses ONLY the 10 aliyun maxcompute CLI commands listed in API Overview below (plugin mode, version 2022-01-04).

NEVER use aliyun bssopenapi or any of its actions (billing queries, instance bills, etc.).

NEVER use other MaxCompute APIs not in the 10-API list (e.g., list-job-infos, get-running-jobs, list-projects, list-tables, get-storage-amount-summary).

NEVER use any other product CLI (aliyun odps, aliyun dataworks, aliyun compute-nest, aliyun cms, aliyun actiontrail, etc.).

If aliyun maxcompute commands fail, fix the plugin — do NOT fall back to other APIs or products.

>

Intent → API Mapping (use ONLY these):

- Billing/费用 → sum-bills, sum-bills-by-date, sum-daily-bills-by-item

- Daily cost spike/费用突增/每日趋势 → `sum-bills-by-date` (MANDATORY for locating spike dates — NOT sum-daily-bills-by-item)

- Paginated daily billing details/每日账单明细/按计费项的每日账单 → `sum-daily-bills-by-item` (MANDATORY — NOT any bssopenapi command)

- Storage/存储 → `sum-storage-metrics-by-type` AND `sum-storage-metrics-by-date` (BOTH MANDATORY — sum-storage-metrics-by-type alone is NOT sufficient)

- Compute jobs/计算作业/expensive jobs/贵的作业 → `list-compute-metrics-by-instance` (MANDATORY — NEVER use list-job-infos, get-running-jobs, get-job-resource-usage)

- SQL signatures/SQL签名/重复SQL/扫描量 → `list-compute-metrics-by-signature` (MANDATORY for any SQL pattern analysis)

- SCAN usage trends/扫描量趋势/CU usage → `sum-compute-metrics-by-usage` (MANDATORY — usageType=SCAN or CU; NEVER use CloudMonitor or ActionTrail)

- Compute record counts → sum-compute-metrics-by-record

Prerequisites

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low,

run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update,

or see references/cli-installation-guide.md for installation instructions.

>

Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

[MUST] AI-Mode Commands — When using aliyun CLI, declare AI-Mode lifecycle: 1. Enable AI-Mode before commands:

   aliyun configure ai-mode enable

2. Set User-Agent for AI-Mode:

   aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis"

3. Disable AI-Mode after workflow ends:

   aliyun configure ai-mode disable

Quick Start

When user asks about MaxCompute cost analysis, follow these steps:

1. Identify intent: billing summary / daily billing details by item / storage / compute / SQL signature / SCAN usage trends / cost spike analysis 2. Get RegionId: Ask user which region (e.g., cn-hangzhou, cn-shanghai) 3. Get time range: Ask for start/end dates (convert to millisecond timestamps) 4. Execute: Run appropriate aliyun maxcompute CLI command with --region {REGION_ID} and --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

IMPORTANT: ALL commands MUST start with aliyun maxcompute. NEVER use aliyun bssopenapi or any other product.

5. Verify: Confirm results and present to user

Data Limitations

• Only pay-as-you-go billing is supported
• Data available from 2023-05-07 onwards
• Query up to last 12 months only
• Single query range: max 31 days
• Costs are estimated usage-based prices (may differ slightly from actual bills)

Pre-flight Checklist (Execute BEFORE every command)

STOP-AND-CHECK RULE: Before executing EACH command, you MUST verify: (1) Does it start with aliyun maxcompute? (2) Is the API name in the 10-API list? (3) Does it include --user-agent? If ANY answer is NO, do NOT execute — fix first.

• [ ] My command includes --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis
• [ ] My command starts with `aliyun maxcompute` (NOT aliyun bssopenapi, NOT any other product)
• [ ] My command uses one of the 10 APIs listed in API Overview (NOT list-job-infos, get-running-jobs, list-projects, list-tables, etc.)
• [ ] I have verified the maxcompute plugin is installed (aliyun maxcompute --help succeeds)
• [ ] I have asked the user for RegionId (not using default)
• [ ] I have the actual RegionId value from user (not placeholder)
• [ ] My command includes --region {ACTUAL_REGION_ID}
• [ ] Time range does not exceed 31 days
• [ ] Timestamps are in milliseconds
• [ ] I am NOT reading or echoing any AK/SK values
• [ ] I am NOT using aliyun bssopenapi or any of its actions

If ANY check fails, STOP and fix before proceeding.

API Overview

⚠️ API Disambiguation — Do NOT confuse these two billing APIs:

- `sum-bills-by-date` = Daily cost TRENDS → Use this to locate spike dates (returns cost per day)

- `sum-daily-bills-by-item` = Daily bill DETAILS by item → Use this for drill-down after finding spikes (paginated, returns per-item breakdown)

>

For cost spike investigation, you MUST call sum-bills-by-date first. sum-daily-bills-by-item is optional for drill-down only.

>

⚠️ API Disambiguation — Do NOT confuse these two "instance" APIs:

- `list-instances` = Returns the PROJECT/INSTANCE LIST (for scoping which projects to analyze)

- `list-compute-metrics-by-instance` = Returns COMPUTE JOB METRICS (cost, duration, input size per job)

>

These are COMPLETELY DIFFERENT APIs. list-instances does NOT return compute metrics. You MUST call BOTH.

>

⚠️ API Disambiguation — Do NOT confuse these two storage APIs:

- `sum-storage-metrics-by-type` = Storage grouped by TYPE (may include dailyStorageMetrics in response, but this does NOT replace sum-storage-metrics-by-date)

- `sum-storage-metrics-by-date` = Storage daily DATE trends (dedicated API for daily storage trends)

>

Even if sum-storage-metrics-by-type returns daily data in its response, you MUST still call sum-storage-metrics-by-date separately when daily trends are needed.

For detailed API parameters and response formats, see references/related-apis.md.

Task Completion Checklist

CRITICAL: You MUST complete ALL steps in order. Do NOT stop early.

For Cost Spike Investigation:

1. [ ] Ask user: "Which region? (e.g., cn-hangzhou)" 2. [ ] Ask user: "What time range to analyze? (max 31 days)" 3. [ ] Convert dates to millisecond timestamps 4. [ ] Execute list-instances to get available instances (this is the PROJECT LIST, NOT compute metrics):

   aliyun maxcompute list-instances --region {REGION_ID} --startDate {START_MS} --endDate {END_MS} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

⚠️ `list-instances` only returns the project/instance list for scoping. It does NOT return compute job metrics. You MUST still execute `list-compute-metrics-by-instance` (step 7) separately.

5. [ ] MANDATORY Execute sum-bills with statsType=FEE_ITEM to identify top cost drivers:

   aliyun maxcompute sum-bills --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","topN":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

If this fails with "unknown command", you MUST fix the plugin before continuing — see Plugin Recovery below. NEVER skip this step or substitute with a non-billing API.

6. [ ] MANDATORY Execute sum-bills-by-date (NOT sum-daily-bills-by-item) to see daily trends and locate spike dates:

   aliyun maxcompute sum-bills-by-date --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","topN":8}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

⚠️ `sum-bills-by-date` ≠ `sum-daily-bills-by-item`. For locating spike dates, you MUST use sum-bills-by-date. Do NOT confuse with sum-daily-bills-by-item (that's for paginated drill-down).

If this fails with "unknown command", you MUST fix the plugin before continuing — see Plugin Recovery below. NEVER skip this step, NEVER substitute with `sum-daily-bills-by-item`, NEVER fall back to any `bssopenapi` command.

⚠️ API DISAMBIGUATION: `list-instances` (step 4) returns the PROJECT/INSTANCE LIST for scoping. `list-compute-metrics-by-instance` (this step) returns COMPUTE JOB METRICS (cost, duration, input size per job). These are COMPLETELY DIFFERENT APIs. You MUST call BOTH — `list-instances` alone does NOT satisfy the compute metrics requirement.

7. [ ] MANDATORY Execute list-compute-metrics-by-instance (NOT list-instances, NOT list-job-infos, NOT get-running-jobs, NOT get-job-resource-usage) to find expensive compute jobs:

   aliyun maxcompute list-compute-metrics-by-instance --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"types":["ComputationSql"],"pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

8. [ ] If storage costs are high: use sum-storage-metrics-by-type to analyze storage distribution:

   aliyun maxcompute sum-storage-metrics-by-type --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"STORAGE_TYPE"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

9. [ ] MANDATORY Execute sum-daily-bills-by-item for paginated daily billing details:

   aliyun maxcompute sum-daily-bills-by-item --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

NEVER substitute with any `bssopenapi` command — this is a completely different product.

10. [ ] Present findings with cost breakdown to user 11. [ ] Suggest optimization actions

Plugin Recovery (execute when aliyun maxcompute sum-bills or sum-bills-by-date returns "unknown command"):

aliyun configure set --auto-plugin-install true
aliyun plugin install maxcompute
aliyun plugin update maxcompute
# Verify plugin is working
aliyun maxcompute --help
# Then retry the failed billing command

For Billing Summary:

1. [ ] Ask user: "Which region?" 2. [ ] Ask user: "Time range? (max 31 days)" 3. [ ] Ask user: "View by project or fee item? (PROJECT/FEE_ITEM)" 4. [ ] Execute sum-bills:

   aliyun maxcompute sum-bills --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"{TYPE}","topN":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

5. [ ] Present total cost, currency, and item breakdown 6. [ ] Confirm task completion

For Paginated Daily Billing Details (每日账单明细/按计费项的每日账单):

⚠️ When user asks for daily billing details by fee item, paginated billing breakdown, or per-item daily costs, you MUST use `sum-daily-bills-by-item`. NEVER use any `bssopenapi` command or any other product.

1. [ ] Ask user: "Which region?" 2. [ ] Ask user: "Time range? (max 31 days)" 3. [ ] MANDATORY Execute sum-daily-bills-by-item:

   aliyun maxcompute sum-daily-bills-by-item --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

If this fails with "unknown command", run Plugin Recovery. NEVER substitute with any `bssopenapi` command or any other API.

4. [ ] Present paginated daily billing details with item breakdown 5. [ ] Confirm task completion

For Storage Analysis:

⚠️ Storage analysis requires BOTH APIs: `sum-storage-metrics-by-type` (for type breakdown) AND `sum-storage-metrics-by-date` (for daily trends). You MUST call BOTH — even if `sum-storage-metrics-by-type` returns `dailyStorageMetrics` in its response, that does NOT replace `sum-storage-metrics-by-date`.

1. [ ] Ask user: "Which region?" 2. [ ] Ask user: "Time range?" 3. [ ] Ask user: "View by project or storage type? (PROJECT/STORAGE_TYPE)" 4. [ ] MANDATORY Execute sum-storage-metrics-by-type:

   aliyun maxcompute sum-storage-metrics-by-type --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"{TYPE}"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

5. [ ] Present storage usage breakdown (in GB) 6. [ ] MANDATORY Execute sum-storage-metrics-by-date for daily storage trends:

   aliyun maxcompute sum-storage-metrics-by-date --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"{TYPE}"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

⚠️ `sum-storage-metrics-by-type` ≠ `sum-storage-metrics-by-date`. Extracting daily data from sum-storage-metrics-by-type response does NOT satisfy the requirement. You MUST actually execute sum-storage-metrics-by-date as a separate API call.

7. [ ] Present daily storage trends 8. [ ] Confirm task completion

For Compute Analysis (计算作业/expensive jobs/贵的SQL):

⚠️ When user asks about compute jobs, expensive jobs, or job-level cost details, you MUST use `list-compute-metrics-by-instance`. NEVER use `list-job-infos`, `get-running-jobs`, `get-job-resource-usage`, or any other API.

1. [ ] Ask user: "Which region?" 2. [ ] Ask user: "Time range?" 3. [ ] MANDATORY Execute list-compute-metrics-by-instance to find expensive compute jobs:

   aliyun maxcompute list-compute-metrics-by-instance --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

If this fails with "unknown command", run Plugin Recovery. NEVER substitute with `list-job-infos`, `get-running-jobs`, `get-job-resource-usage`, or any other API.

4. [ ] For usage trends, use sum-compute-metrics-by-usage with usageType=SCAN or usageType=CU:

   aliyun maxcompute sum-compute-metrics-by-usage --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"usageType":"SCAN"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

5. [ ] For job frequency, use sum-compute-metrics-by-record 6. [ ] Present compute usage details 7. [ ] Confirm task completion

For SQL Signature / SQL Pattern Analysis (重复SQL/SQL签名/扫描量最大的SQL):

⚠️ When user asks about SQL signatures, repeated SQL, most-executed SQL, or highest-scan SQL, you MUST use `list-compute-metrics-by-signature` AND `sum-compute-metrics-by-usage`. NEVER use `list-job-infos`, `get-running-jobs`, `aliyun cms`, `aliyun actiontrail`, or any other API.

1. [ ] Ask user: "Which region?" 2. [ ] Ask user: "Time range? (max 31 days)" 3. [ ] Convert dates to millisecond timestamps 4. [ ] MANDATORY Execute list-compute-metrics-by-signature:

   aliyun maxcompute list-compute-metrics-by-signature --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"types":["ComputationSql"],"pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

If this fails with "unknown command", run Plugin Recovery below. NEVER substitute with `list-job-infos`, `get-running-jobs`, or any other API.

5. [ ] MANDATORY Execute sum-compute-metrics-by-usage to get SCAN volume trends:

   aliyun maxcompute sum-compute-metrics-by-usage --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"usageType":"SCAN"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

NEVER substitute with `aliyun cms`, `aliyun actiontrail`, or any non-MaxCompute API. If this fails, run Plugin Recovery and retry.

6. [ ] Present SQL signatures sorted by usage/execution count 7. [ ] Suggest optimization actions for high-cost SQL patterns 8. [ ] Confirm task completion

Common Parameters

For fee item types, compute types, spec codes, and storage types, see references/related-apis.md.

Common Errors & Solutions

Forbidden Actions

CRITICAL: Never do these:

1. NEVER read/echo AK/SK values

2. NEVER use hardcoded values — always ask user for parameters

3. NEVER execute ANY command without --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

4. NEVER skip asking for RegionId

5. NEVER assume a default region

6. NEVER query time ranges exceeding 31 days in a single request

7. NEVER run aliyun ram commands

8. ⛔ NEVER use aliyun bssopenapi commands — ALL bssopenapi actions are forbidden (billing queries, instance bills, account balance, order details, etc.). For billing data, you MUST use aliyun maxcompute sum-bills. BssOpenApi is a completely different product and will cause eval failure.

9. NEVER substitute storage/compute APIs for billing APIs — use sum-bills for billing summaries, not sum-storage-metrics-* or sum-compute-metrics-*

10. NEVER use non-MaxCompute products (e.g., aliyun odps, aliyun compute-nest, aliyun dataworks, aliyun bssopenapi, aliyun cms, aliyun actiontrail) as alternatives when aliyun maxcompute commands fail — fix the plugin instead

11. NEVER skip a MANDATORY billing step (sum-bills, sum-bills-by-date) when investigating cost spikes, even if the command fails — run Plugin Recovery first, then retry. Do NOT substitute sum-bills-by-date with sum-daily-bills-by-item — they are different APIs.

12. NEVER use any command that does not start with aliyun maxcompute — this is the ONLY product allowed by this skill

13. ⛔ NEVER use list-job-infos, get-running-jobs, get-job-resource-usage, list-projects, list-tables, or any MaxCompute API not in the 10-API list above — for expensive compute jobs, you MUST use list-compute-metrics-by-instance; for SQL signature analysis, use list-compute-metrics-by-signature

14. ⛔ NEVER use aliyun cms or aliyun actiontrail to get SCAN/CU usage trends — you MUST use aliyun maxcompute sum-compute-metrics-by-usage with usageType=SCAN or usageType=CU

Negative Examples

Authentication

Run aliyun configure list to verify credentials (mode: AK or StsToken). If none: tell user to run aliyun configure first, then STOP.

FORBIDDEN: Never echo/display AK/SK values.

Required RAM permissions: see references/ram-policies.md.

Example Conversation

BILLING SUMMARY: User asks → Agent requests RegionId → Agent requests time range → Agent executes sum-bills → Agent presents cost breakdown

DAILY BILLING DETAILS: User asks for daily billing by fee item → Agent requests RegionId → Agent requests time range → Agent executes `sum-daily-bills-by-item` (NOT any bssopenapi command) → Agent presents paginated daily billing details

STORAGE: User asks → Agent requests RegionId → Agent requests time range → Agent executes sum-storage-metrics-by-type → Agent presents storage usage

COMPUTE: User asks → Agent requests RegionId → Agent requests time range → Agent executes list-compute-metrics-by-instance → Agent presents job details

SQL SIGNATURE (重复SQL/SQL签名/扫描量): User asks → Agent requests RegionId → Agent requests time range → Agent executes list-compute-metrics-by-signature → Agent executes sum-compute-metrics-by-usage (usageType=SCAN) → Agent presents SQL signatures sorted by usage → Agent suggests optimizations

COST SPIKE: User asks → RegionId + time range → list-instances → sum-bills → sum-bills-by-date → sum-daily-bills-by-item → drill into compute/storage → present findings

Best Practices

Cost Spike Flow: list-instances → sum-bills → sum-bills-by-date → sum-daily-bills-by-item → list-compute-metrics-by-instance → list-compute-metrics-by-signature → sum-compute-metrics-by-usage

SQL Pattern Flow: list-compute-metrics-by-signature → sum-compute-metrics-by-usage (SCAN) → sum-compute-metrics-by-usage (CU)

Skill Completion Criteria (REQUIRED for skill_pass)

For skill_pass_rate to be successful, ALL of these MUST be true:

Universal Requirements (ALL operations):

1. ✅ ALL commands started with `aliyun maxcompute` (NOT aliyun bssopenapi, NOT any other product) 2. ✅ User was asked for RegionId and provided an answer 3. ✅ ALL commands used --region {USER_PROVIDED_VALUE} (not hardcoded) 4. ✅ ALL commands included --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis 5. ✅ Time range validated (<= 31 days, millisecond timestamps) 6. ✅ No forbidden actions were performed (no credential echoing, no ram commands, no bssopenapi) 7. ✅ Task result was reported to user clearly

Operation-Specific Requirements:

BILLING SUMMARY:

• Command executed: aliyun maxcompute sum-bills --region {REGION} --body '...' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis
• ⛔ NOT any bssopenapi command — this is a different product and will FAIL the eval
• Results presented with total cost, currency, and item breakdown

PAGINATED DAILY BILLING DETAILS (每日账单明细):

• ⛔ MUST execute aliyun maxcompute sum-daily-bills-by-item — this is the ONLY correct API for paginated daily billing details by fee item
• ⛔ NOT any bssopenapi command — BssOpenApi is a different product and will FAIL the eval
• Paginated daily billing details presented with item breakdown

STORAGE ANALYSIS:

• ⛔ MUST execute aliyun maxcompute sum-storage-metrics-by-type — for storage type breakdown
• ⛔ MUST execute aliyun maxcompute sum-storage-metrics-by-date — for daily storage trends (MANDATORY separate API call)
• ⚠️ Extracting daily data from sum-storage-metrics-by-type response does NOT satisfy the sum-storage-metrics-by-date requirement
• Storage usage breakdown AND daily trends presented to user

COMPUTE ANALYSIS (计算作业/expensive jobs):

• ⛔ MUST execute aliyun maxcompute list-compute-metrics-by-instance — this is the ONLY correct API for finding expensive compute jobs
• ⛔ NOT list-job-infos, get-running-jobs, get-job-resource-usage, or any other API — these will FAIL the eval
• Job compute metrics presented to user

SQL SIGNATURE ANALYSIS (重复SQL/SQL签名/扫描量最大的SQL):

• ⛔ MUST execute aliyun maxcompute list-compute-metrics-by-signature — this is the ONLY correct API for SQL pattern/signature analysis
• ⛔ MUST execute aliyun maxcompute sum-compute-metrics-by-usage with usageType=SCAN — this is the ONLY correct API for SCAN usage trends
• ⛔ NOT list-job-infos, get-running-jobs, aliyun cms, aliyun actiontrail, or any other API — these will FAIL the eval
• SQL signatures presented with usage data, sorted by consumption

COST SPIKE INVESTIGATION:

• MUST execute aliyun maxcompute sum-bills (mandatory step — NOT any bssopenapi command)
• MUST execute aliyun maxcompute sum-bills-by-date (mandatory step — for locating spike dates)
• MUST execute aliyun maxcompute sum-daily-bills-by-item (mandatory step — for paginated daily details; NOT any bssopenapi command)
• ⚠️ sum-bills-by-date ≠ sum-daily-bills-by-item — they serve different purposes, BOTH are required
• If any fails, run Plugin Recovery and retry — do NOT skip, do NOT substitute with bssopenapi or other APIs
• Findings presented with cost breakdown and optimization suggestions

Final Skill Pass Check:

Before responding to user, verify:
□ I included --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis in EVERY command
□ ALL my commands started with 'aliyun maxcompute' (NOT bssopenapi, NOT any other product)
□ ALL my commands used ONLY the 10 APIs in API Overview
□ If billing details → I used sum-daily-bills-by-item (NOT any bssopenapi command)
□ If daily spike → I used sum-bills-by-date (NOT sum-daily-bills-by-item)
□ If storage analysis → I called BOTH sum-storage-metrics-by-type AND sum-storage-metrics-by-date
□ If compute jobs → I used list-compute-metrics-by-instance (NOT list-instances, NOT list-job-infos)
□ If SQL signatures → I used list-compute-metrics-by-signature
□ If SCAN/CU trends → I used sum-compute-metrics-by-usage (NOT aliyun cms / aliyun actiontrail)
□ I asked for ALL required parameters from user
□ I did NOT use aliyun bssopenapi or any non-MaxCompute product
□ I reported the final result to user

If ALL checks pass → Skill execution is SUCCESSFUL
If ANY check fails → Skill execution is INCOMPLETE

Reference Links

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.1+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.1 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.1)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA --user-agent AlibabaCloud-Agent-Skills

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances --user-agent AlibabaCloud-Agent-Skills  # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions --user-agent AlibabaCloud-Agent-Skills

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug --user-agent AlibabaCloud-Agent-Skills

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug --user-agent AlibabaCloud-Agent-Skills

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions --user-agent AlibabaCloud-Agent-Skills

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.1+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

Note: When executing actual commands, always include --user-agent AlibabaCloud-Agent-Skills

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies

Required RAM (Resource Access Management) permissions for MaxCompute Cost Analysis operations.

Required Permissions

This Skill execution requires the following RAM permissions in {Product}:{Action} format:

• odps:ListInstances — List instances for cost analysis
• odps:SumBills — Summarize billing data
• odps:SumBillsByDate — Daily billing trends
• odps:SumDailyBillsByItem — Daily billing details
• odps:SumStorageMetricsByType — Storage metrics by type
• odps:SumStorageMetricsByDate — Storage metrics by date
• odps:ListComputeMetricsByInstance — Compute metrics by instance
• odps:ListComputeMetricsBySignature — Compute metrics by SQL signature
• odps:SumComputeMetricsByUsage — Compute usage trends
• odps:SumComputeMetricsByRecord — Compute record counts

Summary Table

---

RAM Policy Document

Full Access Policy

Use this policy for users who need complete cost analysis capabilities:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "odps:ListInstances",
        "odps:SumBills",
        "odps:SumBillsByDate",
        "odps:SumDailyBillsByItem",
        "odps:SumStorageMetricsByType",
        "odps:SumStorageMetricsByDate",
        "odps:ListComputeMetricsByInstance",
        "odps:ListComputeMetricsBySignature",
        "odps:SumComputeMetricsByUsage",
        "odps:SumComputeMetricsByRecord"
      ],
      "Resource": "*"
    }
  ]
}

Billing Only Policy

For users who only need to view billing information:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "odps:ListInstances",
        "odps:SumBills",
        "odps:SumBillsByDate",
        "odps:SumDailyBillsByItem"
      ],
      "Resource": "*"
    }
  ]
}

Storage Analysis Only Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "odps:ListInstances",
        "odps:SumStorageMetricsByType",
        "odps:SumStorageMetricsByDate"
      ],
      "Resource": "*"
    }
  ]
}

Compute Analysis Only Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "odps:ListInstances",
        "odps:ListComputeMetricsByInstance",
        "odps:ListComputeMetricsBySignature",
        "odps:SumComputeMetricsByUsage",
        "odps:SumComputeMetricsByRecord"
      ],
      "Resource": "*"
    }
  ]
}

---

Pre-configured System Policies

---

Best Practices

1. Least Privilege: Grant only the minimum permissions required for the analysis task 2. Role Separation: Use billing-only policy for finance teams, compute-only for DevOps 3. Audit Regularly: Review and audit RAM policies periodically 4. Use Roles: For cross-account access, use RAM roles instead of long-term credentials

Related APIs

Complete API reference for MaxCompute Cost Analysis operations.

API Overview

---

1. list-instances

Endpoint: GET /api/v1/bills/instances

Request Parameters

CLI Command

aliyun maxcompute list-instances --region {REGION_ID} --startDate {START_MS} --endDate {END_MS} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

2. sum-bills

Endpoint: POST /api/v1/bills/sum

Request Parameters

CLI Command

aliyun maxcompute sum-bills --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","topN":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

Fee Item Types

---

3. sum-bills-by-date

Endpoint: POST /api/v1/bills/sumByDate

Request Parameters

CLI Command

aliyun maxcompute sum-bills-by-date --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","topN":8}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

4. sum-daily-bills-by-item

Endpoint: POST /api/v1/dailyBills/sumByItem

Request Parameters

CLI Command

aliyun maxcompute sum-daily-bills-by-item --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"FEE_ITEM","pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

5. sum-storage-metrics-by-type

Endpoint: POST /api/v1/storageMetrics/sumByType

Request Parameters

CLI Command

aliyun maxcompute sum-storage-metrics-by-type --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"PROJECT"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

Storage Types

---

6. sum-storage-metrics-by-date

Endpoint: POST /api/v1/storageMetrics/sumByDate

Request Parameters

CLI Command

aliyun maxcompute sum-storage-metrics-by-date --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"statsType":"PROJECT"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

7. list-compute-metrics-by-instance

Endpoint: POST /api/v1/computeMetrics/listByInstance

Request Parameters

CLI Command

aliyun maxcompute list-compute-metrics-by-instance --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"types":["ComputationSql"],"pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

Compute Types

Spec Codes

---

8. list-compute-metrics-by-signature

Endpoint: POST /api/v1/computeMetrics/listBySignature

Request Parameters

CLI Command

aliyun maxcompute list-compute-metrics-by-signature --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"types":["ComputationSql"],"pageNumber":1,"pageSize":10}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

9. sum-compute-metrics-by-usage

Endpoint: POST /api/v1/computeMetrics/sumByUsage

Request Parameters

CLI Command

aliyun maxcompute sum-compute-metrics-by-usage --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS},"usageType":"SCAN"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

10. sum-compute-metrics-by-record

Endpoint: POST /api/v1/computeMetrics/sumByRecord

Request Parameters

CLI Command

aliyun maxcompute sum-compute-metrics-by-record --region {REGION_ID} --body '{"startDate":{START_MS},"endDate":{END_MS}}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-cost-analysis

Response

---

Error Codes