Implement opt-in analytics (#24440)

* Add analytics opt-in setting, prompt notice kind, and notice watermarks

* Add the analytics report schema

* Add the analytics state file

* Add the install and hardware analytics collectors

* Add the detection analytics collector

* Add the cameras analytics collector

* Add the features analytics collector

* Add the health analytics collector

* Build analytics reports from the section collectors

* Add the analytics report transport

* Send the daily analytics report from the main process

* Add the analytics preview API

* Generate the analytics schema and check it in CI

* Record the image variant in each Dockerfile

* Show the analytics preview in telemetry settings

* Document anonymous analytics

* change wording

* fixes

* update network requirements docs

* adapt analytics to free-form model scenes, split notice counts, and peewee 4

* fixes

* change log levels

* docstrings

* docstrings

* honor file-only analytics opt-outs and skip pre-consent notices

An opt-out saved through the YAML editor's "Save only" or a hand edit never reached the live config, so reports kept going out under the old install ID until a restart. The reporter now reads telemetry.analytics from the config file when a report is due, validated with TelemetryConfig so yes, on, and 1 still count as consent, and an opt-out there deletes the state file and skips the send. The first report under a new install ID also carried every notice since the counters started, including ones from before the opt-in, so a fresh state file now resets the notice watermarks before the report's snapshot.

* take the notice baseline at opt-in instead of the first send

The watermark reset ran at the first send attempt, so notices raised between the opt-in and that send, up to 45 minutes after a startup, were absorbed into the reset and never reported. The reporter now writes the new install ID and resets the watermarks as soon as it sees consent without a state file.

* report notice counts cumulatively from a database baseline

Moving watermarks after each accepted send kept the install ID and the notice baseline out of step: pre-consent notices went out, notices raised before the first send were dropped, and a send that finished after an off/on toggle overwrote the new identity's baseline. health.notices now carries cumulative counts since the install ID was created. Creating an ID copies the lifetime counts into the existing reported_* columns before the state file names it, and nothing is written after a send, so the backend diffs consecutive reports per install ID.

* write held notice repeats before the analytics baseline reset

Repeats of batched kinds like failed_login wait in memory until the stats emitter flushes them, so a baseline reset taken while some were held left them out, and the next flush counted those pre-opt-in repeats as post-consent. The reset now writes held repeats to the notice history under the same lock before copying the counts.

* seed detector inference speed from the first inference

The average started at 0 so idle detectors read 0, but that made every detector's speed climb from 0 for its first couple dozen inferences after a start. Detectors now use the same InferenceSpeed helper as enrichments, so the first inference seeds the average and idle detectors still read 0.

web/e2e/specs/settings/telemetry-analytics.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * Telemetry settings: the analytics preview shows the report Frigate would
+ * send, fetched only when opened.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test, expect } from "../../fixtures/frigate-test";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_SCHEMA = JSON.parse(
+  readFileSync(
+    resolve(__dirname, "../../fixtures/mock-data/config-schema.json"),
+    "utf-8",
+  ),
+);
+
+const PREVIEW = {
+  schema_version: 1,
+  install_id: "0".repeat(32),
+  install: { version: "0.19.0-test" },
+};
+
+test.describe("telemetry settings: analytics preview @medium", () => {
+  test("shows the report on demand", async ({ frigateApp }) => {
+    let requests = 0;
+    const page = frigateApp.page;
+
+    await page.route("**/api/config/schema.json", (route) =>
+      route.fulfill({ json: CONFIG_SCHEMA }),
+    );
+    await page.route("**/api/config/raw_paths", (route) =>
+      route.fulfill({ json: { telemetry: {} } }),
+    );
+    await page.route("**/api/analytics/preview", (route) => {
+      requests += 1;
+      return route.fulfill({ json: PREVIEW });
+    });
+
+    await frigateApp.goto("/settings?page=systemTelemetry");
+
+    const button = page.getByRole("button", { name: "Preview the report" });
+    await expect(button).toBeVisible();
+    expect(requests).toBe(0);
+
+    await button.click();
+
+    await expect(page.getByTestId("analytics-preview")).toContainText(
+      '"schema_version": 1',
+    );
+    expect(requests).toBe(1);
+  });
+});

web/public/locales/en/config/global.json

