Provider API reference¶
The provider base module is the stable import surface for integrations. It re-exports capability constants, time windows, result dataclasses, and snapshot types so provider packages do not need to depend on internal module locations.
Provider contract¶
Base class every analytics data source implements.
Subclasses should raise :class:ProviderError for anything the user needs to know about; other exceptions are treated as bugs.
Startup warnings for a configured-but-under-scoped provider.
Returns a list of :class:django.core.checks.Warning, surfaced at server startup, for a provider that works yet reports an ambiguous scope — e.g. a whole Cloudflare zone, or a guessed Sentry project. Only consulted for providers that are :attr:is_configured.
Whether the requested range is longer than this source can serve.
route is a :class:django_prometric.routes.RouteInfo.
Routes ordered by p95 response time, slowest first.
Firewall mitigations: total plus actions/sources/countries/paths breakdowns (lists of :class:BreakdownItem).
Human vs automated traffic: total requests, humans, bots, and a categories breakdown of the automated share.
Search-engine crawler activity: total crawler requests, engines breakdown, and the most crawled paths.
Protocol mix: http_versions and tls breakdowns (lists of :class:BreakdownItem).
Real users' clients — bots excluded where the source can tell: browsers, os and devices breakdowns.
Database queries ordered by total time spent, worst first.
Database-level health: size, connections and lifetime counters.
Unused and most-used indexes: {"unused": [...], "used": [...]}.
Where application time goes: an ops breakdown of total time (values in ms) across database, templates, upstream calls, …
Context for this provider's section on the route-detail page.
The default ships the full :class:RouteMetrics; providers with a different shape of per-route data override this together with route_template.
Drop any cached upstream responses (used by the refresh button).
User-presentable errors¶
Bases: Exception
A user-presentable analytics failure.
kind lets the UI react appropriately: config – provider is not (fully) configured auth – credentials rejected network – upstream unreachable quota – plan/time-range limit hit plan – feature not included in the current plan error – anything else
Time windows¶
dataclass ¶
classmethod ¶
Build from GET/POST params: a preset period key, or a free from/to date range (period=custom).
Core result types¶
dataclass ¶
OverviewStats(requests=0, unique_visitors=None, page_views=None, bandwidth_bytes=None, cached_requests=None, threats=None, errors=None, avg_response_ms=None)
dataclass ¶
dataclass ¶
PerformanceStats(p50_ms=None, p75_ms=None, p95_ms=None, p99_ms=None, avg_ms=None, failure_rate=None, requests=None)
dataclass ¶
RoutePerformance(transaction, requests=0, p50_ms=None, p75_ms=None, p95_ms=None, p99_ms=None, failure_rate=None)
Response-time percentiles of one route/transaction, app-side.
dataclass ¶
RouteMetrics(requests=0, visits=None, bandwidth_bytes=None, errors=None, last_seen=None, countries=list(), statuses=list(), methods=list(), cache=list(), timeseries=list(), performance=None)
Application and database result types¶
dataclass ¶
One database query aggregated across its calls, slowest first.
dataclass ¶
One grouped application error.
dataclass ¶
DatabaseStats(size_bytes=0, table_count=0, index_count=0, row_estimate=0, dead_estimate=0, connections=dict(), max_connections=None, commits=None, rollbacks=None, cache_hit_ratio=None, deadlocks=None, temp_bytes=None)
Database-level health, mixing point-in-time state and lifetime counters.
Point-in-time fields are correct at read time. The counter fields are wrapped in :class:Cumulative by the provider so the UI can flag them as accumulated since the last statistics reset.
dataclass ¶
One user table's size, row estimates and scan activity.
dataclass ¶
One index's size and use. scans == 0 means it was never used.
dataclass ¶
A counter accumulated since since, not scoped to the query window.
Providers wrap a value in this to tell the UI the number is a lifetime counter (last reset at since), not a per-period figure — so the UI can mark it with a "since …" badge (see components/_cumulative.html) rather than pretend it matches the selected period. When a provider later windows the counter (see :class:CounterSampler, Phase 2), it returns a plain number instead and the badge disappears with no template change.
dataclass ¶
One actionable finding a provider derived from its data.
title states what was found, detail backs it with numbers, and action says what to do about it. Good findings confirm health and carry no action.
dataclass ¶
A side note a provider left while answering — e.g. a clamped window.
warn notices flag that the data shown differs from what was asked for; info ones are purely informative.