linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: add BGP region and Earth rendering plans

Browse Source
This commit is contained in:
linkong
2026-04-03 12:53:26 +08:00
parent 135ec01223
commit 1a3abf73bb
3 changed files with 720 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/bgp-context.md
View File

@@ -182,6 +182,8 @@ Current reality:
- that is expected, because incidents are aggregated and de-noised
- but incident-first rendering makes the Earth view look too quiet unless there is another always-available activity layer
Implementation detail for the recommended `activity layer` is expanded in [bgp-region-aggregation-plan.md](/home/ray/dev/linkong/planet/docs/bgp-region-aggregation-plan.md).
So the immediate next milestone is:
`event map -> observability map`

296
docs/bgp-earth-rendering-plan.md Normal file
View File

@@ -0,0 +1,296 @@
# BGP Earth Rendering Plan
## Goal
This document defines how the BGP `region activity layer` and `incident layer` should coexist on Earth without conflicting.
The main question it answers is:
- how to add a regional observability background layer
- without weakening the current incident-first event focus
## Core Principle
The Earth design should follow a strict semantic hierarchy:
- `collector layer` = observation infrastructure
- `region activity layer` = background situational awareness
- `incident layer` = focal high-confidence event objects
In short:
- collectors prove the network is observing
- regions show where routing behavior is active or abnormal
- incidents show the concrete event worth clicking
Region aggregation is therefore not a replacement for incident rendering.
It is the context layer that makes sparse incident markers legible.
## Rendering Hierarchy
Recommended visual stack order:
1. collector network / collector halos
2. region activity glow
3. incident markers and incident pulses
This ordering should always hold.
Why:
- collectors should stay visible but quiet
- regions should create ambient activity presence
- incidents must remain the first thing users notice as a concrete event
## Role Separation
### Region Layer
The region layer answers:
- where is routing activity building up
- where is there current noise or instability
- which part of the world is currently worth looking at
The region layer should feel:
- broad
- ambient
- low-frequency
- contextual
### Incident Layer
The incident layer answers:
- which exact event should the user inspect
- where is the highest-confidence routing event located right now
The incident layer should feel:
- sharp
- compact
- high-contrast
- intentionally clickable
## Non-Conflict Rules
To avoid visual and semantic conflict, these implementation rules should be treated as hard constraints:
1. region markers must not use the same symbol language as incidents
2. region emphasis must stay weaker than incident emphasis
3. region animation frequency must stay lower than incident animation frequency
4. incident markers must always render above region glows
5. region layer should support the event, not compete with it
If a user notices the region layer first but misses the incident marker, the region layer is too strong.
If a user only sees isolated incident points and cannot feel broader activity context, the region layer is too weak.
## Region Rendering Rules
The region layer should not be rendered as a second kind of incident point.
Recommended representation:
- diffuse glow
- halo
- low-detail pulse
- soft center, not a sharp icon
### Status Mapping
#### `observing`
- weak glow
- cool color, such as cyan or blue
- little to no pulse
- purpose: keep the globe alive during calm periods
#### `anomaly`
- stronger glow
- warmer color, such as amber
- gentle breathing or low-frequency pulse
- purpose: show that a region is experiencing abnormal routing noise
#### `incident`
- strongest regional background emphasis
- still clearly weaker than the incident marker itself
- purpose: lift the surrounding area so the focal event does not feel isolated
### Region Visual Characteristics
Recommended properties:
- large radius
- low opacity
- soft edge
- low-contrast outline or no outline
- low pulse amplitude
Avoid:
- sharp symbol shapes
- strong icon silhouettes
- bright hard-edged centers
- incident-like pulse language
## Incident Rendering Rules
The incident layer should remain visually sharper and more explicit than region activity.
Recommended qualities:
- clear event symbol
- compact hot core
- one or two outward ring pulses
- high contrast
- clear click target
The incident layer should read as:
- focal
- deliberate
- high-confidence
while the region layer should read as:
- contextual
- ambient
- supporting
## Region And Incident In The Same Area
When a region contains one or more incidents:
- the region glow may intensify
- but the incident marker must remain the dominant local feature
Interpretation should be:
- `region` says this area is in an event state
- `incident marker` says this is the concrete event object
So a region with `incident` status is not itself the event marker.
It is the background state around the event.
## Interaction Model
Interaction should also preserve hierarchy.
### Click Region
Open a regional situation view, such as:
- region name
- observation count
- anomaly count
- incident count
- affected prefix count
- affected ASN count
- recent incidents in the region
### Click Incident
Keep the current incident-focused detail interaction.
This creates a natural two-step flow:
1. region gives context
2. incident gives detail
## Layer Relationship To Existing BGP Elements
### Collector Layer
Collectors should remain:
- quieter than regions
- more infrastructural than semantic
- proof of coverage, not proof of incident
### Region Layer
Regions should become:
- the main ambient activity layer
- the bridge between collectors and incidents
- the answer to low-density map quietness
### Incident Layer
Incidents should remain:
- the most legible event layer
- sparse but dominant
- compact and symbol-driven
## Practical Visual Test
Use this test when tuning the Earth implementation:
### Calm Period
Expected result:
- collectors visible
- some weak region glows present
- no region feels alarm-heavy
- globe still feels alive
### Anomaly Period
Expected result:
- one or more regions brighten noticeably
- user can sense the active area before clicking
- still no confusion between region background and incident objects
### Incident Period
Expected result:
- region provides broader context
- incident marker is the first explicit focal object the eye lands on
- user can immediately tell both:
- which region is active
- which specific event to inspect
## Failure Modes To Avoid
### Region Too Strong
Symptoms:
- incident markers disappear into the glow
- users treat the region center as the main event
- the map feels like area flooding instead of event focus
### Region Too Weak
Symptoms:
- incident markers still feel isolated
- low-incident periods still look visually empty
- users cannot tell where routing activity is generally happening
### Region Uses Incident Language
Symptoms:
- region and incident both look like event markers
- users cannot distinguish context from event
## Final Design Rule
The desired reading order is:
1. see the specific incident marker
2. feel the active region around it
3. understand that collectors and background activity keep the globe alive even during quieter periods
In one sentence:
`incident is the point; region is the field.`

