git:20260529.9d42b60 to git:20260901.e8b6b01
217 added, 40 removed. Audit A to A.
---
name: huawei-cloud-maas-tokens-usage
description: |
Query Huawei Cloud MaaS (Model as a Service) tokens usage statistics, including total tokens, prompt tokens, completion tokens, total requests, and total errors. Supports preset service, my service, and custom endpoint with time range queries (last 7/14/30 days or custom). Data source is MaaS ShowStatistics API, consistent with console.
Use this skill when the user wants to: (1) query MaaS token consumption statistics, (2) check MaaS service request counts and error rates, (3) analyze token usage for preset service or my service, (4) monitor MaaS usage over a specific time period.
Trigger: user mentions "MaaS", "Model as a Service", "tokens usage", "token consumption", "request count", "error count", "MaaS usage", "preset service usage", "completion tokens", "prompt tokens", "MaaS statistics", "模型服务", "令牌用量", "token统计", "token用量", "词元用量", "请求次数", "MaaS监控", "华为云MaaS"
+ tags: ["maas", "tokens usage", "model as a service"]
---
- # Huawei Cloud MaaS Tokens Usage Monitoring
+ # Huawei Cloud MaaS Tokens Usage Monitoring Skill
- Query Huawei Cloud MaaS (Model as a Service) usage statistics, 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.
+ ## 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:**
+
+ | Prohibited Operation | Reason |
+ |---------------------|--------|
+ | ❌ Ask the user to provide AK/SK directly in the conversation | Credentials must never appear in conversation |
+ | ❌ Accept AK/SK directly provided by the user in the conversation | Credentials must never appear in conversation |
+ | ❌ Hardcode AK/SK in scripts or command-line arguments | Credential exposure risk |
+ | ❌ Use `hcloud configure set` to pass plaintext AK/SK values | Credentials recorded in command history |
+ | ❌ Print or log the AK/SK values in any output | Credentials must only exist in Python process memory |
+ | ❌ Export AK/SK to shell variables or stdout via the script | Credentials must stay in Python process; only statistics result is printed |
+ | ❌ Implement SDK-HMAC-SHA256 signing manually | Error-prone; must use `huaweicloudsdkcore.Signer` |
+ | ❌ Use `service_type=3` for Custom Endpoint | API only supports `[1, 2, 4]`; returns 400 error |
+ | ❌ Hardcode timezone as `CST` or `Asia/Shanghai` | Must auto-detect OS local timezone |
+ | ❌ Query a time range exceeding 30 days without segmentation | API retains only 30 days; script must auto-segment |
+ | ❌ Use a region other than `cn-southwest-2` | MaaS ShowStatistics only supports Southwest-Guiyang-1 |
+ | ❌ Write a new query script instead of using `maas_rest_usage_stats.py` | Must use the script in `scripts/` directory |
+
+ > **If a user requests a prohibited operation, you must refuse and explain the security constraint.**
+
## Architecture
```
Huawei Cloud MaaS Tokens Usage Monitoring
- └── GetMaaSTokensUsage (via MaaS ShowStatistics API)
+ ├── 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: Python3 + huaweicloudsdkcore required**
+ > **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:
> ```bash
- > python3 --version # Python3 >= 3.8
- > python3 -c "import huaweicloudsdkcore; print('OK')" # SDK signing library
+ > # 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
> ```
- > If SDK not installed: `pip3 install --user huaweicloudsdkcore`
+ >
+ > Verify SDK installation:
+ > ```bash
+ > 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) |
+ >
+ > ```bash
+ > # 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](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
- > **Prerequisite check: Huawei Cloud credentials required**
-
> **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 credentials file
-
+ > - **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
+ > 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
+ > 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: Credentials file
- > Create a file (e.g., ~/aksk.txt) with AK on line 1, SK on line 2.
+ > 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
- > **Check environment variables**:
- > ```bash
- > echo $HW_ACCESS_KEY # Check if AK is set
- > ```
- > If not set, prompt the user to configure credentials using one of the methods above.
-
---
## IAM Permission Policies
- Ensure the IAM user has the required permissions. See [references/iam-policies.md](references/iam-policies.md) for details.
+ Ensure the IAM user has the required permissions (ModelArts monitoring + IAM read, scoped to the MaaS query workflow only). See [references/iam-policies.md](references/iam-policies.md) for the full permission table and recommended IAM policy JSON.
- **Minimum required permissions:**
- - `modelarts:monitoring:get` — Query MaaS monitoring statistics
- - `modelarts:service:get` — Query service information
- - `iam:projects:get` — Auto-get project_id
+ **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 Workflow
+ ## Core Workflows
### Task 1: Query MaaS Tokens Usage Statistics
- Query MaaS usage statistics via the ShowStatistics API. Data is consistent with the console.
+ 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](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](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.
+
---
- ## Verification
+ ## Core Commands
- See [references/verification-method.md](references/verification-method.md).
+ ### Python Script (SDK signing + requests — AK/SK never in ps -ef)
- **Quick verification:**
+ | Command | Description |
+ |---------|-------------|
+ | `pip install huaweicloudsdkcore requests` | Install Python SDK signing library + HTTP client (for UTC+8, add `-i https://mirrors.huaweicloud.com/repository/pypi/simple`) |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21` | Query preset service usage (default `--service-type 2`) for the given date range |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 1` | Query My Service usage |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --service-type 4` | Query Custom Endpoint usage |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --infer-type batch` | Query batch inference usage (default `real_time`) |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --api-keys key1 key2` | Filter by API Key list |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --credentials-file /path/to/aksk.txt` | Use credentials file instead of env vars |
+ | `python3 scripts/maas_rest_usage_stats.py --from 2026-05-08 --to 2026-05-21 --raw` | Show raw API response (for debugging) |
+
+ > **⚠️ 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.**
+
+ | Parameter | Required/Optional | Description | Default |
+ |-----------|-------------------|-------------|---------|
+ | Time range | Required | `--from` / `--to` (YYYY-MM-DD), or user expression ("last 7 days", "last 14 days", "last 30 days", "this month") | Last 7 days |
+ | Service type | Optional | `--service-type`: 1=My Service, 2=Preset Service, 4=Custom Endpoint | 2 (Preset Service) |
+ | Inference type | Optional | `--infer-type`: `real_time` (online) or `batch` | `real_time` |
+ | Region | Optional | Huawei Cloud region (only `cn-southwest-2` is supported) | `cn-southwest-2` |
+ | API Keys filter | Optional | `--api-keys` list to filter specific keys | All keys |
+ | Credentials file | Optional | `--credentials-file` path (alternative to env vars) | - |
+ | Raw response | Optional | `--raw` flag to show raw API response | off |
+
+ > **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 | Description |
+ |--------|-------------|
+ | [maas_rest_usage_stats.py](scripts/maas_rest_usage_stats.py) | MaaS ShowStatistics API query script (SDK signing + requests, AK/SK never in `ps -ef`). Auto-segments ranges > 30 days, auto-detects OS local timezone, supports permanent/temporary AK/SK + credentials file. See Core Commands above for usage. |
+
+ > **⚠️ 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](references/verification-method.md) for details. For common issues and solutions, see [references/troubleshooting.md](references/troubleshooting.md).
+
+ **Quick validation (permanent AK/SK):**
```bash
- export HW_ACCESS_KEY=<your-ak>
- export HW_SECRET_KEY=<your-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):**
+ ```bash
+ 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](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/security-design.md)
+
+ ---
+
## References
| Document | Description |
|----------|-------------|
- | [task-query-tokens-usage.md](references/task-query-tokens-usage.md) | Task 1: Query tokens usage statistics |
- | [related-apis.md](references/related-apis.md) | API and parameter details |
- | [iam-policies.md](references/iam-policies.md) | IAM permission policies |
+ | [cli-installation-guide.md](references/cli-installation-guide.md) | Prerequisites + Python SDK + credentials configuration + Windows GUI env var setup |
+ | [task-query-tokens-usage.md](references/task-query-tokens-usage.md) | Task 1: Query tokens usage statistics detailed steps |
+ | [related-apis.md](references/related-apis.md) | MaaS ShowStatistics API and parameter details |
| [maas-metrics.md](references/maas-metrics.md) | MaaS monitoring metrics reference |
- | [verification-method.md](references/verification-method.md) | Verification steps |
+ | [iam-policies.md](references/iam-policies.md) | Required IAM permissions |
+ | [verification-method.md](references/verification-method.md) | Query result verification method |
| [acceptance-criteria.md](references/acceptance-criteria.md) | Correct/error pattern comparison |
- | [cli-installation-guide.md](references/cli-installation-guide.md) | Prerequisites installation guide |
- | [troubleshooting.md](references/troubleshooting.md) | Troubleshooting and practical experience |
- | [maas_rest_usage_stats.py](scripts/maas_rest_usage_stats.py) | ShowStatistics API usage statistics script |
+ | [troubleshooting.md](references/troubleshooting.md) | Common query issues and solutions |
+ | [security-design.md](references/security-design.md) | Security design: tool separation, credential lifecycle |
+ | [maas_rest_usage_stats.py](scripts/maas_rest_usage_stats.py) | ShowStatistics API usage statistics script (AK/SK never in ps -ef) |