huawei-cloud-maas-tokens-usage

Imported from huaweicloud/huaweicloud-skills (skills/ai/maas/huawei-cloud-maas-tokens-usage/SKILL.md). Install upstream with npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-maas-tokens-usage. Copyright stays with the author.

Huawei Cloud MaaS Tokens Usage Monitoring Skill

Overview

Query Huawei Cloud MaaS (Model as a Service) usage statistics via the ShowStatistics API, including total tokens, prompt tokens, completion tokens, total requests, and total errors. Supports querying last 7 days, 14 days, 30 days, or custom time ranges. Default query type is MaaS preset service. AK/SK never leaves Python process memory.

Tool separation principle:

• Python SDK signing — AK/SK signing via huaweicloudsdkcore.signer.Signer (credentials never leave Python process memory, never appear in ps -ef)
• Python requests — HTTP POST to MaaS ShowStatistics endpoint (signed request sent from Python process only)
• No hcloud CLI — MaaS ShowStatistics is not covered by KooCLI; pure Python REST + SDK signing

Security architecture:

• AK/SK is read from environment variables (HW_ACCESS_KEY / HW_SECRET_KEY) or a credentials file by the Python script (never typed by user in conversation, never passed via CLI args, never exported to shell)
• Temporary credentials add HW_SECURITY_TOKEN (passed as X-Security-Token header by the SDK signer)
• Signing is performed by huaweicloudsdkcore.Signer inside the Python process; the signed Authorization header is sent to the MaaS endpoint only
• AK/SK is never printed, never logged, never appears in ps -ef, never appears in conversation
• No KMS dependency, no hcloud CLI dependency, no third-party skill dependency

⛔ Prohibited Operations (Security Constraints)

This skill strictly forbids the following operations, regardless of user requests:

If a user requests a prohibited operation, you must refuse and explain the security constraint.

🚫 Unsupported Operations (Capability Boundary)

This skill only supports the ShowStatistics aggregate statistics query. The MaaS monitoring API family contains 10 APIs; the other 9 are outside this skill's capability boundary and are not implemented.

If a user requests any of the above APIs or their underlying capabilities (per-service breakdown, error detail, chart data, source IP list, version statistics, error code distribution, etc.), you must refuse and clarify: this skill only supports the ShowStatistics aggregate statistics query (total/prompt/completion tokens, request count, error count, error rate).

Architecture

Huawei Cloud MaaS Tokens Usage Monitoring
├── Task 1: Query MaaS Tokens Usage Statistics (via MaaS ShowStatistics API)
│   ├── 1a. Load credentials    (env vars or --credentials-file, in Python memory only)
│   ├── 1b. Resolve time range  (last 7/14/30 days, this month, or custom YYYY-MM-DD)
│   ├── 1c. Auto-segment        (split ranges > 30 days, aggregate results)
│   ├── 1d. SDK sign request    (huaweicloudsdkcore.Signer, AK/SK in process memory)
│   ├── 1e. POST ShowStatistics (modelarts.{region}.myhuaweicloud.com)
│   ├── 1f. Aggregate & convert (token unit: thousand → M tokens)
│   └── 1g. Print table         (Total/Prompt/Completion Tokens, Requests, Errors, Error Rate)
└── Task 2: Verify & Report     (compare with console, check error rate)

Prerequisites

Prerequisite check 1/3: Python 3.8+ and huaweicloudsdkcore required

The MaaS ShowStatistics query script uses Python to keep AK/SK in process memory only. Install the required packages:

# Auto-use China mirror when system timezone is UTC+8 (faster in CN region; auto-detected via Python)
PIP_INDEX=$(python3 -c "import time;print('-i https://mirrors.huaweicloud.com/repository/pypi/simple' if -(time.timezone)//3600==8 else '')")
pip install $PIP_INDEX huaweicloudsdkcore requests

Verify SDK installation:

python3 --version                          # Expected: >= 3.8
python3 -c "import huaweicloudsdkcore; print('SDK OK')"
python3 -c "import requests; print('requests OK')"

Prerequisite check 2/3: Environment variables for Python SDK credentials (highest priority)

The query script (maas_rest_usage_stats.py) reads credentials from environment variables or a credentials file. The following environment variables MUST be set before running the script (unless --credentials-file is used):