422
docs/bgp-region-aggregation-plan.md Normal file
View File

@@ -0,0 +1,422 @@
# BGP Region Aggregation Plan
## Goal
This document refines the current BGP `activity layer` into an implementation-ready regional aggregation design.
Primary product goal:
- turn sparse prefix-level observations, anomalies, and incidents into a readable `regional observability layer`
- keep Earth visually alive during low-incident periods
- make `incident markers` remain the highest-confidence foreground layer instead of replacing them
This layer is not a new collector, detector, or raw storage table.
It is an aggregation/view-model layer:
`observations -> enrichment -> anomalies/incidents -> geography mapping -> region aggregation -> Earth/UI activity layer`
## Why This Layer Exists
Current product gap from [bgp-context.md](/home/ray/dev/linkong/planet/docs/bgp-context.md):
- incident density is naturally low
- anomaly density is higher, but still not enough to keep the globe expressive all the time
- collector presence alone proves coverage, but does not communicate `where routing is currently active or noisy`
So the missing middle layer is:
- `collectors` show that observation exists
- `regions` show where activity is building up
- `incidents` show the specific high-confidence focus events
## Scope
This plan is specifically for:
- a backend aggregation service
- a summary API for console/stats
- a GeoJSON API for Earth rendering
- an Earth background activity layer that supports, but does not replace, incident markers
This plan does not attempt to solve:
- exact prefix geolocation quality
- polygon-heavy geopolitical visualization
- persistent materialized region tables in v1
## Region Layer Definition
Recommended conceptual model:
- `region layer` = background situational awareness
- `incident layer` = focal event markers
That means:
- region activity should answer `where is routing behavior currently active or abnormal`
- incident markers should answer `which concrete event should the user click`
## Recommended Output Model
Suggested backend output object:
## `BGPRegionActivity`
```json
{
"region_key": "sea",
"region_name": "Southeast Asia",
"center_lat": 1.3521,
"center_lon": 103.8198,
"observation_count": 128,
"anomaly_count": 9,
"incident_count": 2,
"activity_score": 17.6,
"status": "incident",
"affected_prefix_count": 14,
"affected_asn_count": 6,
"collector_count": 5,
"first_seen_at": "2026-04-02T10:00:00Z",
"last_seen_at": "2026-04-02T10:12:00Z"
}
```
### Fields To Keep In MVP
- `region_key`
- `region_name`
- `center_lat`
- `center_lon`
- `observation_count`
- `anomaly_count`
- `incident_count`
- `activity_score`
- `status`
- `affected_prefix_count`
- `affected_asn_count`
- `collector_count`
- `first_seen_at`
- `last_seen_at`
### Fields To Delay
These are useful, but not required for the first implementation:
- `bounding_box`
- `top_incident_types`
- `top_prefixes`
- polygon geometry
## Region Definition Strategy
### Recommendation
Use a static region-definition table first.
Examples:
- `north_america`
- `south_america`
- `western_europe`
- `eastern_europe`
- `east_asia`
- `southeast_asia`
- `south_asia`
- `middle_east`
- `north_africa`
- `sub_saharan_africa`
- `oceania`
Why this is the right v1 choice:
- stable UI semantics
- strong readability on Earth
- easier debugging and explanation
- lower implementation cost than geohash or H3 grids
### Not Recommended For V1
- geohash cell aggregation
- H3 aggregation
- fine-grained lat/lon bucket maps
Those are more flexible, but they make the map feel fragmented and less explainable.
## Geography Mapping Strategy
Do not reduce the implementation to only `prefix -> exact geo`.
The region layer should follow the same geography-priority logic already implied by the current BGP direction:
1. `prefix_geography`
2. `prefix_scope`
3. `ASN organization region`
4. `collector centroid` fallback
This matters because exact prefix geography will often be incomplete or approximate.
The region layer should stay robust even when only partial enrichment is available.
## Backend Design
Recommended new service file:
- [backend/app/services/bgp_regions.py](/home/ray/dev/linkong/planet/backend/app/services/bgp_regions.py)
Suggested responsibilities:
- `map_record_to_region(...)`
- `aggregate_region_activity(...)`
- `build_region_geojson(...)`
- `resolve_activity_status(...)`
- `compute_activity_score(...)`
### Data Source Inputs
Use a recent rolling window, default `15 minutes`, and aggregate from:
- `BGPObservation`
- `BGPAnomaly`
- active `BGPIncident`
### Aggregation Flow
1. query observations in the time window
2. query anomalies in the same window
3. query active incidents in the same window or active status set
4. resolve each record to a best-effort region
5. accumulate per-region counters
6. compute score and status
7. return region activity list
## Status Model
Recommended status buckets:
- `idle`
- `observing`
- `anomaly`
- `incident`
Suggested rule:
```text
if incident_count > 0: incident
elif anomaly_count > 0: anomaly
elif observation_count > 0: observing
else: idle
```
This aligns well with the current Earth status language and keeps the visual mapping simple.
## Activity Score
The score should be a tunable heuristic, not a fixed truth model.
Recommended v1 formula:
```text
activity_score =
min(observation_count, 50) * 0.03
+ anomaly_count * 1.2
+ incident_count * 5.0
```
Why cap observations:
- observation volume is usually much larger than anomaly or incident volume
- uncapped observation counts would overwhelm the score
- capped observation counts preserve baseline presence without drowning real abnormality
### Practical Guidance
- treat coefficients as configuration-like constants
- expect to retune after looking at real data
- keep `incident` weight dominant
## API Design
### 1. Summary/List API
Suggested endpoint:
- `/api/v1/bgp/regions/activity`
Response shape:
```json
{
"window_minutes": 15,
"regions": []
}
```
Use cases:
- BGP console summaries
- right-side Earth stats
- future region list panels
### 2. GeoJSON API
Suggested endpoint:
- `/api/v1/visualization/geo/bgp-regions`
Response shape:
```json
{
"type": "FeatureCollection",
"features": []
}
```
Each feature should include:
- `geometry`
- v1: `Point`
- later: optional `Polygon`
- `properties`
- `region_key`
- `region_name`
- `status`
- `activity_score`
- `observation_count`
- `anomaly_count`
- `incident_count`
- `affected_prefix_count`
- `affected_asn_count`
- `collector_count`
## Earth Rendering Plan
Detailed visual layering guidance is expanded in [bgp-earth-rendering-plan.md](/home/ray/dev/linkong/planet/docs/bgp-earth-rendering-plan.md).
### Layer Relationship
- `region layer` = ambient background activity
- `incident marker` = focal event object
Do not replace incident markers with region markers.
### Region Visual Rules
Suggested mapping:
- `observing`
- weak glow
- low pulse or no pulse
- `anomaly`
- stronger glow
- more visible pulse
- `incident`
- strongest regional emphasis
- but still visually secondary to the incident marker itself
### Region Labels
Good v2 enhancement:
- show region name
- show counts like `2 incidents / 5 anomalies`
This is useful, but should come after the core aggregation and Earth glow layer are working.
## Interaction Model
### Click Region
Recommended detail payload:
- region name
- observation/anomaly/incident counts in the selected window
- affected prefix count
- affected ASN count
- collector count
- recent incidents in the region
### Click Incident
Keep the current incident-detail flow.
Interaction should feel hierarchical:
1. region gives situational context
2. incident gives event focus
## MVP Implementation Order
### Step 1
Define static `REGIONS` in code or config.
### Step 2
Map geography-enriched BGP records into regions using the fallback chain.
### Step 3
Aggregate recent window counts:
- `observation_count`
- `anomaly_count`
- `incident_count`
### Step 4
Compute `activity_score` and `status`.
### Step 5
Expose:
- `/api/v1/bgp/regions/activity`
- `/api/v1/visualization/geo/bgp-regions`
### Step 6
Render region glows on Earth behind incident markers.
## Out Of Scope For MVP
- persistent materialized region tables
- geohash or H3 support
- polygon-filled regional overlays
- detailed top-prefix ranking in the first release
- complicated scoring personalization
## Risks And Constraints
### Geography Quality
Prefix geography is approximate and incomplete.
The region layer must tolerate fallback-based placement.
### Query Cost
Dynamic aggregation is the right v1 choice, but repeated short-window queries may eventually need:
- in-process caching
- scheduled pre-aggregation
- materialized summaries
### UI Overcrowding
If region glow, collector activity, and incidents all become too strong at once, Earth readability will regress.
The region layer must remain supportive, not dominant.
## Final Recommendation
The current BGP roadmap should explicitly add:
- `region aggregation` as the concrete implementation of the missing `activity layer`
The recommended product interpretation is:
- `collectors` prove observation coverage
- `regions` communicate live routing activity and abnormality
- `incidents` remain the clearest high-confidence event objects
In one sentence:
`region aggregation is not a replacement for incidents; it is the situational background that makes sparse incidents feel legible on Earth.`