Metadata-Version: 2.4
Name: az-scout-plugin-latency-stats
Version: 2026.3.4
Summary: Inter-region latency statistics plugin for az-scout
Project-URL: Homepage, https://github.com/lrivallain/az-scout-plugin-latency-stats
Project-URL: Repository, https://github.com/lrivallain/az-scout-plugin-latency-stats
Project-URL: Issues, https://github.com/lrivallain/az-scout-plugin-latency-stats/issues
License-File: LICENSE.txt
Requires-Python: >=3.11
Requires-Dist: az-scout
Requires-Dist: fastapi
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# az-scout-plugin-latency-stats

Inter-region and intra-region (Availability Zone) latency plugin for [az-scout](https://github.com/lrivallain/az-scout).

<img width="1088" height="1361" alt="Screnshot of latency plugin" src="https://github.com/user-attachments/assets/53b51880-c2c4-4381-89eb-e5adda78de1a" />

## Features

- **Latency dataset** — static latency matrix based on [Microsoft published statistics](https://learn.microsoft.com/en-us/azure/networking/azure-network-latency)
- **Cloud63 dataset support** — optional inter-region crowd-sourced measurements via `mode="cloud63"`
- **Intra-zone dataset support** — benchmark-based AZ latency matrix from Cloud63 benchmark API
- **API endpoints** — inter-region and intra-region endpoints for matrix and available regions
- **MCP tools** — `region_latency(...)` for inter-region RTT and `intra_region_latency(...)` for intra-region P50 latency in µs
- **UI tab** — interactive D3.js views with inter/intra scope switch, map/table synchronization, and bidirectional hover highlighting
- **URL hash routing** — `#latency-stats` selects the plugin tab

## Setup

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

For development:

```bash
git clone https://github.com/lrivallain/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
└── src/
    └── az_scout_latency_stats/
        ├── __init__.py          # Plugin class + module-level `plugin` instance
    ├── cloud63.py           # Cloud63 data fetch/cache + inter-region matrix API
    ├── intra_zone.py        # Intra-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-intra.js   # Intra-zone graph/table rendering + sync logic
```

## 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`).
   - **Intra-region (AZ)**: uses the main app region selector (`#region-select`).
3. Inter-region calls `POST /plugins/latency-stats/matrix` and renders world map + matrix table.
4. Intra-region calls `POST /plugins/latency-stats/intra-zone/matrix` and renders AZ graph + pair table.
5. Hover interactions are synchronized between graph links and table values in both directions.

### API

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

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

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

# Intra-zone available regions
curl http://localhost:8080/plugins/latency-stats/intra-zone/regions

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

### MCP tool

```
region_latency(source_region="francecentral", target_region="westeurope")
region_latency(source_region="francecentral", target_region="westeurope", mode="cloud63")
intra_region_latency(region="westeurope", source_zone="az1", target_zone="az2")
```

## Quality checks

The scaffold includes GitHub Actions workflows in `.github/workflows/`:

- **`ci.yml`** — Runs lint (ruff + mypy) and tests (pytest) on Python 3.11–3.13, triggered on push/PR to `main`.
- **`publish.yml`** — Builds, creates a GitHub Release, and publishes to PyPI via trusted publishing (OIDC). Triggered on version tags (`v*`). Requires a `pypi` environment configured in your repo settings with OIDC trusted publishing.

Run the same checks locally:

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

To publish a release:

```bash
git tag v2026.2.0
git push origin v2026.2.0
```

## Copilot support

The `.github/copilot-instructions.md` file provides context to GitHub Copilot about
the plugin structure, conventions, and az-scout plugin API. It helps Copilot generate
code that follows the project patterns.

## Data sources

- **Azure Docs** (inter-region): [Azure Network Latency](https://learn.microsoft.com/en-us/azure/networking/azure-network-latency)
- **Cloud63** (inter-region optional mode): [Azure Latency Test](https://latency.azure.cloud63.fr/)
- **Cloud63 benchmark API** (intra-region AZ): `https://fa-azure-network-benchmark.azurewebsites.net/api/data`

Intra-region outputs are exposed in **microseconds** (`latencyUsP50`). Always validate with in-tenant measurements.

## License

[MIT](LICENSE.txt)

## Disclaimer

> **This tool is not affiliated with Microsoft.** All capacity, pricing, and latency information are indicative and not a guarantee of deployment success. Spot placement scores are probabilistic. Quota values and pricing are dynamic and may change between planning and actual deployment. Latency values are sourced from public benchmark/documentation endpoints and must be validated with in-tenant measurements.
