Skip to content

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

Add CLI usage analytics (#78216)

Sébastiend8f7ae6a91d7
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 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-tracing
api
auth-identity
@@ -169,6 +168,7 @@
lib-be
llm
metabot
+ premium-features
queries
query-permissions
query-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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
index 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.clj
index 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.clj
index 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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
index 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/ApiKey
diff --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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.css
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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. FIXME
handleMetabotSlashCommand: ((_args) => false) as MetabotSlashCommandHandler,
});
diff --git a/resources/migrations/064/20260717_cli_usage_analytics.yaml b/resources/migrations/064/20260717_cli_usage_analytics.yaml
new file mode 100644
index 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 table
diff --git a/resources/migrations/064/20260717_cli_usage_analytics_view.yaml b/resources/migrations/064/20260717_cli_usage_analytics_view.yaml
new file mode 100644
index 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_calls
diff --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.sql
new file mode 100644
index 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.sql
new file mode 100644
index 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.sql
new file mode 100644
index 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.clj
index 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.clj
new file mode 100644
index 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.clj
new file mode 100644
index 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.clj
index 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.clj
index 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-key
diff --git a/test/metabase/cmd/copy_test.clj b/test/metabase/cmd/copy_test.clj
index 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