Variable	Required	Description
HW_ACCESS_KEY	Yes	Huawei Cloud Access Key ID (AK)
HW_SECRET_KEY	Yes	Huawei Cloud Secret Access Key (SK)
HW_SECURITY_TOKEN	No	Temporary security token (only for temporary AK/SK)

# Linux — verify HW_ACCESS_KEY / HW_SECRET_KEY are set (values never printed)
python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
# Windows (cmd / PowerShell)
python -c "import os,sys;ak=os.environ.get('HW_ACCESS_KEY','');sk=os.environ.get('HW_SECRET_KEY','');ok=bool(ak) and bool(sk);print('AK/SK configured OK' if ok else 'ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set');sys.exit(0 if ok else 1)"

If verification reports ERROR (variables not set), configure them:

• Linux: add export HW_ACCESS_KEY=... / export HW_SECRET_KEY=... to your shell profile (~/.bashrc, ~/.zshrc) or a secrets manager, then source the profile.
• Windows: set system environment variables via the GUI (System Properties → Advanced → Environment Variables → System variables → New). See references/cli-installation-guide.md "Windows GUI Setup" for step-by-step instructions. Avoid setx (it records credentials in command history).

⚠️ Never set these variables in conversation or hardcode them in scripts. After setting, restart the terminal/Python process and re-run the verification above.

Prerequisite check 3/3: MaaS service region limitation

• Region: cn-southwest-2 (Southwest-Guiyang-1) — the only region supported by MaaS ShowStatistics API
• API retention: 30 days of statistics data
• Rate limit: total requests ≤ 1000/min, per-user ≤ 200/min

Authentication

Security rules (must be followed):

• Prohibited from reading, echoing, or printing AK/SK values
• Prohibited from asking the user to input AK/SK directly in the conversation
• Prohibited from using hcloud configure set to pass plaintext credential values
• Prohibited from accepting AK/SK directly provided by the user in the conversation
• Only allowed to read credentials from environment variables or a credentials file

⚠️ Important: Handling user-provided credentials

If a user attempts to provide AK/SK directly (e.g., "my AK is xxx, SK is yyy"):

1. Stop immediately — Do not execute any commands
2. Politely refuse and return the following message:

   For account security, please do not provide Huawei Cloud Access Key ID and Access Key Secret directly in the conversation.
   
   Please use one of the following secure methods to configure credentials:
   
   Method 1: Environment variables (permanent AK/SK)
       export HW_ACCESS_KEY=<your-access-key-id>
       export HW_SECRET_KEY=<your-access-key-secret>
   
   Method 2: Environment variables (temporary AK/SK + Security Token)
       export HW_ACCESS_KEY=<your-temp-access-key-id>
       export HW_SECRET_KEY=<your-temp-access-key-secret>
       export HW_SECURITY_TOKEN=<your-security-token>
   
   Method 3: Credentials file
       Create a file (e.g., ~/aksk.txt) with AK on line 1, SK on line 2, Security Token on line 3 (if using temporary credentials).
       Then use: --credentials-file ~/aksk.txt
   
   After configuration is complete, please retry your request.
   

3. Do not continue executing any Huawei Cloud operations until credentials are configured

IAM Permission Policies

Ensure the IAM user has the required permissions (ModelArts monitoring + IAM read, scoped to the MaaS query workflow only). See references/iam-policies.md for the full permission table and recommended IAM policy JSON.

Permission boundaries:

• Scope constraint: Only query MaaS statistics data (read-only). Never modify or delete any MaaS service, endpoint, or configuration.
• Must stop if: credentials missing or invalid, user declines any confirmation, API returns 403/401, or time range exceeds 30 days and segmentation fails.
• Prohibited actions: modifying MaaS services, deleting API keys, changing IAM policies, accessing resources outside the MaaS query workflow, running commands not documented in this skill.

Core Workflows

Task 1: Query MaaS Tokens Usage Statistics

Query MaaS usage statistics via the ShowStatistics API. Data is consistent with the Huawei Cloud console.

⚠️ Tool separation: Python SDK signing + Python requests

