Struct AnalyticsPlugin 

pub struct AnalyticsPlugin { /* private fields */ }

The analytics plugin. Carries no models, no persistent routes — just an AnalyticsClient it installs as the ambient handle at boot so capture / identify work anywhere in the process.

Registration

App::builder()
    .plugin(AnalyticsPlugin::new("phc_your_api_key"))
    .build()
    .await?;

Opt-in per-request pageview capture

AnalyticsPlugin::new("phc_your_api_key")
    .capture_requests()   // fires a $pageview event on every request

No-op when unconfigured

When the API key is absent (neither builder arg nor env var), the plugin registers but the ambient client is not installed. Both capture and identify are silent no-ops. A one-time warn! fires at boot so the operator can diagnose misconfiguration without a runtime panic.

Implementations

impl AnalyticsPlugin

pub fn new(api_key: impl Into<String>) -> Self

Build the plugin with an explicit PostHog project API key.

The key wins over UMBRAL_POSTHOG_API_KEY / posthog_api_key in settings. Use this for apps that keep secrets in code (not recommended for production; prefer the env var and call AnalyticsPlugin::from_env).

pub fn from_env() -> Self

Build the plugin reading configuration exclusively from environment variables / umbral.toml settings. Equivalent to AnalyticsPlugin::default() with no builder overrides.

pub fn host(self, host: impl Into<String>) -> Self

Override the PostHog ingest host. Default: https://us.i.posthog.com. Override for EU region (https://eu.i.posthog.com) or a self-hosted instance.

pub fn capture_requests(self) -> Self

Opt in to automatic per-request $pageview capture. Mounts a from_fn middleware that fires one event per request (with path, method, and status code in properties) without any handler changes. Default OFF.

pub fn exclude_path_prefix(self, prefix: impl Into<String>) -> Self

Exclude a request-path prefix from auto $pageview capture so its path never ships to the analytics host (audit_2 plugin-observability #4). Add every route whose path can carry a secret or PII — password-reset and email-verification links, per-user resource paths, signed URLs, etc. Call more than once to exclude several prefixes.

Trait Implementations

impl Default for AnalyticsPlugin

fn default() -> Self

Returns the “default value” for a type.

impl Plugin for AnalyticsPlugin

fn name(&self) -> &'static str

A stable identifier. Used as the key in the migration tracking table, in dependency lists, and as the directory name under migrations/. Plugin names live in the same namespace as migrate::APP_PLUGIN_NAME ("app"), so user crates must not pick the name "app".

fn on_ready(&self, _ctx: &AppContext) -> Result<(), PluginError>

Wire signals, start background work, seal admin registrations. Called after phase 4 (system checks) passes, in topological dependency order. Sync, on purpose; spawn async work via ctx.runtime() when the runtime handle lands.

fn wrap_router(&self, router: Router) -> Router

Wrap the app router with the plugin’s middleware layers.

fn dependencies(&self) -> &'static [&'static str]

Names of plugins that must load before this one. The App::builder() topological sort uses this; cycles surface as BuildError::PluginCycle. The default is no dependencies.

fn models(&self) -> Vec<ModelMeta>

The plugin’s models, in declaration order. The M7 migration engine collects these across every registered plugin and uses them as the diff target for makemigrations.

fn routes(&self) -> Router

The plugin’s HTTP routes. Merged into the app router after the hand-written one passed to AppBuilder::routes(). Plugins choose their own path prefixes (spec 02 §“What a plugin can contribute”: routes are flat, not auto-prefixed).

fn routes_builder(&self) -> Option<Routes>

The drift-free alternative to routes + route_paths (gaps4 #31): mount routes through the recording Routes builder and the framework takes BOTH the axum router and the declared RouteSpecs from that ONE source, so the route registry can never fall out of sync with what’s mounted.

fn route_paths(&self) -> Vec<RouteSpec>

Declared URL routes this plugin contributes — a companion to routes used for surfacing route lists outside the request flow (currently: the dev-mode default 404 page). axum doesn’t expose its internal route table, so plugins report what they declare here; the framework treats this as informational only — not a source of truth for routing.

fn openapi_paths(&self) -> Vec<(String, Value)>

OpenAPI path items the plugin contributes. Returned as a Vec<(path, value)> where path is the URL template (/api/auth/login, /api/foo/{id}) and value is the matching OpenAPI 3.0 Path Item Object serialised as a serde_json::Value.

fn system_checks(&self) -> Vec<SystemCheck>

Boot-time checks the plugin needs to pass. Run in phase 4 of App::build() alongside the framework’s built-in checks. Severity::Error blocks boot; Severity::Warning logs and continues.

fn provides_storage(&self) -> bool

true if this plugin registers a Storage backend (e.g. StoragePlugin, which calls crate::storage::set_storage in Plugin::on_ready).

fn database(&self) -> Option<&'static str>

The database alias every model this plugin contributes should be read from and written to. Returns None to use the "default" pool (the same one umbral::db::pool() returns).

fn templates_dirs(&self) -> Vec<PathBuf>

Template directories this plugin contributes.

fn template_registrars( &self, ) -> Vec<Box<dyn Fn(&mut Environment<'static>) + Send + Sync>>

Custom template tags / filters this plugin contributes (feature #67 - a loadable template tag/filter library).

fn middleware(&self) -> Vec<Arc<dyn Middleware>>

Framework-level request/response middleware this plugin contributes (feature #68).

fn static_files(&self) -> Vec<StaticFile>

Static files the plugin ships baked into its binary.

fn static_dirs(&self) -> Vec<StaticDir>

On-disk source directories this plugin contributes to the unified static pipeline.

fn static_root_dirs(&self) -> Vec<PathBuf>

On-disk directories served at the root of static_url — with no namespace segment.

fn commands(&self) -> Vec<Box<dyn PluginCommand>>

CLI subcommands the plugin contributes.

fn api_endpoints(&self) -> Vec<ApiEndpoint>

Callable HTTP endpoints this plugin wants advertised in a machine-readable index (e.g. a REST API root, or a client’s service-discovery fetch).