Provider Intelligence

Turn quality signals into safer changes.

NODIF reports only sufficiently large, opted-in provider cohorts. Use the data to form and test operational hypotheses—not to identify, score or target individual users.

UTC windowsDynamic k thresholdNo raw export

Why a dashboard can be empty

An empty value is not automatically an outage. Check these causes in order:

The provider key lacks analytics:read.
The subscription/plan is not actively entitled to Intelligence.
Users have not opted in, or uploads have not arrived after offline use.
The whole window—or an individual bucket/group—does not meet the live minimum_cohort_size returned by the API.
The chosen dimension is unavailable or unknown for that app/network.
Provider catalog attribution is not present in the current client contract.
The query window is outside raw retention or formatted incorrectly.

Overview metric dictionary

Metric	Definition	Interpretation caution
Active installs	Distinct opted-in random NODIF install identities with accepted provider-attributed events in the selected window.	Not subscribers, devices, people or concurrent users.
Sessions	Distinct non-empty NODIF session IDs observed in accepted events.	Reconnects/app behavior can change session counts.
Connection attempts	Count of accepted `connection_result`/`connection_observation` events.	Repeated retries are attempts, not distinct users.
Connection success	Connected outcomes divided by connection attempts/observations.	Compare denominators and client versions before judging a change.
Median latency	50th percentile of positive latency measurements.	Ignores unavailable/zero measurements; cohort/network mix matters.
P95 latency	95th percentile of positive latency measurements.	Useful for tail experience, but unstable in small qualifying groups.
Average jitter	Mean of positive jitter measurements.	A zero can mean no positive sample, not perfect jitter.
Average loss	Mean loss where a latency measurement exists.	Probe method and network conditions affect comparability.
Median download/upload	50th percentile of positive bounded throughput measurements.	Not every session runs a speed test; sampling and user data limits matter.
Reporting coverage	Share of active installs with route probe, quality sample or session-ended data.	Low coverage means speed/quality summaries may not represent all installs.
Known context coverage	Share with known coarse country and city categories.	Unknown is expected when context is unavailable; it is not proof of bad data.
Catalog node coverage	Share with a non-empty NODIF-approved node catalog ID.	Provider self-service catalog registration is not released; low coverage is expected.

Cohort dimensions

Family	Dimensions	Notes
Coarse network context	country, region, city, ASN/network category	Codes/categories, not GPS or retained source IP. “Unknown” can dominate when geolocation context is unavailable.
Client	platform, app version, release channel, OS major, network type	Useful for release regressions and platform-specific failures.
Route	protocol, transport, balancer type, entry type, route shape	Route shape is a fixed direct, provider-balanced, clean-IP/domain-fronted, two-hop, or multi-hop category. It never contains an endpoint value.
Catalog attribution	node ID, entry ID, balancer ID	May be empty or opaque. Full provider-managed catalog/entry/balancer mapping is not released.
Failure	stable error code, failure stage	Typed categories only; no free-form client logs or stack traces.

Every individual row and every time bucket must independently meet the server threshold. The overview qualifying does not force a city or hourly row to appear.

Freshness and time behavior

Times are UTC. API from/to use RFC 3339.
The default window is seven days; the maximum is the active raw-event retention returned by /v1/provider/session.
Queued opted-in events can arrive late when a device reconnects. Recent buckets may change.
Hourly is the default for windows up to 14 days; daily for longer windows.
Raw event retention and aggregate retention are separate policies. The portal should display the live server policy rather than hard-code it.

Safe change-analysis playbook

State one hypothesis. Example: a transport change should improve connection success for Android mobile cohorts without increasing P95 latency.
Choose primary and guardrail metrics. Success may be primary; loss, P95 latency, reconnects and coverage are guardrails.
Capture a baseline. Use the same qualified cohorts, UTC window length and app versions.
Canary the provider change. Keep unrelated routing, pricing and client releases stable where possible.
Wait for reporting delay. Account for offline queues and threshold qualification.
Compare like with like. Avoid interpreting a changed city/platform mix as route improvement.
Rollback on predeclared harm. Do not optimize one median while tail latency, loss or success degrades.
Document only aggregate conclusions. Never attempt to enumerate or contact qualifying installs.

Operational action patterns

Signal	Investigate	Safe action
Success down, handshake stage up	Provider gateway reachability, protocol/transport, certificate/time, ISP blocking, app release.	Canary an alternate eligible provider route; compare guardrails; rollback if worse.
Median stable, P95 latency up	Tail congestion, one network category/city/platform, route switching.	Inspect qualifying cohorts and time buckets; do not assume fleet-wide degradation.
Loss/jitter up on mobile	Network handoff, mobile ISP, packet size/transport behavior.	Test continuity and transport on representative devices; avoid repeated full speed tests.
Throughput down with low coverage	Sampling/measurement coverage first.	Do not declare a speed regression until coverage and cohort mix are adequate.
Error spike after release	App version, platform, OS major and failure stage.	Pause rollout and compare the previous version cohort where both qualify.
Catalog coverage low	Current client contract and NODIF-managed attribution.	Use available category dimensions; do not upload raw host/IP mappings.

Ultimate automated guidance

An active Platform/Ultimate plan can request recommendation-only guidance from GET /v1/provider/guidance. The service evaluates the same tenant-scoped, threshold-protected overview and route/failure categories, then returns prioritized findings and safe canary actions. It does not return raw cohort rows, endpoint values, installation/session identifiers, source IPs, or raw events.

Treat every recommendation as a controlled hypothesis, not an automatic command to rewrite production routing.
Canary the suggested route shape or recovery change and preserve a known-good fallback.
Compare success, P95 latency, loss, and coverage after the cohort has independently qualified again.
Roll back when a guardrail worsens. Never request endpoint or user detail to explain a suppressed result.

Prohibited analytics use

Re-identifying, singling out, fingerprinting or scoring a user/device.
Combining cohorts or repeated queries to infer suppressed groups.
Joining NODIF aggregates to subscription accounts, payment, support or browsing data.
Advertising an individual-user, raw-IP, precise-location or raw-event export.
Selling user-level NODIF data. Monetization is through branding, aggregate tools, APIs, support and service improvement.
Using analytics for employment, credit, insurance, eligibility, surveillance or law-enforcement targeting.

Known current limitations

Older app versions can leave route-shape or transport fields unknown. New versions add categories prospectively; historical events are not reconstructed from subscription data.
Provider-managed catalog registration is not available; node/entry/balancer labels can be unavailable or opaque.
Provider-visible audit history and scheduled report delivery are not released features.
Coarse context depends on approved server configuration and can be unknown; it is not a precise ISP/location database.
Quality tests consume network resources and are deliberately bounded/sampled.