• Python SDK (huaweicloudsdkcore.Signer): Signs the request with AK/SK. Credentials never leave Python process memory.
• Python requests: Sends the signed HTTP POST to the MaaS endpoint. No CLI, no shell variable, no ps -ef leakage.

📄 Detailed steps → references/task-query-tokens-usage.md

Sub-tasks:

1. 1a. Load credentials — Read HW_ACCESS_KEY / HW_SECRET_KEY / HW_SECURITY_TOKEN from env vars, or read from --credentials-file (supports one-per-line, comma-separated, KEY=VALUE formats)
2. 1b. Resolve time range — Parse --from / --to (YYYY-MM-DD), or map user expression ("last 7 days" / "last 14 days" / "last 30 days" / "this month") to a rolling/calendar window
3. 1c. Auto-segment — If time range exceeds 30 days, split into multiple ≤ 30-day segments and aggregate results
4. 1d. SDK sign request — Signer(_Creds(ak, sk)).sign(sdk_request) — AK/SK in Python process memory only
5. 1e. POST ShowStatistics — requests.post("https://modelarts.{region}.myhuaweicloud.com/v1/{project_id}/maas/monitoring/show-statistics", headers=signed_headers, data=body_bytes)
6. 1f. Aggregate & convert — Sum segment results; convert token unit (thousand → M tokens, actual = value × 1000)
7. 1g. Print table — Output Total Tokens / Prompt Tokens / Completion Tokens / Total Requests / Total Errors / Error Rate + Period

Task 2: Verify & Report

Compare the API result with the Huawei Cloud console and report the error rate.

📄 Acceptance criteria → references/acceptance-criteria.md

⚠️ Small discrepancy is normal. API vs. console may differ by < 0.1% due to minor time boundary differences. Data is reliable.

Core Commands

Python Script (SDK signing + requests — AK/SK never in ps -ef)

⚠️ Key constraints on Core Commands:

• MaaS query: MUST use scripts/maas_rest_usage_stats.py — AK/SK never in ps -ef
• Credentials: MUST use env vars or --credentials-file — never hardcode, never pass via CLI args
• --service-type: MUST be 1, 2, or 4 — never 3 (API returns 400)
• --region: MUST be cn-southwest-2 (default) — the only supported region
• Time range: MUST match user expression exactly — "last 7 days" ≠ "this month"

Parameter Confirmation

Before executing any task, the following parameters must be confirmed with the user. Guessing is prohibited.

Note: No AK/SK parameter is required. Credentials are read from environment variables or a credentials file by the Python script. AK/SK is never exported from the Python process.

Script Tools

⚠️ Script usage rules:

• Must use the existing script; do not write a new query script as a replacement
• Do not split the script internal logic into individual curl/HTTP commands
• Do not implement SDK-HMAC-SHA256 signing manually — must use huaweicloudsdkcore.Signer

Verification Method

See references/verification-method.md for details. For common issues and solutions, see references/troubleshooting.md.

Quick validation (permanent AK/SK):

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");ok=bool(ak) and bool(sk);print("AK/SK configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

Quick validation (temporary AK/SK + Security Token):

python3 -c 'import os,sys;ak=os.environ.get("HW_ACCESS_KEY","");sk=os.environ.get("HW_SECRET_KEY","");st=os.environ.get("HW_SECURITY_TOKEN","");ok=bool(ak) and bool(sk) and bool(st);print("Temp AK/SK + Token configured OK" if ok else "ERROR: HW_ACCESS_KEY/HW_SECRET_KEY/HW_SECURITY_TOKEN not set");sys.exit(0 if ok else 1)'
python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21

⚠️ Credential reminder: AK/SK is read from environment variables or a credentials file by the Python script. If you need to configure credentials, see references/cli-installation-guide.md.

Security Design

The security architecture keeps AK/SK exclusively in Python process memory — never in ps -ef, shell variables, environment variables (read-only access), or conversation. Tool separation: Python SDK signing for AK/SK authentication, Python requests for HTTP POST to the MaaS endpoint. Credentials are never printed, never logged, never exported. Temporary credentials add HW_SECURITY_TOKEN as the X-Security-Token header via the SDK signer.

📄 Full details (tool separation table, credential leakage risk elimination, credential lifecycle) → references/security-design.md

References