/alibabacloud-mtr-network-diagnosis-customer

name: alibabacloud-mtr-network-diagnosis-customer
description: >
  Public network MTR diagnosis tool. Supports both manual guidance and Cloud Assistant automation modes.
  Manual mode guides users to run MTR tools locally (macOS/Linux/Android/Windows) and analyze result screenshots.
  Automated mode remotely executes mtr/ping/curl diagnostics on ECS instances via Alibaba Cloud Cloud Assistant.
  Applicable to public network access failures, high latency, packet loss, SLB health check failures, NAT outbound packet loss, etc.
  Use this skill when users encounter network connectivity issues, need to troubleshoot public network link quality, or analyze MTR screenshots.
license: Apache-2.0
metadata:
  domain: aiops
  owner: network-team
  contact: network-team@alibaba-inc.com

Public Network MTR Diagnosis

Use Cases

| Scenario | Typical Issues | |----------|---------------| | **Public network access failure** | Connection refused, timeout, intermittent disconnection | | **High or unstable latency** | Large jitter, latency spikes during specific time periods | | **Packet loss** | Persistent packet loss, intermittent packet loss | | **SLB/CLB health check failure** | Backend ECS health check fails, link troubleshooting needed | | **Cross-region public network access** | Poor link quality between ECS instances across regions | | **NAT Gateway outbound issues** | Packet loss / high latency when ECS behind NAT accesses external targets | | **EIP bandwidth throttling** | Packet loss at fixed bandwidth threshold |

Prerequisites

This Skill supports two modes:

**Manual mode**: No dependencies. Guides users to run MTR tools locally and provide result screenshots for analysis.

**Automated mode (Cloud Assistant)**:

• **Python 3.7+** (required) — scripts use standard library only, no third-party dependencies
• **aliyun CLI** (required): macOS `brew install aliyun-cli`; Linux download from [aliyuncli.alicdn.com](https://aliyuncli.alicdn.com)
• **Alibaba Cloud credentials**: Relies on aliyun CLI's default credential chain — environment variables (`ALIBABA_CLOUD_ACCESS_KEY_ID/SECRET`), CLI profile (`~/.aliyun/config.json`), or ECS RAM Role
• **ECS Cloud Assistant agent**: The target ECS instance must have Cloud Assistant agent installed and running
• **Network access**: ISP identification relies on ipinfo.io API (free, no token required). Automatically falls back to backbone prefix matching when unreachable

aliyun CLI Configuration

Before using the automated mode, ensure the aliyun CLI is properly configured:

Plugin Update

Run `aliyun plugin update` to ensure the ECS plugin is up-to-date. All CLI commands in this Skill use plugin mode (lowercase-hyphenated format, e.g., `run-command`, `describe-instances`). The bundled scripts automatically fall back to the equivalent native OpenAPI form only when the ECS plugin is unavailable in the runtime environment.

> For permission details, see [ram-policies.md](references/ram-policies.md). run-command is an execution-level operation and requires user confirmation on each invocation.

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char hex string) once for the entire session. Use it as `{session-id}` below, and export it as the `SKILL_SESSION_ID` environment variable before invoking any bundled script (e.g. `export SKILL_SESSION_ID={session-id}`), so the scripts reuse the same session ID in their `--user-agent`.

**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.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-mtr-network-diagnosis-customer/{session-id}

Example (assuming session-id is `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`):

aliyun ecs describe-instances --biz-region-id cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-mtr-network-diagnosis-customer/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Do not skip, alter the format, or omit `--user-agent` on any `aliyun` command invocation.

> For RAM permissions details, see [references/ram-policies.md](references/ram-policies.md).

Core Principles

> **Bidirectional MTR is mandatory**: Unidirectional testing is incomplete. Forward and reverse paths may differ (asymmetric routing). Always guide both client→server and server→client testing. **Exception**: When the target is an uncontrollable public address (e.g., public DNS such as 8.8.8.8 or 223.5.5.5, or any host you cannot log into), reverse MTR from the target back to the source may be impossible. In such cases, perform forward MTR from the source to the target. **You MUST explicitly tell the user (in the user's language)**: "Since the target [target] is an uncontrollable public address, reverse MTR cannot be initiated from the target side; this analysis is based on forward MTR results. It is recommended to supplement reverse testing from another vantage point (e.g., a cloud server on a different ISP or in a different region) to verify the return path." Record this limitation and the suggestion in the final report. > > **TCP MTR for supplementary verification**: When intermediate hops in ICMP MTR show high packet loss but the final destination is normal, or when ICMP is blocked by a firewall, use `mtr --tcp -P <port>` for TCP mode verification. > > **Cloud Assistant is mandatory for ECS operations**: When the user provides an ECS instance, ALL operations — including checking tool availability (`which mtr`), installing packages, running MTR, and collecting results — MUST be executed **remotely on the ECS** via Cloud Assistant scripts. **NEVER** run diagnostic commands (e.g. `which mtr`, `mtr --version`, `ping`, `mtr`) on the local machine or agent environment. The diagnosis targets the remote ECS's network, not the local environment. > > **User confirmation required before installing softw