Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Health inspector (#74681)

technomancy943ce3d2b254
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index a17af62208f..70b3da4b207 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -1013,6 +1013,17 @@
:api #{metabase.graph.core}
:uses #{util}}
+ health-inspector
+ {:team "Querying Platform"
+ :api #{metabase.health-inspector.api
+ metabase.health-inspector.init}
+ :uses #{api
+ lib
+ lib-be
+ settings
+ task
+ util}}
+
indexed-entities
{:team "UX West"
:api #{metabase.indexed-entities.api
diff --git a/resources/migrations/063/20260521_health_inspector_runs.yaml b/resources/migrations/063/20260521_health_inspector_runs.yaml
new file mode 100644
index 00000000000..91d3c60548c
--- /dev/null
+++ b/resources/migrations/063/20260521_health_inspector_runs.yaml
@@ -0,0 +1,42 @@
+## Create a table for health inspector runs
+
+databaseChangeLog:
+ - changeSet:
+ id: v63.2026-05-21T10:47:00
+ author: technomancy
+ comment: Create health_inspector_runs table.
+ changes:
+ - createTable:
+ tableName: health_inspector_runs
+ remarks: Records status of health inspector runs over time
+ columns:
+ - column:
+ name: id
+ type: int
+ autoIncrement: true
+ constraints:
+ primaryKey: true
+ nullable: false
+ - column:
+ name: message
+ type: ${text.type}
+ remarks: A message to show to the instance admin.
+ - column:
+ name: check_name
+ type: varchar(254)
+ remarks: The name of the check
+ constraints:
+ nullable: false
+ - column:
+ name: run_at
+ type: ${timestamp_type}
+ remarks: When it was run
+ defaultValueComputed: current_timestamp
+ constraints:
+ nullable: false
+ - column:
+ name: health
+ type: int
+ remarks: Health as a percentage out of 100
+ constraints:
+ nullable: false
diff --git a/src/metabase/api_routes/routes.clj b/src/metabase/api_routes/routes.clj
index 493287d7eea..181c4464656 100644
--- a/src/metabase/api_routes/routes.clj
+++ b/src/metabase/api_routes/routes.clj
@@ -28,6 +28,7 @@
[metabase.frontend-errors.api]
[metabase.geojson.api]
[metabase.glossary.api]
+ [metabase.health-inspector.api]
[metabase.indexed-entities.api]
[metabase.llm.api]
[metabase.logger.api]
@@ -188,6 +189,7 @@
"/geojson" 'metabase.geojson.api
"/glossary" (+auth 'metabase.glossary.api)
"/google" (+auth metabase.sso.api/google-auth-routes)
+ "/health-inspector" (+auth 'metabase.health-inspector.api)
"/ldap" (+auth metabase.sso.api/ldap-routes)
"/llm" (+auth metabase.llm.api/routes)
"/logger" (+auth 'metabase.logger.api)
diff --git a/src/metabase/core/init.clj b/src/metabase/core/init.clj
index 7a8bfc3a7de..467ea412dbb 100644
--- a/src/metabase/core/init.clj
+++ b/src/metabase/core/init.clj
@@ -33,6 +33,7 @@
[metabase.embedding.init]
[metabase.events.init]
[metabase.geojson.init]
+ [metabase.health-inspector.init]
[metabase.indexed-entities.init]
[metabase.lib-be.init]
[metabase.lib.init]
diff --git a/src/metabase/health_inspector/api.clj b/src/metabase/health_inspector/api.clj
new file mode 100644
index 00000000000..f39dcd23f3a
--- /dev/null
+++ b/src/metabase/health_inspector/api.clj
@@ -0,0 +1,19 @@
+(ns metabase.health-inspector.api
+ (:require
+ [metabase.api.common :as api]
+ [metabase.api.macros :as api.macros]
+ [metabase.health-inspector.core :as health]
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.malli.schema :as ms]))
+
+(mr/def ::result [:map
+ [:check_name string?]
+ [:health number?]
+ [:message string?]
+ [:run_at ms/TemporalInstant]])
+
+(api.macros/defendpoint :get "/" :- [:sequential ::result]
+ "Get a list of recent health check runs."
+ [_route-params {:keys [limit] :as _query-params} _body]
+ (api/check-superuser)
+ (health/list-runs (min (or limit 32) 512)))
diff --git a/src/metabase/health_inspector/core.clj b/src/metabase/health_inspector/core.clj
new file mode 100644
index 00000000000..cd73c632ba6
--- /dev/null
+++ b/src/metabase/health_inspector/core.clj
@@ -0,0 +1,92 @@
+(ns metabase.health-inspector.core
+ (:require
+ [clojurewerkz.quartzite.jobs :as jobs]
+ [clojurewerkz.quartzite.schedule.cron :as cron]
+ [clojurewerkz.quartzite.triggers :as triggers]
+ [metabase.health-inspector.settings :as setting]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.schema :as schema]
+ [metabase.task.core :as task]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.malli.registry :as mr]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- validate-query [{:keys [total valid]} {:keys [dataset_query]}]
+ (let [timer (u/start-timer)
+ query (lib-be/normalize-query (json/decode dataset_query keyword))
+ valid? (mr/validate ::schema/query query)]
+ (Thread/sleep ^Long (u/since-ms timer))
+ {:total (inc total)
+ :valid (if valid?
+ (inc valid)
+ valid)}))
+
+(defn- percent [n] (* 100 (int n)))
+
+(defn- validate-queries []
+ (let [queries (t2/reducible-select :report_card {:where [:= :archived false]})
+ {:keys [total valid]} (reduce validate-query {:total 0 :valid 0} queries)
+ ratio (if (zero? total)
+ 1
+ (/ valid total))]
+ {:health (percent ratio)
+ :message (if (= 1 ratio)
+ "All queries valid."
+ "Some queries are invalid.")}))
+
+(defonce ^:private checks (atom {:validate-queries validate-queries}))
+
+(defn register-check!
+ "Register a new check function with a given name.
+ Check functions take no args and return a map with a :health ratio and :description string."
+ [name check-fn]
+ (swap! checks assoc name check-fn))
+
+(defn report
+ "Run all registered checks and produce a report describing potential problems."
+ []
+ (into {} (for [[name f] @checks]
+ [name (f)])))
+
+(defn save-report
+ "Run a health inspector report and save it to the DB."
+ []
+ (doseq [[check-name result] (report)]
+ (t2/insert! :health_inspector_runs (-> result
+ (select-keys [:health :message])
+ (assoc :check_name (name check-name))))))
+
+(defn list-runs
+ "Return the most recent health inspector runs from the DB."
+ [limit]
+ (t2/select :health_inspector_runs {:limit limit :order-by [[:run_at :desc]]}))
+
+(task/defjob ^:private ^{org.quartz.DisallowConcurrentExecution true} SaveReport [_]
+ (when (setting/health-inspector-enabled)
+ ;; background job should always be the lowest priority
+ (.setPriority (Thread/currentThread) 1)
+ ;; quartz doesn't have support for jitter, so we fake it with a sleep
+ (Thread/sleep ^Long (rand-int 60000))
+ (save-report)))
+
+(defmethod task/init! ::SaveReport [_]
+ (let [job-key (jobs/key "metabase.health-inspector.job")
+ trigger-key (triggers/key "metabase.health-inspector.trigger")
+ job (jobs/build
+ (jobs/of-type SaveReport)
+ (jobs/with-identity job-key)
+ (jobs/with-description "Gather health checks.")
+ (jobs/store-durably))
+ trigger (triggers/build
+ (triggers/with-identity trigger-key)
+ (triggers/for-job job-key)
+ (triggers/start-now)
+ ;; 2:28AM every day
+ (triggers/with-schedule
+ (cron/schedule
+ (cron/cron-schedule "0 28 2 * * ? *")
+ (cron/with-misfire-handling-instruction-do-nothing))))]
+ (task/schedule-task! job trigger)))
diff --git a/src/metabase/health_inspector/init.clj b/src/metabase/health_inspector/init.clj
new file mode 100644
index 00000000000..b53e42a19f3
--- /dev/null
+++ b/src/metabase/health_inspector/init.clj
@@ -0,0 +1,3 @@
+(ns metabase.health-inspector.init
+ (:require
+ [metabase.health-inspector.settings]))
diff --git a/src/metabase/health_inspector/settings.clj b/src/metabase/health_inspector/settings.clj
new file mode 100644
index 00000000000..7a8c2556762
--- /dev/null
+++ b/src/metabase/health_inspector/settings.clj
@@ -0,0 +1,13 @@
+(ns metabase.health-inspector.settings
+ (:require
+ [metabase.settings.core :refer [defsetting]]
+ [metabase.util.i18n :refer [deferred-tru]]))
+
+(defsetting health-inspector-enabled
+ (deferred-tru "Enable or disable all health inspector checks.")
+ :type :boolean
+ :default false
+ :doc false
+ :visibility :admin
+ :export? false
+ :audit :getter)
diff --git a/test/metabase/health_inspector/api_test.clj b/test/metabase/health_inspector/api_test.clj
new file mode 100644
index 00000000000..5cd959a63b5
--- /dev/null
+++ b/test/metabase/health_inspector/api_test.clj
@@ -0,0 +1,15 @@
+(ns metabase.health-inspector.api-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.health-inspector.core :as hi]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(deftest api-test
+ (t2/delete! :health_inspector_runs)
+ (hi/save-report)
+ (hi/save-report)
+ (let [response (mt/user-http-request :crowberto :get 200 "/health-inspector")]
+ (is (= [100 100 100 100] (map :health response)))
+ (is (= ["test-check" "test-check" "validate-queries" "validate-queries"]
+ (sort (map :check_name response))))))
diff --git a/test/metabase/health_inspector/core_test.clj b/test/metabase/health_inspector/core_test.clj
new file mode 100644
index 00000000000..b2c03126eb2
--- /dev/null
+++ b/test/metabase/health_inspector/core_test.clj
@@ -0,0 +1,28 @@
+(ns metabase.health-inspector.core-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.health-inspector.core :as hi]
+ [toucan2.core :as t2]))
+
+(defn- test-check []
+ {:health 100
+ :message "test check"})
+
+(hi/register-check! :test-check test-check)
+
+(deftest report-test
+ (let [report (hi/report)]
+ (testing "test check works"
+ (is (= {:health 100 :message "test check"}
+ (:test-check report))))
+ (testing "validate-queries works"
+ (is (= 100 (-> report :validate-queries :health))))))
+
+(deftest report-db-test
+ (t2/delete! :health_inspector_runs)
+ (hi/save-report)
+ (hi/save-report)
+ (let [runs (group-by :check_name (hi/list-runs 32))]
+ (is (= [100 100] (map :health (runs "test-check"))))
+ (is (= ["test check" "test check"] (map :message (runs "test-check"))))
+ (is (= [100 100] (map :health (runs "validate-queries"))))))