@@ -226,6 +226,10 @@
   "telemetry": {
     "label": "Telemetry",
     "description": "System telemetry and stats options including GPU and network bandwidth monitoring.",
+    "analytics": {
+      "label": "Share anonymous analytics",
+      "description": "Send one anonymous usage report a day to help the Frigate maintainers decide what to support. Nothing is sent until this is on."
+    },
     "network_interfaces": {
       "label": "Network interfaces",
       "description": "List of network interface name prefixes to monitor for bandwidth statistics."

web/public/locales/en/views/settings.json

@@ -1,4 +1,9 @@
 {
+  "analyticsPreview": {
+    "show": "Preview the report",
+    "desc": "Frigate sends this report once a day while sharing is on. It never includes camera names, zones, labels, or addresses.",
+    "error": "Unable to build the preview"
+  },
   "documentTitle": {
     "default": "Settings - Frigate",
     "authentication": "Authentication Settings - Frigate",

web/public/locales/en/views/system.json

@@ -56,7 +56,8 @@
         "object_processing_behind": "Tracked object processing could not keep up, so camera frames were dropped. Check CPU utilization, and whether CPU limits or pinning on the container or VM are leaving Frigate too little CPU",
         "failed_login_one": "Failed login attempt for {{user}}",
         "failed_login_other": "Failed login attempts for {{user}}",
-        "update_available": "Frigate {{version}} is available"
+        "update_available": "Frigate {{version}} is available",
+        "analytics_prompt": "Consider sharing anonymous usage statistics to help the developers improve Frigate"
       },
       "streamPrefix": "Stream {{index}}: {{message}}",
       "streamPrefixRestream": "Stream {{index}} (via go2rtc): {{message}}",

web/src/components/config-form/section-configs/telemetry.ts

@@ -3,9 +3,17 @@ import type { SectionConfigOverrides } from "./types";
 const telemetry: SectionConfigOverrides = {
   base: {
     sectionDocs: "/configuration/advanced/reference",
+    fieldDocs: {
+      analytics: "/configuration/advanced/analytics",
+    },
     restartRequired: ["version_check"],
-    fieldOrder: ["network_interfaces", "stats", "version_check"],
+    fieldOrder: ["analytics", "network_interfaces", "stats", "version_check"],
     advancedFields: [],
+    uiSchema: {
+      analytics: {
+        "ui:after": { render: "AnalyticsPreview" },
+      },
+    },
   },
 };
 

web/src/components/config-form/sectionExtras/AnalyticsPreview.tsx

@@ -0,0 +1,56 @@
+import { useState } from "react";
+import useSWR from "swr";
+import { useTranslation } from "react-i18next";
+import { LuChevronDown, LuChevronRight } from "react-icons/lu";
+import ActivityIndicator from "@/components/indicators/activity-indicator";
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+
+export default function AnalyticsPreview() {
+  const { t } = useTranslation("views/settings");
+  const [open, setOpen] = useState(false);
+
+  // built on demand, since building runs every collector on the server
+  const { data, error } = useSWR<Record<string, unknown>>(
+    open ? "analytics/preview" : null,
+    { revalidateOnFocus: false },
+  );
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="mt-2">
+      <CollapsibleTrigger asChild>
+        <Button variant="outline" size="sm" className="gap-1">
+          {open ? (
+            <LuChevronDown className="size-4" />
+          ) : (
+            <LuChevronRight className="size-4" />
+          )}
+          {t("analyticsPreview.show")}
+        </Button>
+      </CollapsibleTrigger>
+      <div className="mt-1 text-xs text-muted-foreground">
+        {t("analyticsPreview.desc")}
+      </div>
+      <CollapsibleContent className="mt-2">
+        {error ? (
+          <div className="text-sm text-danger">
+            {t("analyticsPreview.error")}
+          </div>
+        ) : data ? (
+          <pre
+            data-testid="analytics-preview"
+            className="max-h-96 overflow-auto rounded-md bg-secondary p-3 text-xs"
+          >
+            {JSON.stringify(data, null, 2)}
+          </pre>
+        ) : (
+          <ActivityIndicator className="size-5" />
+        )}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}

web/src/components/config-form/sectionExtras/registry.ts

@@ -1,4 +1,5 @@
 import type { ComponentType } from "react";
+import AnalyticsPreview from "./AnalyticsPreview";
 import SemanticSearchReindex from "./SemanticSearchReindex.tsx";
 import CameraReviewStatusToggles from "./CameraReviewStatusToggles";
 import ProxyRoleMap from "./ProxyRoleMap";
@@ -56,6 +57,9 @@ export const sectionRenderers: SectionRenderers = {
   birdseye: {
     BirdseyeCameraReorder,
   },
+  telemetry: {
+    AnalyticsPreview,
+  },
 };
 
 export default sectionRenderers;

web/src/types/frigateConfig.ts

@@ -662,6 +662,7 @@ export interface FrigateConfig {
   };
 
   telemetry: {
+    analytics: boolean;
     network_interfaces: string[];
     stats: {
       amd_gpu_stats: boolean;