az-scout-plugin-latency-stats

az-scout plugin for inter-region and inter-zone (Availability Zone) latency statistics.

Features

• Latency dataset — static latency matrix based on Microsoft published statistics
• Cloud63 dataset support — optional inter-region crowd-sourced measurements via mode="cloud63"
• Inter-zone dataset support — benchmark-based AZ latency matrix from Cloud63 benchmark API
• API endpoints — inter-region and inter-zone endpoints for matrix and available regions
• MCP tools — inter_region_latency(...) for inter-region RTT and inter_zone_latency(...) for inter-zone P50 RTT latency in µs
• UI tab — interactive D3.js views with inter-region/inter-zone scope switch, map/table synchronization, and bidirectional hover highlighting
• URL hash routing — #latency-stats selects the plugin tab

Setup

uv pip install az-scout-plugin-latency-stats
az-scout  # plugin is auto-discovered

For development:

git clone https://github.com/az-scout/az-scout-plugin-latency-stats
cd az-scout-plugin-latency-stats
uv sync --group dev
uv pip install -e .
az-scout  # plugin is auto-discovered

Structure

az-scout-plugin-latency-stats/
├── .github/
│   ├── copilot-instructions.md  # Copilot context for this plugin
│   └── workflows/
│       ├── ci.yml               # CI pipeline (lint + test, Python 3.11–3.13)
│       └── publish.yml          # Publish to PyPI on version tags
├── pyproject.toml
├── README.md
├── tools/
│   └── vendor_assets.py         # Stdlib-only sync script for vendored assets
└── src/
    └── az_scout_latency_stats/
        ├── __init__.py          # Plugin class + module-level `plugin` instance
        ├── cloud63.py           # Cloud63 data fetch/cache + inter-region matrix API
        ├── inter_zone.py        # Inter-zone benchmark fetch/cache + AZ matrix API
        ├── latency.py           # Static latency dataset + public API
        ├── metadata.py          # Shared source/disclaimer/methodology constants
        ├── routes.py            # FastAPI APIRouter (optional)
        ├── tools.py             # MCP tool functions (optional)
        └── static/
            ├── css/
            │   └── latency.css      # Plugin styles (auto-loaded via css_entry)
            ├── data/
            │   └── region-coordinates.json
            ├── html/
            │   └── latency-tab.html # HTML fragment (fetched by JS at runtime)
            ├── js/
            │   ├── latency-tab.js           # Main tab bootstrap + inter-region UI logic
            │   └── latency-tab-interzone.js # Inter-zone graph/table rendering + sync
            └── vendor/                      # Vendored third-party assets (see below)
                ├── topojson-client/
                └── world-atlas/

Vendored assets

Following the az-scout vendoring recommendation, all third-party frontend assets are committed under static/vendor/ and served same-origin from /plugins/latency-stats/static/vendor/…. The plugin makes no runtime requests to a CDN, so the map renders correctly in offline and air-gapped deployments.

D3.js is provided by the core az-scout app and is intentionally not re-shipped here.

The committed files are the source of truth — there is no npm, bundler, or build step. To refresh them (or after bumping a pinned version in tools/vendor_assets.py):

python3 tools/vendor_assets.py                    # download + verify pinned assets
python3 tools/vendor_assets.py --check            # verify committed files only
python3 tools/vendor_assets.py --update-checksums # re-pin checksums after a version bump

How it works

1. The plugin loads the HTML fragment into #plugin-tab-latency-stats.
2. The user selects a scope:
   • Inter-region: select regions and choose source mode (azuredocs or cloud63).
   • Inter-zone (AZ): uses the main app region selector (#region-select).
3. Inter-region calls POST /plugins/latency-stats/inter-region/matrix and renders world map + matrix table.
4. Inter-zone calls POST /plugins/latency-stats/inter-zone/matrix and renders AZ graph + pair table.
5. Hover interactions are synchronized between graph links and table values in both directions.

API

# Pairwise matrix
curl -X POST http://localhost:8080/plugins/latency-stats/inter-region/matrix \
  -H "Content-Type: application/json" \
  -d '{"regions": ["francecentral", "westeurope", "eastus"], "mode": "azuredocs"}'

# All known pairs
curl http://localhost:8080/plugins/latency-stats/inter-region/pairs

# Cloud63 available regions
curl http://localhost:8080/plugins/latency-stats/inter-region/cloud63-regions

# Inter-zone available regions
curl http://localhost:8080/plugins/latency-stats/inter-zone/regions

# Inter-zone AZ matrix
curl -X POST http://localhost:8080/plugins/latency-stats/inter-zone/matrix \
  -H "Content-Type: application/json" \
  -d '{"region": "westeurope"}'

MCP tool

inter_region_latency(source_region="francecentral", target_region="westeurope")
inter_region_latency(source_region="francecentral", target_region="westeurope", mode="cloud63")
inter_zone_latency(region="westeurope", source_zone="az1", target_zone="az2")

Quality checks

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/
uv run pytest

Copilot support

The .github/copilot-instructions.md file provides context to GitHub Copilot about the plugin structure, conventions, and az-scout plugin API.

Data sources

• Azure Docs (inter-region): Azure Network Latency
• Cloud63 (inter-region optional mode): Azure Latency Test
• Cloud63 benchmark API (inter-zone AZ): https://fa-azure-network-benchmark.azurewebsites.net/api/data

Inter-zone outputs are exposed in microseconds (latencyUsP50). Always validate with in-tenant measurements.

License

MIT

Disclaimer

This tool is not affiliated with Microsoft. All capacity, pricing, and availability information is indicative and not a guarantee of deployment success. Values are dynamic and may change between planning and actual deployment. Always validate in official Microsoft sources and in your target tenant/subscription.