The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Add CLI usage analytics (#78216)
Sébastiend8f7ae6a91d7
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.ednindex 2f6cce44842..685539ae529 100644--- a/.clj-kondo/config/modules/config.edn+++ b/.clj-kondo/config/modules/config.edn@@ -156,8 +156,7 @@agent-api{:team "Metabot"- :api #{metabase.agent-api.api- metabase.agent-api.init}+ :api #{metabase.agent-api.api metabase.agent-api.init metabase.agent-api.usage}:uses #{ai-tracingapiauth-identity@@ -169,6 +168,7 @@lib-bellmmetabot+ premium-featuresqueriesquery-permissionsquery-processor@@ -183,7 +183,8 @@:model/DashboardTab:model/Database:model/Table- :model/User}}+ :model/User}+ :model-exports #{:model/AgentApiCallLog}}agent-lib{:team "Metabot"@@ -2907,6 +2908,17 @@:model/Sandbox:model/Table}}+ enterprise/agent-api+ {:team "Metabot"+ :api #{metabase-enterprise.agent-api.init}+ :uses #{agent-api+ analytics+ metabot+ premium-features+ task+ util}+ :model-imports #{:model/AgentApiCallLog}}+enterprise/analytics{:team "UX West":api #{}diff --git a/enterprise/backend/src/metabase_enterprise/agent_api/init.clj b/enterprise/backend/src/metabase_enterprise/agent_api/init.cljnew file mode 100644index 00000000000..8a6e089446b--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/agent_api/init.clj@@ -0,0 +1,6 @@+(ns metabase-enterprise.agent-api.init+ "Startup wiring for the enterprise Agent API module — loads the scheduled Agent API usage+ trimmer so its `task/init!` runs on boot (on every EE instance, matching where Agent API usage+ is collected)."+ (:require+ [metabase-enterprise.agent-api.task.agent-api-usage-trimmer]))diff --git a/enterprise/backend/src/metabase_enterprise/agent_api/task/agent_api_usage_trimmer.clj b/enterprise/backend/src/metabase_enterprise/agent_api/task/agent_api_usage_trimmer.cljnew file mode 100644index 00000000000..fae514aac17--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/agent_api/task/agent_api_usage_trimmer.clj@@ -0,0 +1,53 @@+(ns metabase-enterprise.agent-api.task.agent-api-usage-trimmer+ "Scheduled task to delete `agent_api_call_log` rows older than the configured+ `ai-usage-max-retention-days`. Mirrors the Metabot `ai-usage-trimmer` and the MCP usage+ trimmer: Agent API usage is collected on every EE instance, so its retention runs on every EE+ instance too — deliberately *not* audit-app-gated (which would let data grow unbounded on+ instances that collect but can't view it)."+ (:require+ [clojurewerkz.quartzite.jobs :as jobs]+ [clojurewerkz.quartzite.schedule.cron :as cron]+ [clojurewerkz.quartzite.triggers :as triggers]+ [java-time.api :as t]+ [metabase.metabot.settings :as metabot.settings]+ [metabase.task.core :as task]+ [metabase.util.log :as log]+ [toucan2.core :as t2])+ (:import+ (org.quartz DisallowConcurrentExecution)))++(set! *warn-on-reflection* true)++(def ^:private trimmer-job-key (jobs/key "metabase.task.agent-api.usage-trimmer.job"))+(def ^:private trimmer-trigger-key (triggers/key "metabase.task.agent-api.usage-trimmer.trigger"))++(defn- trim-old-agent-api-usage-data!+ []+ (let [retention-days (metabot.settings/ai-usage-max-retention-days)]+ (if (nil? retention-days)+ (log/info "Skipping Agent API usage log cleanup; ai-usage-max-retention-days is 0 (infinite retention).")+ (let [cutoff (t/minus (t/offset-date-time) (t/days (long retention-days)))]+ (log/infof "Trimming Agent API usage log rows older than %d days." (long retention-days))+ (let [calls (t2/delete! :model/AgentApiCallLog {:where [:< :created_at cutoff]})]+ (log/infof "Agent API usage log cleanup complete. Deleted %d call rows." (or calls 0)))))))++(task/defjob ^{DisallowConcurrentExecution true+ :doc "Delete old Agent API usage log rows"}+ AgentApiUsageTrimmer [_ctx]+ (trim-old-agent-api-usage-data!))++(defmethod task/init! ::AgentApiUsageTrimmer+ [_]+ (let [job (jobs/build+ (jobs/of-type AgentApiUsageTrimmer)+ (jobs/with-identity trimmer-job-key))+ trigger (triggers/build+ (triggers/with-identity trimmer-trigger-key)+ (triggers/start-now)+ (triggers/with-schedule+ ;; Quartz 6-field cron (sec min hour day-of-month month day-of-week): daily at+ ;; 23:24:41. The offset from the MCP trimmer's 23:19:41 just staggers the two+ ;; independent jobs (different tables) so they don't fire at the same instant —+ ;; it's not a dependency; overlapping runs would be harmless.+ (cron/cron-schedule "41 24 23 * * ?")))]+ (task/schedule-task! job trigger)))diff --git a/enterprise/backend/src/metabase_enterprise/agent_api/usage.clj b/enterprise/backend/src/metabase_enterprise/agent_api/usage.cljnew file mode 100644index 00000000000..7c2ca62de13--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/agent_api/usage.clj@@ -0,0 +1,52 @@+(ns metabase-enterprise.agent-api.usage+ "Enterprise implementation of Agent API (CLI) usage logging.++ Writes one lean `agent_api_call_log` row per direct Agent API HTTP call. Collection runs on+ every EE instance (`:feature :none`), mirroring `ai_usage_log`; the `ip_address` and+ `error_message` PII columns are populated only when `analytics-pii-retention-enabled` is on+ (itself `:audit-app`-gated). Every write is best-effort: a failure is logged and swallowed so+ logging never fails the Agent API request and adds negligible latency."+ (:require+ [metabase.agent-api.usage :as agent-api.usage]+ [metabase.analytics.core :as analytics]+ [metabase.analytics.settings :as analytics.settings]+ [metabase.premium-features.core :refer [defenterprise]]+ [metabase.util :as u]+ [metabase.util.log :as log]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(def ^:private error-message-max-length+ "Cap on the stored error_message length (gated PII), mirroring query_execution.parameters."+ 1024)++(def ^:private operation-max-length+ "Cap on the stored operation length, matching the `agent_api_call_log.operation` column width."+ 255)++(defenterprise record-agent-api-call!+ "EE: write one `agent_api_call_log` row per direct Agent API HTTP call. `client_name` is+ classified from the caller's self-reported User-Agent; `status` is success/error. `ip_address`+ and `error_message` are PII — stored only when `analytics-pii-retention-enabled` is on."+ :feature :none+ [{:keys [user-id tenant-id user-agent operation status duration-ms ip-address error-message]}]+ (try+ (let [;; `pii-fields-from` returns the gated PII columns only when retention is on (nil+ ;; otherwise). Allowlist the one column the row has, so a new field on the shared helper+ ;; can't silently start persisting here without a deliberate change.+ pii (select-keys (analytics/pii-fields-from {:user-agent user-agent+ :ip-address ip-address})+ [:ip_address])]+ (t2/insert! :model/AgentApiCallLog+ (merge {:user_id user-id+ :tenant_id tenant-id+ :client_name (agent-api.usage/detect-client user-agent)+ :operation (some-> operation (u/truncate operation-max-length))+ :status status+ :duration_ms duration-ms+ :error_message (when (analytics.settings/analytics-pii-retention-enabled)+ (some-> error-message (u/truncate error-message-max-length)))}+ pii)))+ (catch Throwable e+ (log/warn e "Failed to record Agent API call"))))diff --git a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.cljindex 197eecc4f4c..b1a8e6ea254 100644--- a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj+++ b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj@@ -33,7 +33,8 @@"v_metabot_conversations""v_metabot_messages""v_ai_usage_log"- "v_mcp_tool_calls"})+ "v_mcp_tool_calls"+ "v_agent_api_calls"})(defenterprise check-audit-db-permissions"Performs a number of permission checks to ensure that a query on the Audit database can be run.diff --git a/enterprise/backend/src/metabase_enterprise/core/init.clj b/enterprise/backend/src/metabase_enterprise/core/init.cljindex 35387358e84..95b3a484fe7 100644--- a/enterprise/backend/src/metabase_enterprise/core/init.clj+++ b/enterprise/backend/src/metabase_enterprise/core/init.clj@@ -8,6 +8,7 @@(:require[metabase-enterprise.action-v2.init][metabase-enterprise.advanced-config.init]+ [metabase-enterprise.agent-api.init][metabase-enterprise.audit-app.init][metabase-enterprise.cache.init][metabase-enterprise.custom-viz-plugin.init]diff --git a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.cljindex c9e51a236ff..5ca5c24ee6f 100644--- a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj+++ b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj@@ -63,7 +63,8 @@(def excluded-models"List of models which are not going to be serialized ever."- ["AiUsageLog"+ ["AgentApiCallLog"+ "AiUsageLog""AnalysisFinding""AnalysisFindingError""ApiKey"diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.cljnew file mode 100644index 00000000000..94c38e5b742--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj@@ -0,0 +1,77 @@+(ns metabase-enterprise.agent-api.api-test+ "Integration tests for the Agent API usage instrumentation in `metabase.agent-api.api` — driving+ the real `routes` wrapper so the recording happens on the same synchronous thread, where+ identity, status, duration, and PII are all in scope. Recording runs on every EE instance+ (`:feature :none`); PII is gated by `analytics-pii-retention-enabled` (itself `:audit-app`-gated)."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [metabase.agent-api.api :as agent-api.api]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(use-fixtures :once (fixtures/initialize :db :test-users))++(defn- cleanup-by-ip!+ "Isolate + clean up a test's rows by the unique fake ip_address it recorded (PII, so present only+ when retention is on)."+ [& conditions]+ (apply t2/delete! :model/AgentApiCallLog conditions))++(defn- random-ip+ "A random, well-formed IPv4 address for test-row isolation. Well-formed so it survives+ `request/ip-address`'s non-IP-character stripping unchanged, and thus round-trips into+ `ip_address` for a precise lookup/cleanup key."+ []+ (format "10.%d.%d.%d" (rand-int 250) (rand-int 250) (rand-int 250)))++(defn- invoke-routes+ "Drive `agent-api.api/routes` synchronously and return the response. `extra` is merged onto a+ minimal authenticated GET /api/agent/v1/ping request. `:uri` is the full public path (what the+ recorder stores as `operation`); `:path-info` is the context-stripped path the router matches on."+ [extra]+ (let [p (promise)]+ (agent-api.api/routes+ (merge {:request-method :get+ :uri "/api/agent/v1/ping"+ :path-info "/v1/ping"+ :metabase-user-id (mt/user->id :rasta)}+ extra)+ (fn [resp] (deliver p resp))+ (fn [e] (deliver p e)))+ (deref p 5000 :timeout)))++(deftest routes-records-direct-http-call-test+ (testing "a direct Agent API call is recorded with client classified from the User-Agent"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled true]+ (let [ip (random-ip)]+ (try+ (let [resp (invoke-routes {:headers {"user-agent" "metabase-cli/4.5.6"}+ :remote-addr ip})]+ (is (= 200 (:status resp))))+ (let [row (t2/select-one :model/AgentApiCallLog :ip_address ip)]+ (is (some? row) "a row is recorded for the direct HTTP call")+ (is (= "metabase-cli" (:client_name row)))+ (is (= "GET /api/agent/v1/ping" (:operation row)))+ (is (= "success" (:status row)))+ (is (= (mt/user->id :rasta) (:user_id row)))+ (is (nat-int? (:duration_ms row))))+ (finally (cleanup-by-ip! :ip_address ip))))))))++(deftest routes-skips-synthetic-internal-request-test+ (testing "MCP's synthetic in-process dispatch (:agent-api-internal-request? true) is NOT recorded,+ so it never double-counts against the row already written to mcp_tool_call_log"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled true]+ (let [ip (random-ip)]+ (try+ (let [resp (invoke-routes {:headers {"user-agent" "metabase-cli/4.5.6"}+ :remote-addr ip+ :agent-api-internal-request? true})]+ (is (= 200 (:status resp))))+ (is (nil? (t2/select-one :model/AgentApiCallLog :ip_address ip))+ "no agent_api_call_log row is written for the synthetic internal request")+ (finally (cleanup-by-ip! :ip_address ip))))))))diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/task/agent_api_usage_trimmer_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/task/agent_api_usage_trimmer_test.cljnew file mode 100644index 00000000000..50fa18df7d4--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/agent_api/task/agent_api_usage_trimmer_test.clj@@ -0,0 +1,37 @@+(ns metabase-enterprise.agent-api.task.agent-api-usage-trimmer-test+ (:require+ [clojure.test :refer :all]+ [java-time.api :as t]+ [metabase-enterprise.agent-api.task.agent-api-usage-trimmer :as agent-api-usage-trimmer]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [toucan2.core :as t2]))++(use-fixtures :once (fixtures/initialize :db))++(set! *warn-on-reflection* true)++;; NOTE: these tests deliberately do NOT wrap in `mt/with-premium-features #{:audit-app}` — Agent API+;; usage is collected on every EE instance, so its trimmer must run regardless of the audit-app feature.++(deftest trims-rows-older-than-custom-retention-test+ (testing "with retention set to 30 days, call rows older than 30 days are deleted"+ (mt/with-temp+ [:model/AgentApiCallLog {recent :id} {:operation "GET /api/agent/v1/ping" :created_at (t/offset-date-time)}+ :model/AgentApiCallLog {boundary :id} {:operation "GET /api/agent/v1/ping" :created_at (t/minus (t/offset-date-time) (t/days 31))}+ :model/AgentApiCallLog {old :id} {:operation "GET /api/agent/v1/ping" :created_at (t/minus (t/offset-date-time) (t/days 200))}]+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 30]+ (#'agent-api-usage-trimmer/trim-old-agent-api-usage-data!)+ (is (= #{recent}+ (t2/select-fn-set :id :model/AgentApiCallLog {:where [:in :id [recent boundary old]]}))+ "call rows older than the cutoff are deleted, recent kept")))))++(deftest skips-deletion-when-retention-is-infinite-test+ (testing "when retention is set to 0 (infinite), no rows are deleted"+ (mt/with-temp+ [:model/AgentApiCallLog {recent :id} {:operation "GET /api/agent/v1/ping" :created_at (t/offset-date-time)}+ :model/AgentApiCallLog {old :id} {:operation "GET /api/agent/v1/ping" :created_at (t/minus (t/offset-date-time) (t/years 5))}]+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 0]+ (#'agent-api-usage-trimmer/trim-old-agent-api-usage-data!)+ (is (= #{recent old}+ (t2/select-fn-set :id :model/AgentApiCallLog {:where [:in :id [recent old]]})))))))diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/usage_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/usage_test.cljnew file mode 100644index 00000000000..3dd52b8e8c3--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/agent_api/usage_test.clj@@ -0,0 +1,131 @@+(ns metabase-enterprise.agent-api.usage-test+ "Tests for the Agent API (CLI) usage write point — one lean `agent_api_call_log` row per direct+ Agent API HTTP call. Exercises the `defenterprise` dispatch via the OSS entry point in+ `metabase.agent-api.usage`. Collection runs on every EE instance (`:feature :none`); PII is gated+ by `analytics-pii-retention-enabled` (itself `:audit-app`-gated). The end-to-end path through the+ real `routes` wrapper is covered in `metabase-enterprise.agent-api.api-test`."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [metabase.agent-api.usage :as usage]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(use-fixtures :once (fixtures/initialize :db :test-users))++(defn- cleanup-by-ip!+ "Rows are isolated + cleaned up by a unique fake ip_address (PII, so recorded only when retention+ is on) or by a unique operation string, whichever the test keys on."+ [& conditions]+ (apply t2/delete! :model/AgentApiCallLog conditions))++;;; --------------------------------------------- detect-client (pure) --------------------------------------++(deftest ^:parallel detect-client-test+ (testing "the CLI's User-Agent maps to the canonical client key"+ (is (= "metabase-cli" (usage/detect-client "metabase-cli/1.2.3")))+ (is (= "metabase-cli" (usage/detect-client "Metabase-CLI/9")))+ (is (= "metabase-cli" (usage/detect-client "some-wrapper metabase-cli/0.1"))))+ (testing "unknown / missing User-Agents fall back to \"other\""+ (is (= "other" (usage/detect-client "Mozilla/5.0")))+ (is (= "other" (usage/detect-client "")))+ (is (= "other" (usage/detect-client nil))))+ (testing "every value produced is a supported key or the \"other\" fallback"+ (doseq [ua ["metabase-cli/1" "curl/8" "Mozilla/5.0" nil ""]]+ (is (contains? (conj usage/supported-client-keys "other")+ (usage/detect-client ua))))))++;;; ------------------------------------------ record-agent-api-call! ---------------------------------------++(deftest record-agent-api-call!-writes-row-test+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled true]+ (let [op (str "GET /api/agent/v1/ping?" (mt/random-name))]+ (try+ (usage/record-agent-api-call!+ {:user-id (mt/user->id :rasta)+ :tenant-id nil+ :user-agent "metabase-cli/1.2.3"+ :operation op+ :status "success"+ :duration-ms 12+ :ip-address "203.0.113.7"})+ (let [row (t2/select-one :model/AgentApiCallLog :operation op)]+ (testing "non-PII columns"+ (is (= "metabase-cli" (:client_name row)))+ (is (= "success" (:status row)))+ (is (= 12 (:duration_ms row)))+ (is (= (mt/user->id :rasta) (:user_id row))))+ (testing "PII column populated when retention is on"+ (is (= "203.0.113.7" (:ip_address row)))))+ (finally (cleanup-by-ip! :operation op)))))))++(deftest record-agent-api-call!-pii-gate-test+ (testing "ip_address / error_message are stored only when retention is on"+ (mt/with-premium-features #{:audit-app}+ (testing "retention on: PII columns populated"+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled true]+ (let [op (str "on-" (mt/random-name))]+ (try+ (usage/record-agent-api-call!+ {:user-id (mt/user->id :rasta) :operation op :status "error" :duration-ms 1+ :user-agent "metabase-cli/1" :ip-address "203.0.113.7" :error-message "boom"})+ (let [row (t2/select-one :model/AgentApiCallLog :operation op)]+ (is (= "203.0.113.7" (:ip_address row)))+ (is (= "boom" (:error_message row))))+ (finally (cleanup-by-ip! :operation op))))))+ (testing "retention off: PII columns stay null"+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled false]+ (let [op (str "off-" (mt/random-name))]+ (try+ (usage/record-agent-api-call!+ {:user-id (mt/user->id :rasta) :operation op :status "error" :duration-ms 1+ :user-agent "metabase-cli/1" :ip-address "203.0.113.7" :error-message "boom"})+ (let [row (t2/select-one :model/AgentApiCallLog :operation op)]+ (is (nil? (:ip_address row)))+ (is (nil? (:error_message row))))+ (finally (cleanup-by-ip! :operation op)))))))))++(deftest record-agent-api-call!-truncates-operation-test+ (testing "an over-long operation is truncated to the column width so the row still records"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [analytics-pii-retention-enabled true]+ (let [ip (str (random-uuid))+ long-op (apply str (repeat 300 \x))]+ (try+ (usage/record-agent-api-call!+ {:user-id (mt/user->id :rasta) :operation long-op :status "success" :duration-ms 1+ :ip-address ip})+ (is (= 255 (count (:operation (t2/select-one :model/AgentApiCallLog :ip_address ip)))))+ (finally (cleanup-by-ip! :ip_address ip))))))))++;;; --------------------------------------------- Feature gating --------------------------------------------++(deftest collection-runs-on-ee-without-audit-app-test+ (testing "collection happens on any EE instance (:feature :none), but PII stays null without :audit-app"+ (mt/with-premium-features #{}+ (let [op (str "no-audit-" (mt/random-name))]+ (try+ (usage/record-agent-api-call!+ {:user-id (mt/user->id :rasta) :operation op :status "success" :duration-ms 1+ :user-agent "metabase-cli/1" :ip-address "1.2.3.4" :error-message "x"})+ (let [row (t2/select-one :model/AgentApiCallLog :operation op)]+ (testing "non-PII row is written"+ (is (some? row))+ (is (= "metabase-cli" (:client_name row)))+ (is (= (mt/user->id :rasta) (:user_id row))))+ (testing "PII is null because retention can't be enabled without :audit-app"+ (is (nil? (:ip_address row)))+ (is (nil? (:error_message row)))))+ (finally (cleanup-by-ip! :operation op)))))))++;;; ------------------------------------------- Best-effort logging -----------------------------------------++(deftest logging-is-best-effort-test+ (testing "a failed write is swallowed and never propagates"+ (mt/with-premium-features #{:audit-app}+ (mt/with-dynamic-fn-redefs [t2/insert! (fn [& _] (throw (ex-info "boom" {})))]+ (is (nil? (usage/record-agent-api-call!+ {:user-id 1 :operation "GET /api/agent/v1/ping" :status "success" :duration-ms 1})))))))diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/v_agent_api_calls_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/v_agent_api_calls_test.cljnew file mode 100644index 00000000000..fe96a4f0d91--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/agent_api/v_agent_api_calls_test.clj@@ -0,0 +1,63 @@+(ns metabase-enterprise.agent-api.v-agent-api-calls-test+ "Tests for the `v_agent_api_calls` SQL view. Client identity is stored on each call row, and the+ view derives `client_display_name` / `user_display_name` from it and LEFT JOINs core_user + tenant."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [java-time.api :as t]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [toucan2.core :as t2]))++(use-fixtures :once (fixtures/initialize :db))++(set! *warn-on-reflection* true)++(defn- query-view+ "Query v_agent_api_calls, returning only rows for the given call ids."+ [call-ids]+ (t2/query {:select [:*]+ :from [:v_agent_api_calls]+ :where [:in :call_id call-ids]}))++(defn- find-row [rows call-id]+ (some #(when (= (:call_id %) call-id) %) rows))++(deftest joins-and-derived-columns-test+ (testing "the view derives display columns from the identity stored on each call row"+ (mt/with-temp+ [:model/User {user-id :id} {:first_name "Ada" :last_name "Lovelace"}+ :model/AgentApiCallLog {cli-id :id} {:user_id user-id+ :operation "POST /api/agent/v1/query" :status "success"+ :duration_ms 42 :client_name "metabase-cli"+ :created_at (t/offset-date-time)}+ :model/AgentApiCallLog {other-id :id} {:user_id user-id+ :operation "GET /api/agent/v1/ping" :status "error"+ :duration_ms 7 :client_name "other"+ :error_message "bad params"+ :created_at (t/offset-date-time)}]+ (let [rows (query-view [cli-id other-id])+ cli (find-row rows cli-id)+ other (find-row rows other-id)]+ (is (=? {:operation "POST /api/agent/v1/query"+ :status "success"+ :client_name "metabase-cli"+ :client_display_name "Metabase CLI"+ :user_display_name "Ada Lovelace"}+ cli))+ (is (=? {:status "error"+ :client_name "other"+ :client_display_name "Other"+ :error_message "bad params"}+ other))))))++(deftest unknown-client-and-user-test+ (testing "a call with no client and no user still appears, with null display columns"+ (mt/with-temp+ [:model/AgentApiCallLog {orphan-id :id} {:user_id nil+ :operation "GET /api/agent/v1/ping" :status "success"+ :duration_ms 5 :created_at (t/offset-date-time)}]+ (let [row (find-row (query-view [orphan-id]) orphan-id)]+ (is (some? row) "the row is not dropped")+ (is (=? {:operation "GET /api/agent/v1/ping" :client_name nil+ :client_display_name nil :user_display_name nil}+ row))))))diff --git a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.cljindex f66f944fbf7..553e108ab0e 100644--- a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj+++ b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj@@ -36,7 +36,8 @@- not exported in serialization; or- exported as a child of something else (eg. timeline_event under timeline)so they don't need a generated entity_id."- #{:model/AiUsageLog+ #{:model/AgentApiCallLog+ :model/AiUsageLog:model/AnalysisFinding:model/AnalysisFindingError:model/ApiKeydiff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsEmptyState.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsEmptyState.tsxnew file mode 100644index 00000000000..93fcdf3fe38--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsEmptyState.tsx@@ -0,0 +1,17 @@+import { t } from "ttag";++import { EmptyState } from "metabase/common/components/EmptyState";+import { Flex } from "metabase/ui";++/** Centered placeholder shown (in place of the tabs/charts) when the filtered view has no calls. */+export function CliAnalyticsEmptyState() {+ return (+ <Flex flex={1} mih="60vh" align="center" justify="center">+ <EmptyState+ icon="audit"+ title={t`No CLI activity`}+ message={t`Calls from the CLI and other Agent API clients will show up here. Try widening the date range or check back once clients start making requests.`}+ />+ </Flex>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.tsxnew file mode 100644index 00000000000..65712920426--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.tsx@@ -0,0 +1,224 @@+import { useMemo } from "react";+import { match } from "ts-pattern";+import { t } from "ttag";++import { MetabotAdminLayout } from "metabase/admin/ai/MetabotAdminLayout";+import { SettingsPageWrapper } from "metabase/admin/components/SettingsSection";+import { useSetting } from "metabase/common/hooks";+import { useUrlState } from "metabase/common/hooks/use-url-state";+import type { WithRouterProps } from "metabase/router";+import { Flex, Loader, SimpleGrid, Stack, Tabs, Title } from "metabase/ui";++import {+ // The shared audit filter bar; aliased since it has nothing to do with Metabot "conversations".+ ConversationFilters as CliCallsFilter,+ useFilterOptions,+} from "../../metabot-analytics/components/ConversationFilters";+import { useAuditTable } from "../../metabot-analytics/hooks/useAuditTable";+import { VIEW_AGENT_API_CALLS, VIEW_GROUP_MEMBERS } from "../constants";+import { useCliHasData } from "../hooks/useCliHasData";+import { buildCallsByDayByStatusQuery } from "../query-utils";+import type { CliTab } from "../url-state";+import { cliUrlStateConfig } from "../url-state";++import { CliAnalyticsEmptyState } from "./CliAnalyticsEmptyState";+import { CliBreakoutChart } from "./CliBreakoutChart";+import { CliCallerLivenessTable } from "./CliCallerLivenessTable";+import { CliCallsTimelineChart } from "./CliCallsTimelineChart";+import { CliEventsTable } from "./CliEventsTable";++/**+ * Admin CLI analytics page. Renders live ad-hoc queries over the `v_agent_api_calls` audit view+ * across two tabs (Charts and a row-level Calls table), sharing URL-state date/user/group+ * filters. Shows a single empty state (no tabs) when the filtered view has no activity.+ */+export function CliAnalyticsPage({ location }: WithRouterProps) {+ const [+ { date, user, group, tenant, tab, page, sort_column, sort_direction },+ { patchUrlState },+ ] = useUrlState(location, cliUrlStateConfig);++ const {+ dateFilter,+ userId,+ groupId,+ tenantId,+ groupNoFilterValue,+ userOptions,+ groupOptions,+ tenantOptions,+ hasTenants,+ } = useFilterOptions({ date, user, group, tenant });++ // IP address and error message are PII (null unless retention is on), so only surface those+ // columns when they're collected.+ const hasPii = useSetting("analytics-pii-retention-enabled") === true;++ const callsAudit = useAuditTable(VIEW_AGENT_API_CALLS);+ const groupMembersAudit = useAuditTable(VIEW_GROUP_MEMBERS);++ const dataSources = {+ provider: callsAudit.provider,+ table: callsAudit.table,+ groupMembersTable: groupMembersAudit.table,+ };++ const chartFilters = { dateFilter, userId, groupId, tenantId };++ // Keep this referentially stable: it feeds the events query's `useMemo`, and each rebuild mints+ // fresh metabase-lib UUIDs, which change the query's serialized RTK cache key and trigger a+ // redundant refetch (and loader flash) on every incidental re-render.+ const sortingOptions = useMemo(+ () => ({ sort_column, sort_direction }),+ [sort_column, sort_direction],+ );++ const { isInitialLoading, isRefetching, hasData, count } = useCliHasData({+ ...dataSources,+ ...chartFilters,+ });+ // Initial load shows a loader (never the empty state). After the first result, a filter+ // change keeps the charts mounted so they show their own skeletons while refetching; the+ // empty state only appears once a load has resolved to zero rows.+ const showEmpty = !isInitialLoading && !isRefetching && !hasData;++ // Only surface the errors section when the current filters actually match failed calls, so a+ // healthy instance doesn't show a row of empty error charts.+ const { hasData: hasErrors } = useCliHasData({+ ...dataSources,+ ...chartFilters,+ errorsOnly: true,+ });++ return (+ <MetabotAdminLayout fullWidth>+ <SettingsPageWrapper mt="sm">+ <Flex align="center" justify="space-between">+ <Title order={2}>{t`CLI analytics`}</Title>++ <CliCallsFilter+ date={date}+ onDateChange={(val) => patchUrlState({ date: val })}+ user={user}+ onUserChange={(val) => patchUrlState({ user: val })}+ userOptions={userOptions}+ group={group}+ onGroupChange={(val) => patchUrlState({ group: val })}+ groupOptions={groupOptions}+ groupNoFilterValue={groupNoFilterValue}+ tenant={tenant}+ onTenantChange={(val) => patchUrlState({ tenant: val })}+ tenantOptions={tenantOptions}+ hasTenants={hasTenants}+ />+ </Flex>++ {match({ isInitialLoading, showEmpty })+ .with({ isInitialLoading: true }, () => (+ <Flex mih="60vh" align="center" justify="center">+ <Loader size="lg" />+ </Flex>+ ))+ .with({ showEmpty: true }, () => <CliAnalyticsEmptyState />)+ .otherwise(() => (+ <Tabs+ value={tab}+ // tab/val _is_ a CliTab, but Mantine's Tab only deals with strings ¯\_(ツ)_/¯+ onChange={(val) => patchUrlState({ tab: val as CliTab })}+ keepMounted={false}+ >+ <Tabs.List mb="lg">+ <Tabs.Tab value="charts">{t`Usage`}</Tabs.Tab>+ <Tabs.Tab value="events">{t`Calls`}</Tabs.Tab>+ </Tabs.List>++ <Tabs.Panel value="charts">+ <Stack gap="lg">+ <CliCallsTimelineChart+ {...dataSources}+ {...chartFilters}+ title={t`Calls by client over time`}+ />+ <SimpleGrid cols={2} spacing="lg">+ <CliBreakoutChart+ {...dataSources}+ {...chartFilters}+ title={t`Calls by client`}+ display="pie"+ breakoutColumn="client_display_name"+ h={500}+ />+ <CliBreakoutChart+ {...dataSources}+ {...chartFilters}+ title={t`Calls by operation`}+ display="row"+ breakoutColumn="operation"+ h={500}+ />+ </SimpleGrid>+ <SimpleGrid cols={2} spacing="lg">+ <CliBreakoutChart+ {...dataSources}+ {...chartFilters}+ title={t`Calls by user`}+ display="row"+ breakoutColumn="user_display_name"+ h={500}+ />+ <CliCallerLivenessTable+ {...dataSources}+ {...chartFilters}+ title={t`User activity`}+ h={500}+ />+ </SimpleGrid>++ {hasErrors && (+ <>+ <Title order={3} mt="md">{t`Errors`}</Title>+ <CliCallsTimelineChart+ {...dataSources}+ {...chartFilters}+ title={t`Calls by status over time`}+ buildQuery={buildCallsByDayByStatusQuery}+ />+ <CliBreakoutChart+ {...dataSources}+ {...chartFilters}+ title={t`Errors by operation`}+ display="row"+ breakoutColumn="operation"+ errorsOnly+ h={500}+ />+ </>+ )}+ </Stack>+ </Tabs.Panel>++ <Tabs.Panel value="events">+ <CliEventsTable+ {...dataSources}+ {...chartFilters}+ hasTenants={hasTenants}+ hasPii={hasPii}+ page={page}+ total={count}+ onPageChange={(newPage) => patchUrlState({ page: newPage })}+ sortingOptions={sortingOptions}+ onSortingOptionsChange={(newSorting) =>+ patchUrlState({+ sort_column: newSorting.sort_column,+ sort_direction: newSorting.sort_direction,+ page: 0,+ })+ }+ />+ </Tabs.Panel>+ </Tabs>+ ))}+ </SettingsPageWrapper>+ </MetabotAdminLayout>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.unit.spec.tsxnew file mode 100644index 00000000000..7822e6d722d--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliAnalyticsPage.unit.spec.tsx@@ -0,0 +1,225 @@+import userEvent from "@testing-library/user-event";+import fetchMock from "fetch-mock";++import { setupEnterprisePlugins } from "__support__/enterprise";+import {+ setupGroupsEndpoint,+ setupUsersEndpoints,+} from "__support__/server-mocks";+import { mockSettings } from "__support__/settings";+import { renderWithProviders, screen, waitFor, within } from "__support__/ui";+import { createMockState } from "metabase/redux/store/mocks";+import { Route, withRouteProps } from "metabase/router";+import { registerVisualizations } from "metabase/visualizations/register";+import type { Database, Dataset, Field } from "metabase-types/api";+import {+ createMockColumn,+ createMockDatabase,+ createMockDataset,+ createMockDatasetData,+ createMockField,+ createMockGroup,+ createMockTable,+ createMockTokenFeatures,+ createMockUser,+} from "metabase-types/api/mocks";++import { AUDIT_DB_ID } from "../constants";++import { CliAnalyticsPage } from "./CliAnalyticsPage";++const RoutedCliAnalyticsPage = withRouteProps(CliAnalyticsPage);++registerVisualizations();++const AGENT_API_CALLS_TABLE_ID = 2001;+const GROUP_MEMBERS_TABLE_ID = 2002;++const BASE_TYPE = {+ text: "type/Text",+ integer: "type/Integer",+ dateTime: "type/DateTimeWithLocalTZ",+} as const;++type FieldSpec = [+ type: keyof typeof BASE_TYPE,+ name: string,+ semantic_type: Field["semantic_type"],+];++/** Build a mock audit-DB table (in `AUDIT_DB_ID`) with the given fields, for the metadata endpoint. */+const buildTable = (id: number, name: string, fields: FieldSpec[]) =>+ createMockTable({+ id,+ db_id: AUDIT_DB_ID,+ schema: "public",+ name,+ display_name: name,+ fields: fields.map(([type, fieldName, semantic_type], i) =>+ createMockField({+ id: id * 100 + i,+ table_id: id,+ name: fieldName,+ display_name: fieldName,+ fingerprint: null,+ base_type: BASE_TYPE[type],+ effective_type: BASE_TYPE[type],+ semantic_type,+ }),+ ),+ });++const auditDatabase: Database = createMockDatabase({+ id: AUDIT_DB_ID,+ name: "Audit DB",+ tables: [+ buildTable(AGENT_API_CALLS_TABLE_ID, "v_agent_api_calls", [+ ["text", "call_id", "type/PK"],+ ["dateTime", "created_at", "type/CreationTimestamp"],+ ["text", "operation", "type/Category"],+ ["text", "status", "type/Category"],+ ["integer", "duration_ms", "type/Quantity"],+ ["integer", "user_id", "type/FK"],+ ["text", "user_display_name", "type/Name"],+ ["text", "client_display_name", "type/Category"],+ ]),+ buildTable(GROUP_MEMBERS_TABLE_ID, "v_group_members", [+ ["integer", "user_id", "type/Description"],+ ["integer", "group_id", "type/PK"],+ ["text", "group_name", "type/Name"],+ ]),+ ],+});++// A breakout/count dataset that satisfies both the chart visualizations+// (breakout + aggregation columns) and the events table (named columns).+// Aggregation column first so the page's no-breakout count probe (reads rows[0][0]) sees a+// positive number; the `source` tags still let the breakout charts find the right columns.+const datasetResponse: Dataset = createMockDataset({+ data: createMockDatasetData({+ rows: [+ [12, "POST /api/agent/v1/query"],+ [7, "GET /api/agent/v1/search"],+ ],+ cols: [+ createMockColumn({+ source: "aggregation",+ name: "count",+ display_name: "Count",+ }),+ createMockColumn({+ source: "breakout",+ name: "operation",+ display_name: "Operation",+ }),+ ],+ }),+ database_id: AUDIT_DB_ID,+ row_count: 2,+ running_time: 1,+});++// A zero-count aggregation result — what the page's "has any data?" probe gets when the+// filtered view is empty.+const emptyDatasetResponse: Dataset = createMockDataset({+ data: createMockDatasetData({+ rows: [[0]],+ cols: [+ createMockColumn({+ source: "aggregation",+ name: "count",+ display_name: "Count",+ }),+ ],+ }),+ database_id: AUDIT_DB_ID,+ row_count: 1,+ running_time: 1,+});++/** Mock the audit-DB metadata, users/groups, and the `/api/dataset` adhoc endpoint (with the given dataset). */+function setupEndpoints(dataset: Dataset = datasetResponse) {+ fetchMock.get(`path:/api/database/${AUDIT_DB_ID}/metadata`, auditDatabase);+ setupUsersEndpoints([createMockUser({ id: 1, first_name: "Ada" })]);+ setupGroupsEndpoint([createMockGroup({ id: 1, name: "All Users" })]);+ fetchMock.post("path:/api/dataset", dataset, { name: "dataset" });+}++/** Render `CliAnalyticsPage` at its route with EE plugins + `audit_app`, optionally overriding the dataset response. */+function setup({ dataset }: { dataset?: Dataset } = {}) {+ setupEnterprisePlugins();+ setupEndpoints(dataset);++ return renderWithProviders(+ <Route+ path="/admin/metabot/usage-auditing/cli"+ element={<RoutedCliAnalyticsPage />}+ />,+ {+ initialRoute: "/admin/metabot/usage-auditing/cli",+ withRouter: true,+ storeInitialState: createMockState({+ settings: mockSettings({+ "token-features": createMockTokenFeatures({ audit_app: true }),+ }),+ }),+ },+ );+}++describe("CliAnalyticsPage", () => {+ it("renders the header, filters, and charts tab", async () => {+ setup();++ expect(+ await screen.findByRole("heading", { name: "CLI analytics" }),+ ).toBeInTheDocument();+ expect(+ screen.getByTestId("conversation-filters-date-select"),+ ).toBeInTheDocument();+ // Tabs appear only after the initial count query resolves (the page shows a loader first).+ expect(+ await screen.findByRole("tab", { name: "Usage" }),+ ).toBeInTheDocument();++ // Charts run ad-hoc dataset queries through /api/dataset.+ await waitFor(() => {+ expect(fetchMock.callHistory.called("dataset")).toBe(true);+ });+ expect(await screen.findByText("Calls by operation")).toBeInTheDocument();+ // The errors section renders because the (mocked) error count is > 0.+ expect(await screen.findByText("Errors by operation")).toBeInTheDocument();+ });++ it("switches to the calls tab and renders the sortable row-level table", async () => {+ setup();++ await screen.findByRole("heading", { name: "CLI analytics" });+ await userEvent.click(await screen.findByRole("tab", { name: "Calls" }));++ const eventsPanel = screen.getByRole("tabpanel");+ expect(await within(eventsPanel).findByRole("table")).toBeInTheDocument();+ // a curated column header and a cell value from the mocked page render+ expect(within(eventsPanel).getByText("Operation")).toBeInTheDocument();+ expect(+ await within(eventsPanel).findByText("POST /api/agent/v1/query"),+ ).toBeInTheDocument();+ });++ it("shows a single empty state (no tabs, no charts) when there is no activity", async () => {+ setup({ dataset: emptyDatasetResponse });++ expect(+ await screen.findByRole("heading", { name: "CLI analytics" }),+ ).toBeInTheDocument();+ expect(await screen.findByText("No CLI activity")).toBeInTheDocument();++ // No tabs render when the view is empty — so neither the charts nor the events table can.+ expect(+ screen.queryByRole("tab", { name: "Usage" }),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByRole("tab", { name: "Calls" }),+ ).not.toBeInTheDocument();+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliBreakoutChart.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliBreakoutChart.tsxnew file mode 100644index 00000000000..f73a739755e--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliBreakoutChart.tsx@@ -0,0 +1,159 @@+import { useMemo } from "react";+import { t } from "ttag";++import { Skeleton, useMantineTheme } from "metabase/ui";+import type {+ CardMetadata,+ MetadataProvider,+ Query,+ TableMetadata,+} from "metabase-lib";+import type { VisualizationDisplay } from "metabase-types/api";++import { BreakoutChartCard } from "../../metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";+import { mapBreakoutDimension } from "../../metabot-analytics/components/ConversationStatsPage/breakout-raw-series";+import { useAdhocBreakoutQuery } from "../../metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { CliFilters } from "../query-utils";+import {+ buildCountBreakoutQuery,+ buildErrorBreakoutQuery,+} from "../query-utils";+import { toCountBreakoutRawSeries } from "../raw-series";++const DEFAULT_CHART_HEIGHT = 350;+const DEFAULT_MAX_CATEGORIES = 8;++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++type Props = DataSources &+ CliFilters & {+ title: string;+ display: VisualizationDisplay;+ /** Column to break down call counts by (e.g. `client_display_name`, `operation`). */+ breakoutColumn: string;+ /** When set, count only failed calls (`status = error`) — for the error breakdown charts. */+ errorsOnly?: boolean;+ labelMapper?: (value: unknown) => unknown;+ maxCategories?: number;+ h?: number;+ };++type InnerProps = CliFilters & {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+ title: string;+ display: VisualizationDisplay;+ breakoutColumn: string;+ errorsOnly: boolean;+ labelMapper?: (value: unknown) => unknown;+ maxCategories: number;+ h: number;+};++/**+ * Single-breakout count chart (e.g. calls by client as a pie, calls by operation as a row chart).+ * Renders a skeleton until the audit metadata is loaded, then delegates to the inner component.+ */+export function CliBreakoutChart({+ provider,+ table,+ groupMembersTable,+ h = DEFAULT_CHART_HEIGHT,+ maxCategories = DEFAULT_MAX_CATEGORIES,+ errorsOnly = false,+ ...rest+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <CliBreakoutChartInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ h={h}+ maxCategories={maxCategories}+ errorsOnly={errorsOnly}+ {...rest}+ />+ );+}++/**+ * Loaded variant of {@link CliBreakoutChart}: builds the breakout query, runs it, and renders+ * the result through the shared chart card. Split out so the query hooks only run once metadata+ * (provider/table) is available.+ */+function CliBreakoutChartInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ title,+ display,+ breakoutColumn,+ errorsOnly,+ labelMapper,+ maxCategories,+ h,+}: InnerProps) {+ const query = useMemo<Query>(() => {+ const opts = {+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ breakoutColumn,+ };+ return errorsOnly+ ? buildErrorBreakoutQuery(opts)+ : buildCountBreakoutQuery(opts);+ }, [+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ breakoutColumn,+ errorsOnly,+ ]);++ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);+ const { themeColor } = useMantineTheme().fn;++ const rawSeries = useMemo(() => {+ const labeled = labelMapper+ ? mapBreakoutDimension(data, labelMapper)+ : data;+ return toCountBreakoutRawSeries(labeled, jsQuery, {+ display,+ maxCategories,+ otherLabel: t`Other`,+ getColor: themeColor,+ });+ }, [data, jsQuery, labelMapper, display, maxCategories, themeColor]);++ return (+ <BreakoutChartCard+ title={title}+ rawSeries={rawSeries}+ isFetching={isFetching}+ display={display}+ h={h}+ otherLabel={t`Other`}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallerLivenessTable.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallerLivenessTable.tsxnew file mode 100644index 00000000000..71b6180a6d4--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallerLivenessTable.tsx@@ -0,0 +1,157 @@+import { useMemo } from "react";+import { t } from "ttag";++import { Skeleton } from "metabase/ui";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";+import type { DatasetQuery } from "metabase-types/api";++import { BreakoutChartCard } from "../../metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";+import { useAdhocBreakoutQuery } from "../../metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { CliFilters } from "../query-utils";+import { buildCallerLivenessQuery } from "../query-utils";++const TABLE_HEIGHT = 500;++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++type Props = DataSources &+ CliFilters & {+ title: string;+ h?: number;+ };++type InnerProps = CliFilters & {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+ title: string;+ h: number;+};++/**+ * Wrap the caller-liveness result (one row per caller: last-seen timestamp + call count) as a+ * single-card table rawSeries. The result has one breakout column (the caller/user) and two+ * aggregations in build order — `max(created_at)` then `count` — which we relabel "User",+ * "Last seen", and "Calls". Returns null before the first result resolves.+ */+export function buildLivenessRawSeries(+ data: ReturnType<typeof useAdhocBreakoutQuery>["data"],+ jsQuery: DatasetQuery | null,+) {+ if (!data?.data || !jsQuery) {+ return null;+ }+ const { cols } = data.data;+ const dimensionCol = cols.find((col) => col.source === "breakout");+ const [lastSeenCol, callsCol] = cols.filter(+ (col) => col.source === "aggregation",+ );+ if (!dimensionCol || !lastSeenCol || !callsCol) {+ return null;+ }++ // Relabel the surfaced columns; row data is left untouched so columns stay aligned.+ const titles: Record<string, string> = {+ [dimensionCol.name]: t`User`,+ [lastSeenCol.name]: t`Last seen`,+ [callsCol.name]: t`Calls`,+ };+ const renamedCols = cols.map((col) =>+ titles[col.name] ? { ...col, display_name: titles[col.name] } : col,+ );++ return [+ {+ card: {+ display: "table",+ dataset_query: jsQuery,+ visualization_settings: {+ "table.columns": [+ { name: dimensionCol.name, enabled: true },+ { name: lastSeenCol.name, enabled: true },+ { name: callsCol.name, enabled: true },+ ],+ },+ },+ data: { ...data.data, cols: renamedCols },+ },+ ];+}++/**+ * Caller-liveness table — last-seen timestamp and call count per caller (user), so an admin can+ * spot who's still active and who's gone quiet. Renders a skeleton until the audit metadata is+ * loaded, then delegates to the inner component.+ */+export function CliCallerLivenessTable({+ provider,+ table,+ groupMembersTable,+ h = TABLE_HEIGHT,+ ...rest+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <CliCallerLivenessTableInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ h={h}+ {...rest}+ />+ );+}++function CliCallerLivenessTableInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ title,+ h,+}: InnerProps) {+ const query = useMemo(+ () =>+ buildCallerLivenessQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ }),+ [provider, table, groupMembersTable, dateFilter, userId, groupId, tenantId],+ );++ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);++ const rawSeries = useMemo(+ () => buildLivenessRawSeries(data, jsQuery),+ [data, jsQuery],+ );++ return (+ <BreakoutChartCard+ title={title}+ rawSeries={rawSeries}+ isFetching={isFetching}+ display="table"+ h={h}+ otherLabel={t`Other`}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallsTimelineChart.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallsTimelineChart.tsxnew file mode 100644index 00000000000..97bfe6260ab--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliCallsTimelineChart.tsx@@ -0,0 +1,130 @@+import { useMemo } from "react";+import { t } from "ttag";++import { Skeleton } from "metabase/ui";+import type {+ CardMetadata,+ MetadataProvider,+ Query,+ TableMetadata,+} from "metabase-lib";++import { BreakoutChartCard } from "../../metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";+import { useAdhocBreakoutQuery } from "../../metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { CliFilters } from "../query-utils";+import { buildCallsByDayByClientQuery } from "../query-utils";+import { toSeriesByBreakoutRawSeries } from "../raw-series";++const CHART_HEIGHT = 320;++type DataSources = {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+};++type BuildQueryFn = (opts: CliFilters & DataSources) => Query;++type Props = CliFilters & {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+ title: string;+ /** Two-breakout (day × series) query builder. Defaults to the day×client breakdown. */+ buildQuery?: BuildQueryFn;+ h?: number;+};++type InnerProps = CliFilters &+ DataSources & {+ title: string;+ buildQuery: BuildQueryFn;+ h: number;+ };++/**+ * Multi-series line chart of calls per day (one line per series — client or status). Renders a+ * skeleton until the audit metadata is loaded, then delegates to the inner component.+ */+export function CliCallsTimelineChart({+ provider,+ table,+ groupMembersTable,+ title,+ buildQuery = buildCallsByDayByClientQuery,+ h = CHART_HEIGHT,+ ...filters+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <CliCallsTimelineChartInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ title={title}+ buildQuery={buildQuery}+ h={h}+ {...filters}+ />+ );+}++/**+ * Loaded variant of {@link CliCallsTimelineChart}: builds the day×series query, runs it, and+ * renders it as a multi-series line chart through the shared chart card.+ */+function CliCallsTimelineChartInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ title,+ buildQuery,+ h,+}: InnerProps) {+ const query = useMemo(+ () =>+ buildQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ }),+ [+ buildQuery,+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ ],+ );++ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);++ const rawSeries = useMemo(+ () => toSeriesByBreakoutRawSeries(data, jsQuery),+ [data, jsQuery],+ );++ return (+ <BreakoutChartCard+ title={title}+ rawSeries={rawSeries}+ isFetching={isFetching}+ display="line"+ h={h}+ otherLabel={t`Other`}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.module.css b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.module.cssnew file mode 100644index 00000000000..900621381e2--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.module.css@@ -0,0 +1,8 @@+/* Call rows can hold long values (operations, ids, error text); keep them on one line so the+ body scrolls horizontally rather than wrapping into tall, hard-to-scan rows. */+.table thead th,+.table thead th *,+.table td,+.table th {+ white-space: nowrap;+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.tsxnew file mode 100644index 00000000000..fb3c70be767--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.tsx@@ -0,0 +1,269 @@+import { type ReactNode, useMemo, useRef } from "react";+import { t } from "ttag";++import {+ AdminDataTable,+ type AdminDataTableColumn,+} from "metabase/admin/components/AdminDataTable";+import { DateTime } from "metabase/common/components/DateTime";+import { EMPTY_CELL_PLACEHOLDER } from "metabase/utils/constants";+import { formatNumber } from "metabase/utils/formatting";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";+import type { RowValue, RowValues, SortingOptions } from "metabase-types/api";++import { useCliEventsQuery } from "../hooks/useCliEventsQuery";+import type { CliEventSortColumn, CliFilters } from "../query-utils";+import { buildEventsQuery } from "../query-utils";++import S from "./CliEventsTable.module.css";++export const EVENTS_PAGE_SIZE = 25;++type EventColumn = {+ /** View column name, matched case-insensitively against the result columns. */+ key: string;+ title: string;+ /** Present when the column can be sorted server-side. */+ sort?: CliEventSortColumn;+ align?: "right";+ render?: (value: RowValue) => ReactNode;+};++/**+ * The curated columns surfaced in the events table, in display order. Only these are ever+ * rendered — every other view column (raw ids, client_name, …) stays hidden by construction, so+ * nothing sensitive can leak. `tenant_name` shows only when tenants are enabled; `ip_address` /+ * `error_message` only when PII retention is on (they're null otherwise).+ */+export function eventColumns(+ hasTenants: boolean,+ hasPii: boolean,+): EventColumn[] {+ const columns: (EventColumn | false)[] = [+ { key: "call_id", title: t`ID` },+ {+ key: "created_at",+ title: t`Created at`,+ sort: "created_at",+ render: (value) =>+ value == null ? (+ EMPTY_CELL_PLACEHOLDER+ ) : (+ <DateTime value={String(value)} />+ ),+ },+ { key: "operation", title: t`Operation`, sort: "operation" },+ {+ key: "client_display_name",+ title: t`Client`,+ sort: "client_display_name",+ },+ { key: "user_display_name", title: t`User`, sort: "user_display_name" },+ hasTenants && { key: "tenant_name", title: t`Tenant` },+ hasPii && { key: "ip_address", title: t`IP address` },+ { key: "status", title: t`Status`, sort: "status" },+ {+ key: "duration_ms",+ title: t`Duration (ms)`,+ sort: "duration_ms",+ align: "right",+ render: (value) =>+ value == null ? EMPTY_CELL_PLACEHOLDER : formatNumber(Number(value)),+ },+ hasPii && { key: "error_message", title: t`Error message` },+ ];+ return columns.filter((column): column is EventColumn => column !== false);+}++function renderCell(column: EventColumn, value: RowValue): ReactNode {+ if (column.render) {+ return column.render(value);+ }+ return value == null || value === "" ? EMPTY_CELL_PLACEHOLDER : String(value);+}++type PaginationProps = {+ /** Current page, 0-indexed. */+ page: number;+ /** Total number of calls matching the filters (across all pages). */+ total: number;+ onPageChange: (page: number) => void;+};++type SortProps = {+ sortingOptions: SortingOptions<CliEventSortColumn>;+ onSortingOptionsChange: (+ sortingOptions: SortingOptions<CliEventSortColumn>,+ ) => void;+};++type Nullable<T> = { [K in keyof T]: T[K] | null };++// The audit metadata sources the inner table needs, all resolved.+type MetadataSources = {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+};++type BaseProps = CliFilters &+ PaginationProps &+ SortProps & {+ hasTenants: boolean;+ hasPii: boolean;+ };++// Sources are still loading in the outer props (hence nullable); the inner component only renders+// once they're resolved, so it takes them non-null.+type Props = BaseProps & Nullable<MetadataSources>;+type InnerProps = BaseProps & MetadataSources;++/**+ * Retain the last non-nullish value so a component keeps rendering the previous result while the+ * next one loads. RTK query hooks return `undefined` data mid-fetch; without this a consumer would+ * blank out on every refetch.+ */+function useRetainedValue<T>(value: T | undefined): T | undefined {+ const ref = useRef(value);+ if (value != null) {+ ref.current = value;+ }+ return value ?? ref.current;+}++/**+ * Row-level events table for the Events tab. Renders nothing until the audit metadata is+ * loaded, then delegates to the inner component.+ */+export function CliEventsTable({+ provider,+ table,+ groupMembersTable,+ ...rest+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return null;+ }+ return (+ <CliEventsTableInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ {...rest}+ />+ );+}++/**+ * Loaded variant of {@link CliEventsTable}: builds the paginated, sorted row-level query, runs it,+ * and renders the Agent API calls as a sortable table with pagination controls.+ */+function CliEventsTableInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ hasTenants,+ hasPii,+ page,+ total,+ onPageChange,+ sortingOptions,+ onSortingOptionsChange,+}: InnerProps) {+ const query = useMemo(+ () =>+ buildEventsQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ sortColumn: sortingOptions.sort_column,+ sortDirection: sortingOptions.sort_direction,+ }),+ [+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ sortingOptions,+ ],+ );++ const { data: latestData, isFetching } = useCliEventsQuery(+ query,+ page,+ EVENTS_PAGE_SIZE,+ );+ // Retain the previous page while the next one loads, so the table doesn't blank out on every+ // page or sort change; we overlay a spinner on the retained rows instead. From here on `data` is+ // simply the warehouse result — the retention is an implementation detail of the hook.+ const data = useRetainedValue(latestData);++ const columns = useMemo(+ () => eventColumns(hasTenants, hasPii),+ [hasTenants, hasPii],+ );+ const rows: RowValues[] = data?.data?.rows ?? [];+ // The result columns (`data.data.cols`) are the full, warehouse-ordered set the query returns —+ // not the curated `columns` we render. So we can't reuse the `columns` index; we map each curated+ // column to its position in the result by name. Names are upper- or lower-cased depending on the+ // warehouse (the audit DB is H2, which upper-cases; Postgres lower-cases), so match+ // case-insensitively.+ const columnIndex = useMemo(() => {+ const cols = data?.data?.cols ?? [];+ return new Map(cols.map((col, index) => [col.name.toLowerCase(), index]));+ }, [data]);++ // Adapt the curated `columns` to the generic table: each render pulls its value out of the+ // warehouse-ordered result row by the column's position in `columnIndex`.+ const dataColumns = useMemo<+ AdminDataTableColumn<RowValues, CliEventSortColumn>[]+ >(+ () =>+ columns.map((column) => ({+ key: column.key,+ title: column.title,+ sortKey: column.sort,+ align: column.align,+ render: (row) => {+ const index = columnIndex.get(column.key);+ const value = index != null ? row[index] : null;+ return renderCell(column, value);+ },+ })),+ [columns, columnIndex],+ );++ return (+ <AdminDataTable+ columns={dataColumns}+ rows={rows}+ sorting={{ sortingOptions, onSortingOptionsChange }}+ pagination={{+ page,+ pageSize: EVENTS_PAGE_SIZE,+ total,+ onPageChange,+ showTotal: true,+ }}+ loading={isFetching}+ emptyText={t`No calls found`}+ maxBodyHeight="calc(100vh - 23rem)"+ tableClassName={S.table}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.unit.spec.tsxnew file mode 100644index 00000000000..3b81c40e77e--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/components/CliEventsTable.unit.spec.tsx@@ -0,0 +1,58 @@+import { eventColumns } from "./CliEventsTable";++const keys = (hasTenants: boolean, hasPii: boolean) =>+ eventColumns(hasTenants, hasPii).map((column) => column.key);++describe("eventColumns", () => {+ it("surfaces the curated columns in display order (ID first, Tenant + IP after User)", () => {+ expect(keys(true, true)).toEqual([+ "call_id",+ "created_at",+ "operation",+ "client_display_name",+ "user_display_name",+ "tenant_name",+ "ip_address",+ "status",+ "duration_ms",+ "error_message",+ ]);+ });++ it("includes the Tenant column only when tenants are enabled", () => {+ expect(keys(true, true)).toContain("tenant_name");+ expect(keys(false, true)).not.toContain("tenant_name");+ });++ it("includes the PII columns (IP + error message) only when retention is on", () => {+ expect(keys(true, true)).toEqual(+ expect.arrayContaining(["ip_address", "error_message"]),+ );+ const withoutPii = keys(true, false);+ expect(withoutPii).not.toContain("ip_address");+ expect(withoutPii).not.toContain("error_message");+ });++ it("never surfaces raw/sensitive columns (client_name, raw ids, group_name)", () => {+ const all = keys(true, true);+ expect(all).not.toContain("client_name");+ expect(all).not.toContain("user_id");+ expect(all).not.toContain("tenant_id");+ expect(all).not.toContain("group_name");+ });++ it("marks the expected columns sortable and leaves the rest static", () => {+ const columns = eventColumns(true, true);+ const sortable = columns.filter((c) => c.sort).map((c) => c.key);+ expect(sortable).toEqual([+ "created_at",+ "operation",+ "client_display_name",+ "user_display_name",+ "status",+ "duration_ms",+ ]);+ // the PK and free-text columns are not sortable+ expect(columns.find((c) => c.key === "call_id")?.sort).toBeUndefined();+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/constants.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/constants.tsnew file mode 100644index 00000000000..6426b5518ce--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/constants.ts@@ -0,0 +1,7 @@+export {+ AUDIT_DB_ID,+ VIEW_GROUP_MEMBERS,+} from "../metabot-analytics/constants";++// View name in the audit database for Agent API (CLI + other clients) call analytics.+export const VIEW_AGENT_API_CALLS = "v_agent_api_calls";diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliEventsQuery.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliEventsQuery.tsnew file mode 100644index 00000000000..e6a6f21c757--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliEventsQuery.ts@@ -0,0 +1,34 @@+import { useMemo } from "react";++import { skipToken, useGetAdhocQueryQuery } from "metabase/api";+import type { Query } from "metabase-lib";+import * as Lib from "metabase-lib";+import type { Dataset } from "metabase-types/api";++import { paginateEventsQuery } from "../query-utils";++type EventsPageResult = {+ data: Dataset | undefined;+ isFetching: boolean;+};++/**+ * Run the row-level events query for one page. Applies the MBQL `:page` clause (via+ * {@link paginateEventsQuery}) before execution so the backend returns only the requested page.+ * `page` is 0-indexed.+ */+export function useCliEventsQuery(+ query: Query | null,+ page: number,+ pageSize: number,+): EventsPageResult {+ const jsQuery = useMemo(+ () =>+ query ? Lib.toJsQuery(paginateEventsQuery(query, page, pageSize)) : null,+ [query, page, pageSize],+ );++ const { data, isFetching } = useGetAdhocQueryQuery(jsQuery ?? skipToken);++ return { data, isFetching };+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliHasData.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliHasData.tsnew file mode 100644index 00000000000..2b8d1fca06c--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/hooks/useCliHasData.ts@@ -0,0 +1,90 @@+import { useMemo, useRef } from "react";++import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";++import { useAdhocBreakoutQuery } from "../../metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { CliFilters } from "../query-utils";+import { buildTotalCountQuery } from "../query-utils";++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++type Result = {+ /** First load, before the count has ever resolved — show a loader, never the empty state. */+ isInitialLoading: boolean;+ /** A subsequent load triggered by a filter change — let the charts show their own skeletons. */+ isRefetching: boolean;+ /** Whether the current (resolved) filters match any calls. */+ hasData: boolean;+ /** Total number of calls matching the current filters — drives the events pagination. */+ count: number;+};++/**+ * Runs a single count query over the filtered view to drive the page's load/empty/data states.+ * Distinguishes the initial load (loader) from a filter-change refetch (skeletons) so the page+ * never flashes the empty state before the first result has resolved.+ */+export function useCliHasData({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ errorsOnly = false,+}: DataSources & CliFilters & { errorsOnly?: boolean }): Result {+ const query = useMemo(+ () =>+ provider && table && groupMembersTable+ ? buildTotalCountQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ errorsOnly,+ })+ : null,+ [+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ errorsOnly,+ ],+ );++ const { data, isFetching } = useAdhocBreakoutQuery(query);++ // Latch once the first count resolves; from then on a fetch is a refetch, not initial load.+ const hasLoadedOnce = useRef(false);+ const resolved = query != null && !isFetching && data != null;+ if (resolved) {+ hasLoadedOnce.current = true;+ }++ // The query is a single count aggregation with no breakout, so the result is exactly one row+ // with one column — the scalar total. `rows[0][0]` is that count.+ const count = Number(data?.data?.rows?.[0]?.[0] ?? 0);++ return {+ isInitialLoading: !hasLoadedOnce.current,+ isRefetching: hasLoadedOnce.current && isFetching,+ hasData: count > 0,+ count,+ };+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/index.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/index.tsnew file mode 100644index 00000000000..41b271f8ba5--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/index.ts@@ -0,0 +1 @@+export { CliAnalyticsPage } from "./components/CliAnalyticsPage";diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/nav.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/nav.tsxnew file mode 100644index 00000000000..b7e4f848fde--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/nav.tsx@@ -0,0 +1,17 @@+import { t } from "ttag";++import { AdminNavItem } from "metabase/admin/components/AdminNav";++/**+ * The CLI analytics nav item, rendered as a child of the admin "Usage auditing" group+ * (`metabot-analytics/nav`). Lives in EE-only code, so it's absent on OSS. Unlike MCP there's no+ * enabled/disabled flag — the CLI page is always accessible whenever `audit_app` is present.+ */+export function CliAnalyticsNavItem() {+ return (+ <AdminNavItem+ label={t`CLI analytics`}+ path="/admin/metabot/usage-auditing/cli"+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/query-utils.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/query-utils.tsnew file mode 100644index 00000000000..870cf2291f2--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/query-utils.ts@@ -0,0 +1,407 @@+import type { DateFilterValue } from "metabase/querying/common/types";+import type {+ CardMetadata,+ MetadataProvider,+ Query,+ TableMetadata,+} from "metabase-lib";+import * as Lib from "metabase-lib";+import type { SortDirection } from "metabase-types/api";++import {+ applyDateFilter,+ applyIdFilter,+ breakoutByColumn,+ findColumn,+ joinGroupMembers,+} from "../metabot-analytics/components/ConversationStatsPage/query-utils";++export type CliFilters = {+ dateFilter: DateFilterValue;+ userId?: number;+ groupId?: number;+ tenantId?: number;+};++type CliDataSources = {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+};++// Name of the count aggregation column produced by `Lib.aggregateByCount`.+const COUNT_COLUMN = "count";++/**+ * Apply the shared user/group/tenant filters to a query. The group filter joins the audit+ * `v_group_members` view and filters by `group_id` (a user can belong to several groups); the+ * user and tenant filters are plain `user_id` / `tenant_id` equalities. Each no-ops when its id+ * is unset.+ */+function applyScopeFilters(+ query: Query,+ {+ userId,+ groupId,+ tenantId,+ }: Pick<CliFilters, "userId" | "groupId" | "tenantId">,+ groupMembersTable: TableMetadata | CardMetadata,+): Query {+ query = applyIdFilter(query, "user_id", userId);+ query = applyIdFilter(query, "tenant_id", tenantId);+ query = groupId != null ? joinGroupMembers(query, groupMembersTable) : query;+ query = groupId != null ? applyIdFilter(query, "group_id", groupId) : query;+ return query;+}++/**+ * The shared prelude every builder starts from: the view query with the date + scope+ * (user/group/tenant) filters applied. Centralizing it keeps the filter handling — notably+ * `tenantId` — in one place so a builder can't silently drop a filter.+ */+function buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+}: CliFilters & CliDataSources): Query {+ let query = Lib.queryFromTableOrCardMetadata(provider, table);+ query = applyDateFilter(query, dateFilter);+ query = applyScopeFilters(+ query,+ { userId, groupId, tenantId },+ groupMembersTable,+ );+ return query;+}++/** Order an aggregated query by the count column descending (highest counts first). */+function orderByCountDesc(query: Query): Query {+ const countCol = findColumn(query, COUNT_COLUMN, Lib.orderableColumns);+ return countCol ? Lib.orderBy(query, 0, countCol, "desc") : query;+}++/** Filter a query to rows whose `status` equals `status` (e.g. "error"). No-op if absent. */+function applyStatusFilter(query: Query, status: string): Query {+ const col = findColumn(query, "status", Lib.filterableColumns);+ if (!col) {+ return query;+ }+ return Lib.filter(+ query,+ 0,+ Lib.stringFilterClause({+ operator: "=",+ column: col,+ values: [status],+ options: {},+ }),+ );+}++/**+ * Add a `max(columnName)` aggregation to a query. Mirrors `addSumAggregation` from the shared+ * metabot query-utils but for the "max" operator — used for the "last seen" liveness column.+ * No-ops when the operator or column is unavailable.+ */+function addMaxAggregation(query: Query, columnName: string): Query {+ const operators = Lib.availableAggregationOperators(query, 0);+ const maxOp = operators.find((op) => {+ const info = Lib.displayInfo(query, 0, op);+ return info.shortName === "max";+ });+ if (!maxOp) {+ return query;+ }++ const columns = Lib.aggregationOperatorColumns(maxOp);+ const lowerName = columnName.toLowerCase();+ const col = columns.find((c) => {+ const info = Lib.displayInfo(query, 0, c);+ return info.name?.toLowerCase() === lowerName;+ });+ if (!col) {+ return query;+ }++ const clause = Lib.aggregationClause(maxOp, col);+ return Lib.aggregate(query, 0, clause);+}++type CountBreakoutQueryOpts = CliFilters &+ CliDataSources & {+ breakoutColumn: string;+ };++/**+ * Build a "count of calls grouped by `breakoutColumn`" query (filtered + ordered by count desc).+ * Used by the single-breakout charts — calls by client, by operation, by user, etc.+ */+export function buildCountBreakoutQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ breakoutColumn,+}: CountBreakoutQueryOpts): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByColumn(query, breakoutColumn);+ query = orderByCountDesc(query);+ return query;+}++/** Add a `created_at` breakout bucketed by day (falls back to the raw column if the day bucket is unavailable). */+function breakoutByCreatedAtDay(query: Query): Query {+ const col = findColumn(query, "created_at", Lib.breakoutableColumns);+ if (!col) {+ return query;+ }+ const dayBucket = Lib.availableTemporalBuckets(query, 0, col).find(+ (bucket) => Lib.displayInfo(query, 0, bucket).shortName === "day",+ );+ const bucketed = dayBucket ? Lib.withTemporalBucket(col, dayBucket) : col;+ return Lib.breakout(query, 0, bucketed);+}++/**+ * Build a "calls per day, broken out by client" query — a multi-series time series. The day+ * breakout is added first so it becomes the x-axis dimension and `client_display_name` becomes+ * the series (one line per client).+ */+export function buildCallsByDayByClientQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+}: CliFilters & CliDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByCreatedAtDay(query);+ query = breakoutByColumn(query, "client_display_name");+ return query;+}++/**+ * Build a "calls per day, broken out by status" query — a multi-series time series (one line+ * per status) that surfaces the error-vs-success trend over time.+ */+export function buildCallsByDayByStatusQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+}: CliFilters & CliDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByCreatedAtDay(query);+ query = breakoutByColumn(query, "status");+ return query;+}++/**+ * Build the caller-liveness query: the filtered view grouped by the caller (`user_display_name`)+ * with two aggregations — `max(created_at)` (the last-seen timestamp, surfaced as "Last seen")+ * and the row count (surfaced as "Calls"). The max aggregation is added first so it precedes the+ * count in the result columns. Ordered by count desc so the busiest callers come first. Keyed on+ * the caller (the user), not the client — the tech doc's liveness table is "last-seen per caller",+ * so an admin can spot which users are still active and which have gone quiet.+ */+export function buildCallerLivenessQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+}: CliFilters & CliDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = addMaxAggregation(query, "created_at");+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByColumn(query, "user_display_name");+ query = orderByCountDesc(query);+ return query;+}++type ErrorBreakoutQueryOpts = CliFilters &+ CliDataSources & {+ breakoutColumn: string;+ };++/**+ * Build a "count of failed calls grouped by `breakoutColumn`" query (filtered to `status = error`,+ * ordered by count desc). Used by the error breakdown charts — e.g. by operation.+ */+export function buildErrorBreakoutQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ breakoutColumn,+}: ErrorBreakoutQueryOpts): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = applyStatusFilter(query, "error");+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByColumn(query, breakoutColumn);+ query = orderByCountDesc(query);+ return query;+}++/**+ * Build a single-number count over the filtered view, used to decide whether the page has any+ * data to show (so we can render one empty state instead of a grid of empty charts). When+ * `errorsOnly` is set, counts only failed calls (drives the errors-section visibility).+ */+export function buildTotalCountQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ errorsOnly = false,+}: CliFilters & CliDataSources & { errorsOnly?: boolean }): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });+ query = errorsOnly ? applyStatusFilter(query, "error") : query;+ query = Lib.aggregateByCount(query, 0);+ return query;+}++export const CLI_EVENT_SORT_COLUMNS = [+ "created_at",+ "operation",+ "client_display_name",+ "user_display_name",+ "status",+ "duration_ms",+] as const;++export type CliEventSortColumn = (typeof CLI_EVENT_SORT_COLUMNS)[number];++/** Append an order-by on `columnName` in `direction` if it's orderable. No-op if absent. */+function orderByColumn(+ query: Query,+ columnName: string,+ direction: "asc" | "desc",+): Query {+ const col = findColumn(query, columnName, Lib.orderableColumns);+ return col ? Lib.orderBy(query, 0, col, direction) : query;+}++type EventsQueryOpts = CliFilters &+ CliDataSources & {+ sortColumn?: CliEventSortColumn;+ sortDirection?: SortDirection;+ };++/**+ * Build the row-level events query for the Events tab: the filtered view with no aggregation,+ * ordered by the chosen sort column (default `created_at` descending), then by the `call_id`+ * primary key as a tiebreaker. The tiebreaker makes the sort a total order — without it,+ * pagination can skip or duplicate rows across page boundaries when the sort column has ties (the+ * DB is free to order ties differently between requests). Pagination is applied separately via+ * {@link paginateEventsQuery}.+ */+export function buildEventsQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ sortColumn = "created_at",+ sortDirection = "desc",+}: EventsQueryOpts): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ userId,+ groupId,+ tenantId,+ });++ query = orderByColumn(query, sortColumn, sortDirection);+ query = orderByColumn(query, "call_id", "desc");++ return query;+}++/**+ * Restrict the events query to a single page via the MBQL `:page` clause. `page` is 0-indexed+ * here; metabase-lib's `:page` is 1-indexed, so we add 1.+ */+export function paginateEventsQuery(+ query: Query,+ page: number,+ pageSize: number,+): Query {+ return Lib.withPage(query, 0, { page: page + 1, items: pageSize });+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.tsnew file mode 100644index 00000000000..3bea84b2b6b--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.ts@@ -0,0 +1,145 @@+import type { ColorName } from "metabase/ui/colors/types";+import type { DatasetQuery, VisualizationDisplay } from "metabase-types/api";++type GetColor = (name: ColorName) => string;++type RawDataCol = { source?: string; name?: string };+type RawData = { cols: RawDataCol[]; rows: unknown[][] };+type AdhocResponse = { data?: RawData } | undefined;++type Opts = {+ display: VisualizationDisplay;+ maxCategories?: number;+ otherLabel: string;+ getColor: GetColor;+};++/**+ * Keep the top `max - 1` rows (already count-ordered) and fold the remaining long tail into a+ * single "Other" row whose metric is the summed overflow. Returns rows unchanged when there's+ * nothing to collapse.+ */+function collapseToTopN(+ rows: unknown[][],+ dimensionIndex: number,+ metricIndex: number,+ max: number | undefined,+ otherLabel: string,+ colCount: number,+): unknown[][] {+ const shouldCollapse =+ max != null && dimensionIndex >= 0 && metricIndex >= 0 && rows.length > max;+ if (!shouldCollapse) {+ return rows;+ }+ const keep = rows.slice(0, max - 1);+ const overflow = rows.slice(max - 1);+ const otherRow: unknown[] = new Array(colCount).fill(null);+ otherRow[dimensionIndex] = otherLabel;+ otherRow[metricIndex] = overflow.reduce(+ (sum, row) => sum + (Number(row[metricIndex]) || 0),+ 0,+ );+ return [...keep, otherRow];+}++/**+ * Build a single-breakout rawSeries (one dimension + the count metric) for `bar`/`row`/`pie`+ * displays. Long tails are collapsed into a single "Other" category.+ */+export function toCountBreakoutRawSeries(+ response: AdhocResponse,+ jsQuery: DatasetQuery | null,+ opts: Opts,+) {+ if (!response?.data || !jsQuery) {+ return null;+ }++ const { display, maxCategories, otherLabel, getColor } = opts;+ const cols = response.data.cols;+ const dimensionIndex = cols.findIndex((c) => c.source === "breakout");+ const metricIndex = cols.findIndex((c) => c.source === "aggregation");+ const dimensionName =+ dimensionIndex >= 0 ? cols[dimensionIndex].name : undefined;+ const countColumnName =+ metricIndex >= 0 ? (cols[metricIndex].name ?? "count") : "count";++ const visualizationSettings =+ display === "pie"+ ? {+ "pie.dimension": dimensionName,+ "pie.metric": countColumnName,+ }+ : {+ "graph.x_axis.title_text": "",+ "graph.y_axis.title_text": "",+ ...(display === "bar" && {+ "graph.x_axis.axis_enabled": "compact" as const,+ }),+ series_settings: {+ [countColumnName]: { color: getColor("accent0") },+ },+ };++ return [+ {+ card: {+ display,+ dataset_query: jsQuery,+ visualization_settings: visualizationSettings,+ },+ data: {+ ...response.data,+ rows: collapseToTopN(+ response.data.rows,+ dimensionIndex,+ metricIndex,+ maxCategories,+ otherLabel,+ cols.length,+ ),+ },+ },+ ];+}++/**+ * Build a multi-series line rawSeries from a two-breakout count query: the first breakout is+ * the x-axis dimension and the second becomes the series (e.g. day x client).+ */+export function toSeriesByBreakoutRawSeries(+ response: AdhocResponse,+ jsQuery: DatasetQuery | null,+) {+ if (!response?.data || !jsQuery) {+ return null;+ }++ const breakoutCols = response.data.cols.filter(+ (col) => col.source === "breakout",+ );+ const metricCol = response.data.cols.find(+ (col) => col.source === "aggregation",+ );+ const [dimensionCol, seriesCol] = breakoutCols;+ if (!dimensionCol?.name || !seriesCol?.name || !metricCol?.name) {+ return null;+ }++ return [+ {+ card: {+ display: "line" as const,+ dataset_query: jsQuery,+ visualization_settings: {+ "graph.dimensions": [dimensionCol.name, seriesCol.name],+ "graph.metrics": [metricCol.name],+ "graph.x_axis.title_text": "",+ "graph.y_axis.title_text": "",+ },+ },+ data: response.data,+ },+ ];+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.unit.spec.tsnew file mode 100644index 00000000000..12f0326de41--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/raw-series.unit.spec.ts@@ -0,0 +1,78 @@+import type { DatasetQuery } from "metabase-types/api";++import { toCountBreakoutRawSeries } from "./raw-series";++// Unjustified type cast. FIXME+const jsQuery = { database: 1, type: "query", query: {} } as DatasetQuery;++const opts = {+ display: "row" as const,+ otherLabel: "Other",+ getColor: () => "#509EE3",+};++/** A single-breakout count response: one `breakout` dimension col + one `aggregation` metric col. */+const response = (rows: unknown[][]) => ({+ data: {+ cols: [+ { source: "breakout", name: "client_display_name" },+ { source: "aggregation", name: "count" },+ ],+ rows,+ },+});++const rowsOf = (series: ReturnType<typeof toCountBreakoutRawSeries>) =>+ series?.[0].data.rows;++describe("toCountBreakoutRawSeries collapse behavior", () => {+ it("folds the long tail into a single summed 'Other' row when rows exceed maxCategories", () => {+ const series = toCountBreakoutRawSeries(+ response([+ ["A", 10],+ ["B", 7],+ ["C", 5],+ ["D", 3],+ ["E", 1],+ ]),+ jsQuery,+ { ...opts, maxCategories: 3 },+ );++ // keep top (max - 1) = 2, fold the remaining 3 into "Other" summing 5 + 3 + 1 = 9+ expect(rowsOf(series)).toEqual([+ ["A", 10],+ ["B", 7],+ ["Other", 9],+ ]);+ });++ it("leaves rows untouched when the count is within maxCategories", () => {+ const rows = [+ ["A", 10],+ ["B", 7],+ ];+ const series = toCountBreakoutRawSeries(response(rows), jsQuery, {+ ...opts,+ maxCategories: 3,+ });+ expect(rowsOf(series)).toEqual(rows);+ });++ it("leaves rows untouched when maxCategories is unset", () => {+ const rows = [+ ["A", 10],+ ["B", 7],+ ["C", 5],+ ];+ const series = toCountBreakoutRawSeries(response(rows), jsQuery, opts);+ expect(rowsOf(series)).toEqual(rows);+ });++ it("returns null without data or query", () => {+ expect(toCountBreakoutRawSeries(undefined, jsQuery, opts)).toBeNull();+ expect(+ toCountBreakoutRawSeries(response([["A", 1]]), null, opts),+ ).toBeNull();+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/routes.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/routes.tsxnew file mode 100644index 00000000000..47e40abd372--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/routes.tsx@@ -0,0 +1,21 @@+import { Route, withRouteProps } from "metabase/router";++import { CliAnalyticsPage } from "./components/CliAnalyticsPage";++const RoutedCliAnalyticsPage = withRouteProps(CliAnalyticsPage);++/**+ * The `/admin/metabot/usage-auditing/cli` route — nested under the `usage-auditing` namespace so+ * the admin nav opens the "Usage auditing" folder (where the link lives) rather than the Metabot+ * group. Wired into `PLUGIN_AUDIT` and only registered on EE instances with the `audit_app`+ * feature, so navigating there renders nothing on OSS.+ */+export function getCliAnalyticsRoutes() {+ return (+ <Route+ key="cli-analytics"+ path="usage-auditing/cli"+ element={<RoutedCliAnalyticsPage />}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/url-state.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/url-state.tsnew file mode 100644index 00000000000..247873ecf77--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/cli-analytics/url-state.ts@@ -0,0 +1,74 @@+import {+ type QueryParam,+ type UrlStateConfig,+ getFirstParamValue,+} from "metabase/common/hooks/use-url-state";+import type { SortDirection } from "metabase-types/api";++import {+ type FilterUrlState,+ filterUrlStateConfig,+ mergeUrlStateConfig,+} from "../metabot-analytics/components/ConversationFilters/url-state";++import { CLI_EVENT_SORT_COLUMNS, type CliEventSortColumn } from "./query-utils";++export type CliTab = "charts" | "events";++type CliPageUrlState = {+ tab: CliTab;+ /** Current page of the row-level events table, 0-indexed. */+ page: number;+ sort_column: CliEventSortColumn;+ sort_direction: SortDirection;+};++export type CliUrlState = FilterUrlState & CliPageUrlState;++const DEFAULT_TAB: CliTab = "charts";+const DEFAULT_SORT_COLUMN: CliEventSortColumn = "created_at";+const DEFAULT_SORT_DIRECTION: SortDirection = "desc";++/** Parse the `tab` query param, defaulting to the charts tab for any unrecognized value. */+function parseTab(param: QueryParam): CliTab {+ return getFirstParamValue(param) === "events" ? "events" : DEFAULT_TAB;+}++/** Parse the `page` query param, defaulting to 0 for anything missing or invalid. */+function parsePage(param: QueryParam): number {+ const parsed = parseInt(getFirstParamValue(param) || "0", 10);+ return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;+}++function parseSortColumn(param: QueryParam): CliEventSortColumn {+ const value = getFirstParamValue(param);+ return (+ CLI_EVENT_SORT_COLUMNS.find((col) => col === value) ?? DEFAULT_SORT_COLUMN+ );+}++function parseSortDirection(param: QueryParam): SortDirection {+ const value = getFirstParamValue(param);+ // we don't want to use `value` directly because it may be an invalid sort direction+ // coming from URL params+ return value === "asc" || value === "desc" ? value : DEFAULT_SORT_DIRECTION;+}++const cliPageUrlStateConfig: UrlStateConfig<CliPageUrlState> = {+ parse: (query) => ({+ tab: parseTab(query.tab),+ page: parsePage(query.page),+ sort_column: parseSortColumn(query.sort_column),+ sort_direction: parseSortDirection(query.sort_direction),+ }),+ serialize: ({ tab, page, sort_column, sort_direction }) => ({+ tab: tab === DEFAULT_TAB ? undefined : tab,+ page: page === 0 ? undefined : String(page),+ sort_column: sort_column === DEFAULT_SORT_COLUMN ? undefined : sort_column,+ sort_direction:+ sort_direction === DEFAULT_SORT_DIRECTION ? undefined : sort_direction,+ }),+};++export const cliUrlStateConfig: UrlStateConfig<CliUrlState> =+ mergeUrlStateConfig(filterUrlStateConfig, cliPageUrlStateConfig);diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/index.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/index.tsxindex 3cdbe688dc9..12de0321cb7 100644--- a/enterprise/frontend/src/metabase-enterprise/audit_app/index.tsx+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/index.tsx@@ -11,6 +11,7 @@ import { isInternalUser } from "metabase/urls";import { hasPremiumFeature } from "metabase-enterprise/settings";import type { User } from "metabase-types/api";+import { getCliAnalyticsRoutes } from "./cli-analytics/routes";import { InsightsLink } from "./components/InsightsLink";import { InsightsMenuItem } from "./components/InsightsMenuItem";import { getMcpAnalyticsRoutes } from "./mcp-analytics/routes";@@ -49,6 +50,7 @@ export function initializePlugin() {PLUGIN_AUDIT.InsightsLink = InsightsLink;PLUGIN_AUDIT.InsightsMenuItem = InsightsMenuItem;PLUGIN_AUDIT.getMcpAnalyticsRoutes = getMcpAnalyticsRoutes;+ PLUGIN_AUDIT.getCliAnalyticsRoutes = getCliAnalyticsRoutes;// Nav is registered for audit_app and decides Metabot (ai_controls) vs MCP (audit_app)// children internally; only the routes split on ai_controls.PLUGIN_AUDIT.getMetabotAnalyticsNavItems = getMetabotAnalyticsNavItems;diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/mcp-analytics/components/McpAnalyticsPage.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/mcp-analytics/components/McpAnalyticsPage.unit.spec.tsxindex 3e5cc0fc90c..4f3bd047f81 100644--- a/enterprise/frontend/src/metabase-enterprise/audit_app/mcp-analytics/components/McpAnalyticsPage.unit.spec.tsx+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/mcp-analytics/components/McpAnalyticsPage.unit.spec.tsx@@ -200,6 +200,31 @@ function setup({ dataset }: { dataset?: Dataset } = {}) {);}+// pMBQL order-by clause: [direction, opts, ["field", opts, fieldId]]+type OrderByClause = [string, unknown, [string, unknown, number]];++type EventsMbqlStage = {+ page?: { page: number; items: number };+ "order-by"?: OrderByClause[];+};++/**+ * The first MBQL stage of every adhoc `dataset` request issued so far. The row-level events query+ * is the one that carries a `:page` clause on stage 0 (the chart queries don't), so tests filter+ * on `.page`. Non-string bodies are skipped.+ */+const eventsDatasetStages = (): EventsMbqlStage[] =>+ fetchMock.callHistory+ .calls("dataset")+ .map((call) => call.options?.body)+ .filter((body): body is string => typeof body === "string")+ .map((body) => {+ // JSON.parse is untyped (`any`); the request body is an MBQL query, so assert its shape.+ const query = JSON.parse(body) as { stages?: EventsMbqlStage[] };+ return query.stages?.[0];+ })+ .filter((stage): stage is EventsMbqlStage => stage != null);+describe("McpAnalyticsPage", () => {it("renders the header, filters, and charts tab", async () => {setup();@@ -253,16 +278,9 @@ describe("McpAnalyticsPage", () => {await userEvent.click(await screen.findByRole("button", { name: "Tool" }));await waitFor(() => {- const sortedAscending = fetchMock.callHistory- .calls("dataset")- .some((call) => {- const body = call.options?.body;- if (typeof body !== "string") {- return false;- }- const stage = JSON.parse(body).stages?.[0];- return stage?.page != null && stage["order-by"]?.[0]?.[0] === "asc";- });+ const sortedAscending = eventsDatasetStages().some(+ (stage) => stage.page != null && stage["order-by"]?.[0]?.[0] === "asc",+ );expect(sortedAscending).toBe(true);});});@@ -287,15 +305,9 @@ describe("McpAnalyticsPage", () => {// Advancing issues an adhoc dataset query for the second MBQL page (1-indexed).await waitFor(() => {- const requestedPage2 = fetchMock.callHistory- .calls("dataset")- .some((call) => {- const body = call.options?.body;- if (typeof body !== "string") {- return false;- }- return JSON.parse(body)?.stages?.[0]?.page?.page === 2;- });+ const requestedPage2 = eventsDatasetStages().some(+ (stage) => stage.page?.page === 2,+ );expect(requestedPage2).toBe(true);});});@@ -311,13 +323,7 @@ describe("McpAnalyticsPage", () => {// Dataset calls for the events query's second page (MBQL `:page` is 1-indexed, so UI page 1).const page2EventsCalls = () =>- fetchMock.callHistory.calls("dataset").filter((call) => {- const body = call.options?.body;- if (typeof body !== "string") {- return false;- }- return JSON.parse(body)?.stages?.[0]?.page?.page === 2;- });+ eventsDatasetStages().filter((stage) => stage.page?.page === 2);await userEvent.click(await screen.findByLabelText("Next page"));@@ -344,19 +350,10 @@ describe("McpAnalyticsPage", () => {// created_at followed by the tool_call_id (PK) tiebreaker, so pages can't skip/duplicate rows// on tied timestamps.await waitFor(() => {- const eventsStage = fetchMock.callHistory- .calls("dataset")- .map((call) => call.options?.body)- .filter((body): body is string => typeof body === "string")- .map((body) => JSON.parse(body).stages?.[0])- .find((stage) => stage?.page != null);- // pMBQL order-by clause: [direction, opts, ["field", opts, fieldId]]- const orderBy = eventsStage?.["order-by"] as [- string,- object,- [string, object, number],- ][];- expect(orderBy?.map((clause) => clause[2][2])).toEqual([+ const eventsStage = eventsDatasetStages().find(+ (stage) => stage.page != null,+ );+ expect(eventsStage?.["order-by"]?.map((clause) => clause[2][2])).toEqual([CREATED_AT_FIELD_ID,TOOL_CALL_ID_FIELD_ID,]);diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/nav.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/nav.tsxindex 5c0d635aebc..be34a6a2241 100644--- a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/nav.tsx+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/nav.tsx@@ -5,6 +5,7 @@ import { UpsellGem } from "metabase/common/components/upsells/components";import { useSetting } from "metabase/common/hooks";import { hasPremiumFeature } from "metabase-enterprise/settings";+import { CliAnalyticsNavItem } from "../cli-analytics/nav";import { McpAnalyticsNavItem } from "../mcp-analytics/nav";export function getMetabotAnalyticsNavItems() {@@ -56,6 +57,7 @@ function MetabotAnalyticsNavItems() {))}<McpAnalyticsNavItem mcpEnabled={mcpEnabled} />+ <CliAnalyticsNavItem /></AdminNavItem>);}diff --git a/frontend/src/metabase/admin/components/AdminDataTable/AdminDataTable.unit.spec.tsx b/frontend/src/metabase/admin/components/AdminDataTable/AdminDataTable.unit.spec.tsxindex 6fb35ddba29..6f5fb063e91 100644--- a/frontend/src/metabase/admin/components/AdminDataTable/AdminDataTable.unit.spec.tsx+++ b/frontend/src/metabase/admin/components/AdminDataTable/AdminDataTable.unit.spec.tsx@@ -135,7 +135,6 @@ describe("AdminDataTable", () => {setup({ rows: [], emptyText: "Nothing here" });expect(screen.getByText("Nothing here")).toBeInTheDocument();- expect(screen.queryByText("Alpha")).not.toBeInTheDocument();});it("keeps showing rows while refetching (overlay instead of blanking)", () => {diff --git a/frontend/src/metabase/admin/routes.tsx b/frontend/src/metabase/admin/routes.tsxindex aba827b2b63..f8fd586359e 100644--- a/frontend/src/metabase/admin/routes.tsx+++ b/frontend/src/metabase/admin/routes.tsx@@ -288,6 +288,7 @@ export const getRoutes = (>{PLUGIN_AUDIT.getAiAnalyticsRoutes()}{PLUGIN_AUDIT.getMcpAnalyticsRoutes()}+ {PLUGIN_AUDIT.getCliAnalyticsRoutes()}<Route key="index-layout" element={<MetabotAdminLayout />}><Route index key="index" element={<AISettingsPage />} /><Route key="mcp" path="mcp" element={<McpSettingsPage />} />diff --git a/frontend/src/metabase/plugins/oss/audit.ts b/frontend/src/metabase/plugins/oss/audit.tsindex 09434a06e70..ba0634950e1 100644--- a/frontend/src/metabase/plugins/oss/audit.ts+++ b/frontend/src/metabase/plugins/oss/audit.ts@@ -51,6 +51,7 @@ const getDefaultPluginAudit = () => ({getMetabotAnalyticsNavItems: (): ReactNode => null,getAiAnalyticsRoutes: (): ReactNode => null,getMcpAnalyticsRoutes: (): ReactNode => null,+ getCliAnalyticsRoutes: (): ReactNode => null,// Unjustified type cast. FIXMEhandleMetabotSlashCommand: ((_args) => false) as MetabotSlashCommandHandler,});diff --git a/resources/migrations/064/20260717_cli_usage_analytics.yaml b/resources/migrations/064/20260717_cli_usage_analytics.yamlnew file mode 100644index 00000000000..1581ed14209--- /dev/null+++ b/resources/migrations/064/20260717_cli_usage_analytics.yaml@@ -0,0 +1,113 @@+## CLI (Agent API) usage analytics storage layer.+##+## One table, agent_api_call_log — one row per direct Agent API HTTP call. Modeled on+## mcp_tool_call_log but leaner: the Agent API is stateless (no session table — the CLI opens+## no session), and each caller is classified into `client_name` from its self-reported+## User-Agent (metabase-cli/<version> -> "metabase-cli", anything else -> "other"). Client+## identity + PII are captured on the row so v_agent_api_calls needs no join beyond core_user+## and tenant. Row insertion is handled by the instrumentation in metabase.agent-api.api.++databaseChangeLog:+ - logicalFilePath: migrations/064_update_migrations.yaml++ - changeSet:+ id: v64.2026-07-17T00:00:00+ author: sfragnaud+ comment: Create agent_api_call_log table+ changes:+ - createTable:+ tableName: agent_api_call_log+ remarks: One row per direct Agent API HTTP call; client identity + PII captured on the row so the view needs no session join (modeled on mcp_tool_call_log)+ columns:+ - column:+ name: id+ type: bigint+ autoIncrement: true+ remarks: Autoincrement primary key+ constraints:+ primaryKey: true+ nullable: false+ - column:+ name: created_at+ type: ${timestamp_type}+ defaultValueComputed: current_timestamp+ remarks: When the Agent API call was made+ constraints:+ nullable: false+ - column:+ name: user_id+ type: int+ remarks: Metabase user behind the call; NULL for unauthenticated calls. Non-PII, always recorded.+ constraints:+ nullable: true+ - column:+ name: tenant_id+ type: int+ remarks: Snapshot of the calling user's tenant at call time; NULL for non-tenant users. Non-PII.+ constraints:+ nullable: true+ - column:+ name: client_name+ type: varchar(255)+ remarks: Canonical client key classified from the User-Agent (metabase-cli/other). Self-reported, analytics-only, never gated on. Non-PII.+ constraints:+ nullable: true+ - column:+ name: operation+ type: varchar(255)+ remarks: HTTP method + request URI of the Agent API call, e.g. "POST /api/agent/v1/query".+ constraints:+ nullable: true+ - column:+ name: status+ type: varchar(20)+ remarks: Outcome of the call, success or error (derived from the HTTP status code).+ constraints:+ nullable: true+ - column:+ name: duration_ms+ type: int+ remarks: Wall-clock duration of the call in milliseconds+ constraints:+ nullable: true+ - column:+ name: ip_address+ type: varchar(45)+ remarks: Client IP captured at call time, PII (gated by analytics-pii-retention-enabled).+ constraints:+ nullable: true+ - column:+ name: error_message+ type: ${text.type}+ remarks: Error message for a failed call, PII (gated by analytics-pii-retention-enabled, truncated); NULL on success or when gating is off.+ constraints:+ nullable: true+ rollback:+ - dropTable:+ tableName: agent_api_call_log++ - changeSet:+ id: v64.2026-07-17T00:00:01+ author: sfragnaud+ comment: Index on agent_api_call_log.user_id+ changes:+ - createIndex:+ indexName: idx_agent_api_call_log_user_id+ tableName: agent_api_call_log+ columns:+ - column:+ name: user_id+ rollback: # dropped with table++ - changeSet:+ id: v64.2026-07-17T00:00:02+ author: sfragnaud+ comment: Index on agent_api_call_log.created_at+ changes:+ - createIndex:+ indexName: idx_agent_api_call_log_created_at+ tableName: agent_api_call_log+ columns:+ - column:+ name: created_at+ rollback: # dropped with tablediff --git a/resources/migrations/064/20260717_cli_usage_analytics_view.yaml b/resources/migrations/064/20260717_cli_usage_analytics_view.yamlnew file mode 100644index 00000000000..41d5cb957a5--- /dev/null+++ b/resources/migrations/064/20260717_cli_usage_analytics_view.yaml@@ -0,0 +1,33 @@+## Create the v_agent_api_calls view for CLI (Agent API) usage analytics.+##+## Filename intentionally sorts after 20260717_cli_usage_analytics.yaml (the table-creation+## migration) so Liquibase — which processes change-log files alphabetically — creates the+## agent_api_call_log table before this view references it.+##+## Client identity + PII are stored on each call row, so v_agent_api_calls reads them straight+## off agent_api_call_log and only LEFT JOINs core_user (for the display name) and the tenant+## table (for tenant_name).++databaseChangeLog:+ - logicalFilePath: migrations/064_update_migrations.yaml++ - changeSet:+ id: v64.2026-07-17T00:00:10+ author: sfragnaud+ runOnChange: true+ comment: Create v_agent_api_calls view for CLI usage analytics+ changes:+ - sqlFile:+ dbms: postgresql+ path: ../instance_analytics_views/agent_api_calls/v1/postgres-agent_api_calls.sql+ relativeToChangelogFile: true+ - sqlFile:+ dbms: mysql,mariadb+ path: ../instance_analytics_views/agent_api_calls/v1/mysql-agent_api_calls.sql+ relativeToChangelogFile: true+ - sqlFile:+ dbms: h2+ path: ../instance_analytics_views/agent_api_calls/v1/h2-agent_api_calls.sql+ relativeToChangelogFile: true+ rollback:+ - sql: DROP VIEW IF EXISTS v_agent_api_callsdiff --git a/resources/migrations/instance_analytics_views/agent_api_calls/v1/h2-agent_api_calls.sql b/resources/migrations/instance_analytics_views/agent_api_calls/v1/h2-agent_api_calls.sqlnew file mode 100644index 00000000000..8bf1db0ea3b--- /dev/null+++ b/resources/migrations/instance_analytics_views/agent_api_calls/v1/h2-agent_api_calls.sql@@ -0,0 +1,35 @@+DROP VIEW IF EXISTS v_agent_api_calls;++CREATE OR REPLACE VIEW v_agent_api_calls AS+SELECT+ t.id AS call_id,+ t.created_at,+ t.operation,+ t.status,+ t.error_message AS error_message,+ t.duration_ms,+ t.user_id,+ COALESCE(u.first_name || ' ' || u.last_name, u.email) AS user_display_name,+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = t.user_id+ AND pg.id != 1+ ORDER BY pg.name+ LIMIT 1) AS group_name,+ t.client_name AS client_name,+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /+ -- `detect-client` in src/metabase/agent_api/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.tenant_id AS tenant_id,+ tn.name AS tenant_name,+ t.ip_address AS ip_address+FROM agent_api_call_log t+LEFT JOIN core_user u+ ON u.id = t.user_id+LEFT JOIN tenant tn+ ON tn.id = t.tenant_id;diff --git a/resources/migrations/instance_analytics_views/agent_api_calls/v1/mysql-agent_api_calls.sql b/resources/migrations/instance_analytics_views/agent_api_calls/v1/mysql-agent_api_calls.sqlnew file mode 100644index 00000000000..802bdbc5906--- /dev/null+++ b/resources/migrations/instance_analytics_views/agent_api_calls/v1/mysql-agent_api_calls.sql@@ -0,0 +1,35 @@+DROP VIEW IF EXISTS v_agent_api_calls;++CREATE OR REPLACE VIEW v_agent_api_calls AS+SELECT+ t.id AS call_id,+ t.created_at,+ t.operation,+ t.status,+ t.error_message AS error_message,+ t.duration_ms,+ t.user_id,+ COALESCE(CONCAT(u.first_name, ' ', u.last_name), u.email) AS user_display_name,+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = t.user_id+ AND pg.id != 1+ ORDER BY pg.name+ LIMIT 1) AS group_name,+ t.client_name AS client_name,+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /+ -- `detect-client` in src/metabase/agent_api/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.tenant_id AS tenant_id,+ tn.name AS tenant_name,+ t.ip_address AS ip_address+FROM agent_api_call_log t+LEFT JOIN core_user u+ ON u.id = t.user_id+LEFT JOIN tenant tn+ ON tn.id = t.tenant_id;diff --git a/resources/migrations/instance_analytics_views/agent_api_calls/v1/postgres-agent_api_calls.sql b/resources/migrations/instance_analytics_views/agent_api_calls/v1/postgres-agent_api_calls.sqlnew file mode 100644index 00000000000..8bf1db0ea3b--- /dev/null+++ b/resources/migrations/instance_analytics_views/agent_api_calls/v1/postgres-agent_api_calls.sql@@ -0,0 +1,35 @@+DROP VIEW IF EXISTS v_agent_api_calls;++CREATE OR REPLACE VIEW v_agent_api_calls AS+SELECT+ t.id AS call_id,+ t.created_at,+ t.operation,+ t.status,+ t.error_message AS error_message,+ t.duration_ms,+ t.user_id,+ COALESCE(u.first_name || ' ' || u.last_name, u.email) AS user_display_name,+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = t.user_id+ AND pg.id != 1+ ORDER BY pg.name+ LIMIT 1) AS group_name,+ t.client_name AS client_name,+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /+ -- `detect-client` in src/metabase/agent_api/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.tenant_id AS tenant_id,+ tn.name AS tenant_name,+ t.ip_address AS ip_address+FROM agent_api_call_log t+LEFT JOIN core_user u+ ON u.id = t.user_id+LEFT JOIN tenant tn+ ON tn.id = t.tenant_id;diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex c2fd976ee3c..ed769f6338f 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -4,6 +4,7 @@(:require[clojure.string :as str][metabase.agent-api.settings :as agent-api.settings]+ [metabase.agent-api.usage :as agent-api.usage][metabase.agent-api.validation :as agent-api.validation][metabase.ai-tracing.core :as ait][metabase.api.common :as api]@@ -1809,6 +1810,35 @@(def ^:private base-routes(api.macros/ns-handler *ns* +auth))+(defn- error-message-from-response+ "Best-effort human-readable error string from an agent-api error `response`, for the gated+ `error_message` column. Keyword lookups are nil-safe, so a streaming/opaque body just yields nil."+ [response]+ (let [body (:body response)]+ (or (:message body) (:error body))))++(defn- record-agent-api-usage!+ "Record one `agent_api_call_log` row for a completed direct Agent API HTTP call (EE-only).+ Best-effort: the EE writer wraps the insert in try/catch, so a failure to record is logged and+ swallowed — analytics never fails the request. Skips the synthetic in-process requests MCP+ dispatches through here — those are already counted in `mcp_tool_call_log`, so recording them+ again would double-count. `status`, `duration_ms`, IP, and User-Agent are all in scope here, and+ `+auth` has bound `*current-user-id*` by the time this respond fires so direct HTTP callers get+ attributed."+ [request response timer]+ (when-not (:agent-api-internal-request? request)+ (let [status-code (:status response)+ error? (or (nil? status-code) (>= status-code 400))]+ (agent-api.usage/record-agent-api-call!+ {:user-id (or (:metabase-user-id request) api/*current-user-id*)+ :tenant-id (some-> api/*current-user* deref :tenant_id)+ :user-agent (get-in request [:headers "user-agent"])+ :operation (str (some-> (:request-method request) name u/upper-case-en) " " (:uri request))+ :status (if error? "error" "success")+ :duration-ms (long (u/since-ms timer))+ :ip-address (request/ip-address request)+ :error-message (when error? (error-message-from-response response))}))))+(def ^{:arglists '([request respond raise])} routes"`/api/agent/` routes.";; Wrapped in `handler-with-open-api-spec` so the handler still implements `OpenAPISpec` for@@ -1820,33 +1850,37 @@;; Agent-API endpoints are synchronous, so `respond` fires inside the span and the span;; closes after the handler returns.(fn [request respond raise]- (ait/with-eval-session nil- (ait/eval-span (str "agent-api." (some-> (:request-method request) name) " " (:uri request))- {:http/method (some-> (:request-method request) name)- :http/uri (:uri request)- :http/request (:body request)- :http/user-id (or (:metabase-user-id request) api/*current-user-id*)}- (base-routes request- ;; Relies on `respond` firing synchronously on this thread (see- ;; above): if an endpoint ever responds async, `*parent*` is- ;; unbound there and this `record!` no-ops, so the span captures- ;; no status/response. Both fail soft; the trace is just incomplete- ;; for async agent-api responses.- (fn eval-traced-respond [response]- (when (ait/capture-active?)- ;; `+auth` binds `*current-user-id*` inside `base-routes`, so it- ;; is unbound when the span opened above but set by the time this- ;; respond fires — record the user id here so direct HTTP callers- ;; (not just the MCP path, which carries `:metabase-user-id`) get it.- (ait/record! {:http/status (:status response)- ;; Only record a plain data body. A streaming/opaque- ;; body (not a coll) would otherwise be stringified- ;; by the log sink into a useless `#object[…]`, so- ;; skip it — the trace just omits the response there.- :http/response (when (coll? (:body response))- (:body response))- :http/user-id (or (:metabase-user-id request)- api/*current-user-id*)}))- (respond response))- raise))))+ (let [timer (u/start-timer)]+ (ait/with-eval-session nil+ (ait/eval-span (str "agent-api." (some-> (:request-method request) name) " " (:uri request))+ {:http/method (some-> (:request-method request) name)+ :http/uri (:uri request)+ :http/request (:body request)+ :http/user-id (or (:metabase-user-id request) api/*current-user-id*)}+ (base-routes request+ ;; Relies on `respond` firing synchronously on this thread (see+ ;; above): if an endpoint ever responds async, `*parent*` is+ ;; unbound there and this `record!` no-ops, so the span captures+ ;; no status/response. Both fail soft; the trace is just incomplete+ ;; for async agent-api responses.+ (fn eval-traced-respond [response]+ (when (ait/capture-active?)+ ;; `+auth` binds `*current-user-id*` inside `base-routes`, so it+ ;; is unbound when the span opened above but set by the time this+ ;; respond fires — record the user id here so direct HTTP callers+ ;; (not just the MCP path, which carries `:metabase-user-id`) get it.+ (ait/record! {:http/status (:status response)+ ;; Only record a plain data body. A streaming/opaque+ ;; body (not a coll) would otherwise be stringified+ ;; by the log sink into a useless `#object[…]`, so+ ;; skip it — the trace just omits the response there.+ :http/response (when (coll? (:body response))+ (:body response))+ :http/user-id (or (:metabase-user-id request)+ api/*current-user-id*)}))+ ;; CLI usage analytics: one lean row per direct HTTP call, on the+ ;; same synchronous thread so identity/PII/duration are all in scope.+ (record-agent-api-usage! request response timer)+ (respond response))+ raise)))))(fn [prefix] (open-api/open-api-spec base-routes prefix))))diff --git a/src/metabase/agent_api/models/agent_api_call_log.clj b/src/metabase/agent_api/models/agent_api_call_log.cljnew file mode 100644index 00000000000..65f201c6298--- /dev/null+++ b/src/metabase/agent_api/models/agent_api_call_log.clj@@ -0,0 +1,9 @@+(ns metabase.agent-api.models.agent-api-call-log+ (:require+ [methodical.core :as methodical]+ [toucan2.core :as t2]))++(methodical/defmethod t2/table-name :model/AgentApiCallLog [_model] :agent_api_call_log)++(doto :model/AgentApiCallLog+ (derive :metabase/model))diff --git a/src/metabase/agent_api/usage.clj b/src/metabase/agent_api/usage.cljnew file mode 100644index 00000000000..e418e6f14e0--- /dev/null+++ b/src/metabase/agent_api/usage.clj@@ -0,0 +1,45 @@+(ns metabase.agent-api.usage+ "Agent API (CLI) usage logging.++ One write point feeds the analytics table: a lean `agent_api_call_log` row per direct Agent+ API HTTP call, recorded from the `routes` respond callback in `metabase.agent-api.api`. The+ write is a `defenterprise` no-op in OSS — an OSS instance records nothing — with the real+ insert in `metabase-enterprise.agent-api.usage`. Like `ai_usage_log`, collection runs on every+ EE instance (`:feature :none`); the `:audit-app` feature gates the surfaces that read these+ rows (the audit view + page), not the writing.++ PII columns (`ip_address`, `error_message`) are populated only when+ `analytics-pii-retention-enabled` is on — a setting that is itself `:audit-app`-gated and+ defaults off, so PII is never collected without `:audit-app`. `client_name` is classified from+ the caller's self-reported `User-Agent` (analytics only — never used to gate access)."+ (:require+ [clojure.string :as str]+ [metabase.premium-features.core :refer [defenterprise]]+ [metabase.util :as u]))++(def supported-client-keys+ "Canonical client keys [[detect-client]] classifies callers into for analytics. Keep in sync+ with the `client_name` CASE in the `v_agent_api_calls` view SQL (the enum-<->-CASE sync+ footgun)."+ #{"metabase-cli"})++(def ^:private client-name-matchers+ "Ordered `[substring canonical-key]` pairs matched against the lowercased `User-Agent`. First+ match wins. The Metabase CLI sends `metabase-cli/<version>`."+ [["metabase-cli" "metabase-cli"]])++(defn detect-client+ "Classify a caller's `User-Agent` into a canonical client key (one of [[supported-client-keys]]),+ or `\"other\"` when nothing matches (or the header is absent). Identity is self-reported and used+ for analytics only — never to gate access."+ [user-agent]+ (let [ua (some-> user-agent u/lower-case-en)]+ (or (when ua+ (some (fn [[needle k]] (when (str/includes? ua needle) k)) client-name-matchers))+ "other")))++(defenterprise record-agent-api-call!+ "Write a lean `agent_api_call_log` row for one direct Agent API HTTP call. OSS no-op."+ metabase-enterprise.agent-api.usage+ [_call-info]+ nil)diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.cljindex ee1711046ff..2b928eb7d15 100644--- a/src/metabase/mcp/tools.clj+++ b/src/metabase/mcp/tools.clj@@ -391,7 +391,11 @@(cond-> {:request-method method:uri path:metabase-user-id api/*current-user-id*- :token-scopes token-scopes}+ :token-scopes token-scopes+ ;; Marks this as MCP's synthetic in-process dispatch so the Agent API usage recorder+ ;; skips it — these calls are already counted in mcp_tool_call_log; recording them as+ ;; agent_api_call_log rows too would double-count.+ :agent-api-internal-request? true};; POST/PUT/PATCH carry params in the body; GET/DELETE carry them as query params.(and (seq params) (#{:post :put :patch} method)) (assoc :body params)(and (seq params) (not (#{:post :put :patch} method))) (assoc :query-params params))diff --git a/src/metabase/models/resolution.clj b/src/metabase/models/resolution.cljindex 97db0e005e2..9fdcf495810 100644--- a/src/metabase/models/resolution.clj+++ b/src/metabase/models/resolution.clj@@ -13,6 +13,7 @@Tests will check to make sure new models get included in this map."'{:model/Action metabase.actions.models+ :model/AgentApiCallLog metabase.agent-api.models.agent-api-call-log:model/AnalysisFinding metabase-enterprise.dependencies.models.analysis-finding:model/AnalysisFindingError metabase-enterprise.dependencies.models.analysis-finding-error:model/ApiKey metabase.api-keys.models.api-keydiff --git a/test/metabase/cmd/copy_test.clj b/test/metabase/cmd/copy_test.cljindex afee9df4fed..8b90a1b35a1 100644--- a/test/metabase/cmd/copy_test.clj+++ b/test/metabase/cmd/copy_test.clj@@ -25,7 +25,8 @@(def ^:private models-to-exclude"Models that should *not* be migrated in `load-from-h2`."- #{:model/AiUsageLog+ #{:model/AgentApiCallLog+ :model/AiUsageLog:model/AnalysisFinding:model/AnalysisFindingError:model/ApiKey