128 lines
6.6 KiB
Markdown
128 lines
6.6 KiB
Markdown
# Earth Location Candidate Collection User Guide
|
|
|
|
Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, and online geocoding results into a previewable candidate list.
|
|
|
|
## Supported Entities
|
|
|
|
Currently supported:
|
|
|
|
- Compute centers: TOP500 supercomputers and Epoch AI GPU clusters.
|
|
- BGP collectors: RIPE RIS `rrcXX` collectors.
|
|
|
|
BGP events inherit the location of their owning collector. Events do not have a separate collection button yet; future ASN facility, prefix geography, or PeeringDB resolvers should use the same pipeline.
|
|
|
|
## What Users See
|
|
|
|
Clicking a compute center or BGP collector on Earth opens a detail card with location fields:
|
|
|
|
| Field | Meaning |
|
|
| --- | --- |
|
|
| Location precision | Precise coordinates, site-level, city-level, or unconfirmed |
|
|
| Location source | Source coordinates, ROR organization registry, Nominatim online search, or stored BGP collector locations |
|
|
| Location confidence | Relative confidence reported by the backend resolver |
|
|
| Verification status | Confirmed, estimated, or online result pending confirmation |
|
|
| Resolution reason | Why the location was selected |
|
|
| Matched location name | Canonical name from an open source, online result, or stored collector location |
|
|
| Verified at | Verification date for confirmed locations; online candidates are usually empty |
|
|
|
|
Compute-center GeoJSON no longer renders country centroids, unknown locations, or `[0, 0]` placeholders. Records that cannot reach city-level precision are returned in the endpoint's `unresolved` list and can be improved through candidate collection.
|
|
|
|
A compute center with a `?` marker on Earth is not unresolved. It already has coordinates, but the coordinates still need confirmation, either because `needs_confirmation=true` or because the source is online geocoding. Truly unresolved records have no trustworthy coordinates and are therefore absent from the globe.
|
|
|
|
## Collect Candidates
|
|
|
|
1. Open `http://localhost:3000/earth`.
|
|
2. Enable the `Compute centers` or `BGP observation` layer.
|
|
3. Click an object to open its detail card.
|
|
4. Click `自动采集坐标候选` or `重新自动采集坐标`.
|
|
5. Wait for up to five candidates to appear.
|
|
6. Click `预览` on a candidate row; Earth flies to that latitude and longitude.
|
|
|
|
Candidate rows show:
|
|
|
|
- Candidate name.
|
|
- Precision: precise, site, or city.
|
|
- Resolver source.
|
|
- Confidence.
|
|
- Coordinates.
|
|
|
|
Clicking `保存` on a candidate row writes the selected compute-center candidate into the location dimension table. After the save succeeds, the compute-center layer refreshes; if the record was previously in the unresolved queue, the unresolved count decreases.
|
|
|
|
## Unresolved Queue And Adopt All
|
|
|
|
The notification badge on the compute-center layer row shows the current unresolved count. Clicking it opens a fixed queue beside the layer panel:
|
|
|
|
1. The queue contains only compute centers without trustworthy coordinates.
|
|
2. Row-level `采集` calls the candidate endpoint and shows up to five previewable candidates.
|
|
3. Header-level `一键采用` walks the list from top to bottom, chooses the highest-confidence candidate with valid coordinates, and saves it.
|
|
4. Each successful save immediately removes that row, renumbers the remaining rows, and updates the badge count.
|
|
5. When the batch completes, the frontend refreshes the compute-center layer so UI state and backend state converge.
|
|
|
|
If a record has no saveable candidate, the system does not invent a country centroid, vendor headquarters, or hard-coded hint. The row stays in the queue with the backend failure reason and attempted queries so an operator can supply better evidence later.
|
|
|
|
## Backend APIs
|
|
|
|
The frontend buttons call:
|
|
|
|
```http
|
|
POST /api/v1/visualization/compute-centers/{source_id}/collect-location
|
|
POST /api/v1/visualization/compute-centers/{source_id}/location
|
|
POST /api/v1/bgp/collectors/{collector_id}/collect-location
|
|
```
|
|
|
|
Both `collect-location` endpoints use the same response shape:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"candidates": [],
|
|
"best_candidate": {},
|
|
"attempted_queries": [],
|
|
"context": {}
|
|
}
|
|
```
|
|
|
|
When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason` plus the attempted queries. This helps distinguish missing source fields, open-source gaps, and online geocoding misses.
|
|
|
|
## Registry Maintenance
|
|
|
|
Compute centers and BGP collectors no longer maintain local candidate registries. Compute-center accepted locations are stored in the `compute_center_locations` database dimension table keyed by `(source, source_id)`. BGP collector current locations are stored in the `bgp_collector_locations` database dimension table; the old RIPE RIS city-level coordinates are used only as initialization seed data and still require confirmation.
|
|
|
|
For compute centers, prefer maintaining:
|
|
|
|
- `source` / `source_id`: for example `top500` + `top500_50`.
|
|
- `name` / `operator` / `site`.
|
|
- `city` / `country`.
|
|
- `latitude` / `longitude`.
|
|
- `precision`: `precise`, `site`, or `city`.
|
|
- `confidence`: confidence from 0 to 1.
|
|
- `location_source` / `source_url` / `source_note` / `raw_payload`: evidence source.
|
|
- `needs_confirmation` / `verification_status` / `verified_at`: manual verification status and date.
|
|
|
|
For BGP collectors, prefer maintaining:
|
|
|
|
- `collector_id`: for example `rrc12`.
|
|
- `site` / `operator`: site and operator.
|
|
- `city` / `country` / `region`.
|
|
- `latitude` / `longitude`.
|
|
- `precision`: `precise`, `site`, or `city`.
|
|
- `confidence`: confidence from 0 to 1.
|
|
- `source` / `source_url` / `raw_payload`: evidence source.
|
|
- `verification_status` / `verified_at`: manual verification status and date.
|
|
|
|
If only the city is known, use city-level precision. Do not enter a precise-looking coordinate that has not been verified.
|
|
|
|
## Common Questions
|
|
|
|
### Why are some compute centers missing on Earth?
|
|
|
|
Earth only renders coordinates that reach city-level precision or better. If source data, verified storage, and online geocoding all fail, the record is returned as `unresolved` instead of being rendered at a misleading country center or `[0, 0]`.
|
|
|
|
### Why do online results need confirmation?
|
|
|
|
Nominatim/OpenStreetMap results may match same-name cities, organizations, or campuses. They are useful for previewing candidates, but should be manually confirmed before being persisted as verified locations.
|
|
|
|
### Why do BGP events no longer all land in Amsterdam?
|
|
|
|
The old behavior could match common fields like `operator="RIPE NCC"` and incorrectly promote `rrc00`. BGP event inheritance now uses a strict owning-collector lookup in the DB-backed cache instead of registry fuzzy matching.
|