Signal methodology and API

This page describes the measurements shown by BGP Prefix Monitor. Stored timestamps are UTC. A missing measurement is not automatically classified as an outage.

Signals

Raw local signal API

/api/signals/raw downloads the locally stored BGP1, BGP2, Active /48s, and Active /24s measurements for one ASN. Download routes require the static key configured as DOWNLOAD_API_KEY, supplied in X-API-Key or as a Bearer token. Times accept Unix seconds, Unix milliseconds, ISO 8601, or a normal UTC date such as 2026-07-28 12:00. The maximum range is 31 days.

curl -H "X-API-Key: $DOWNLOAD_API_KEY" \
  "https://HOST/api/signals/raw?asn=9198&from=2026-07-21T00:00:00Z&until=2026-07-28T00:00:00Z"

curl -H "Authorization: Bearer $DOWNLOAD_API_KEY" \
  "https://HOST/api/signals/raw?asn=9198&timestamp=2026-07-27T12:00:00Z&format=csv"

A singular timestamp requests the following two-hour window so lower-cadence BGP2 measurements can be included. JSON is the default. Set format=csv for a downloadable CSV.

Signal display decisions

Chart representation: Absolute shows stored counts. % Baseline divides by the fixed entity baseline and caps the display at 100%. % wk MA divides by that signal's trailing seven-day mean and caps at 100%; it changes display scale only.

Adaptive BGP1 resolution: chart windows of seven days or less return native ten-minute samples. Longer windows are grouped into two-hour UTC buckets and return the mean routed-prefix count in each bucket. Changing the slider or date fields refetches BGP1 at the appropriate resolution; it does not merely stretch the original week.

BGP1 diagnostics: 10-minute high and high+low counts; hourly literal prefix count; hourly address-weighted peer and collector BGPVis.

Outage display: charts and lists read persisted worker events. They do not recompute outage windows in the browser.

Measurement recovery: after a BGP1 collection gap, values remain unknown until collector-wide and per-AS totals reach 95% of their pre-gap level, remain there for four hours, and reach the next full UTC hour.

Collector health: the hourly dump provides global peer visibility and collector membership per prefix. The health view plots active collectors, effective IPv4/IPv6 peer ceilings, and each collector's prefix/address-space coverage. It cannot derive peers per individual collector because peer identities are not stored in the dump.

Authoritative ASN outage decisions

The worker is the only authoritative detector. BGP1, BGP2, Active /24s, and Active /48s have separate baselines and state keys. An outage in any primary signal marks the ASN.

1. Routed day: asn_days_routed_route records a day with at least one robust BGP1 unit.
2. Admission: eligible on at least 15 of the preceding 30 complete days; stored in outage_as_eligibility_route.
3. Baseline: the baseline is the mean of that family's positive daily average prefix counts across those routed days. Sigma is calculated across the same daily averages.
4. Collector gate: IPv4 and IPv6 decisions advance only when their current effective-peer count is at least 70% of the preceding 24-hour median and at least six preceding collector samples exist. ASN-count changes are recorded for diagnostics but are not used to reject an interval.
5. Missing ASN: after the collector gate passes, an eligible ASN absent from the current BGP1 snapshot has observed value zero. Consecutive healthy missing intervals continue to be zero.
6. Opening: an outage opens when the observation is at least 30% below baseline and the fall is at least 3σ. Effective sigma is the largest of measured sigma, 5% of baseline, or one prefix.
7. Persistence: eligibility, baseline, and outage start are persisted in outage_as_state. An open outage is not removed when the rolling 30-day routed-day count later falls below 15, so outages can last longer than a week or month.
8. Recovery: an outage closes when a collector-healthy observation no longer satisfies both the 30% and 3σ conditions. Collector-bad or missing measurement intervals neither recover nor extend the state.
9. History: per-signal openings and recoveries are persisted in outage_as_signal_events. The ASN rail queries event overlap with the selected range.
10. Aggregation: an ASN is in outage if either eligible family is in outage. An organization is in outage if any member ASN is in outage. Country percentages use eligible/open ASNs or organizations as the denominator. “Recent” means currently open or recovered within the preceding 24 hours.

Country signal heatmap decisions

The worker stores continuous country values in outage_signal_scores and two-hour cells in outage_country_heatmap. Each primary signal is evaluated independently. Missing source intervals are grey, not outages.

The selectable profiles combine a minimum fall from the preceding baseline, a minimum z-score, and minimum history coverage:

Countries are ranked by accumulated outage share for the selected source, family, and profile. The country browser requests the persisted outage order before pagination, so current outages appear before recent outages and unaffected entities. Its right rail can switch between ASes and organizations. Opening an organization replaces the country rail with all member ASes while retaining one focused scientific chart. The Organization link in the focused ASN metadata opens the same member view.

GET /api/outage_heatmap?source=bgp1&family=ipv4&profile=default&days=30

Routed prefixes by country

/api/prefixes/routed returns the latest routed prefixes for all ASNs matching a country and the optional entity filters. It requires the same download API key. IPv4 and IPv6 prefixes are included by default. The older /api/routed_prefix_export path remains available for compatibility.

GET /api/prefixes/routed?country=AT&format=json
GET /api/prefixes/routed?country=DE&source=bgpmap&format=csv
GET /api/prefixes/routed?country=NL&source=routeviews&ipv6_prefixes=0&format=csv
GET /api/prefixes/routed?country=US&rows=org&format=parquet
GET /api/prefixes/routed?country=CH&fields=prefix,asn,as_name,org_name,country,snapshot_ts

The BGPMap source reads routing_table_dump_latest.parquet; RouteViews reads routeviews-latest.dat or the newest configured RIB. These files are mounted read-only and refreshed independently of the API container.

Deployment endpoints

The dashboard container serves these APIs on port 8080. An optional API-only Docker service exposes the same documented endpoints on host loopback port 8081 without starting outage or notification background loops. A reverse proxy can publish that port under a separate API hostname or path.

IODA source API

The dashboard proxies the official IODA v2 raw-signal and outage-event endpoints only after the user presses “Load IODA”. IODA remains the source and copyright holder for those records.

← Return to BGP Prefix Monitor