The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
[API Key analytics] Integration branch → master (#83726)
Sébastien21613fe65f92
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.ednindex 645a5b7d447..5e8c0273cd9 100644--- a/.clj-kondo/config/modules/config.edn+++ b/.clj-kondo/config/modules/config.edn@@ -182,6 +182,7 @@metabase.analytics.coremetabase.analytics.eventmetabase.analytics.init+ metabase.analytics.sdkmetabase.analytics.settings}:uses #{analytics.interfaceanalytics.internal-stats@@ -296,16 +297,18 @@{:team "UX West":api #{metabase.api-keys.apimetabase.api-keys.core- metabase.api-keys.schema}+ metabase.api-keys.schema+ metabase.api-keys.usage}:uses #{apiapp-dbeventslib.schemamodelspermissions+ premium-featuresusersutil}- :model-exports #{:model/ApiKey}+ :model-exports #{:model/ApiKey :model/ApiKeyUsageLog}:model-imports #{:model/User}}api-routes@@ -2862,6 +2865,7 @@metabase.testing-api.init}:uses #{analyticsapi+ api-keysapp-dbliblib.be@@ -3544,6 +3548,19 @@premium-featuresutil}}+ enterprise/api-keys+ {:team "UX West"+ :api #{metabase-enterprise.api-keys.init}+ :uses #{analytics+ api-keys+ metabot+ premium-features+ request+ startup+ task+ util}+ :model-imports #{:model/ApiKeyUsageLog}}+enterprise/api-routes{:team "UX West":api #{metabase-enterprise.api-routes.routes}diff --git a/docs/configuring-metabase/environment-variables.md b/docs/configuring-metabase/environment-variables.mdindex 5f67650da1f..c25b7eb20fb 100644--- a/docs/configuring-metabase/environment-variables.md+++ b/docs/configuring-metabase/environment-variables.md@@ -86,7 +86,7 @@ Whether AI features are enabled.- [Exported as](../installation-and-operation/serialization.md): `ai-usage-max-retention-days`.- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md).-Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely.+Number of days to retain rows in the ai_usage_log, metabot_conversation, metabot_message, agent_api_call_log, and api_key_usage_log tables. Minimum value is 30; set to 0 to retain data indefinitely.Sets the maximum number of days Metabase preserves rows for the following application database tables:@@ -94,6 +94,7 @@ Sets the maximum number of days Metabase preserves rows for the following applic- `metabot_conversation`- `metabot_message`- `agent_api_call_log`+- `api_key_usage_log`Once a day, Metabase deletes rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).If set to 0, Metabase will keep all rows. If you don't set this variable, Metabase keeps rows for 180 days.diff --git a/e2e/test/scenarios/monitor/api-key-usage.cy.spec.ts b/e2e/test/scenarios/monitor/api-key-usage.cy.spec.tsnew file mode 100644index 00000000000..3afb010e6f0--- /dev/null+++ b/e2e/test/scenarios/monitor/api-key-usage.cy.spec.ts@@ -0,0 +1,120 @@+const { H } = cy;++import { ADMIN_USER_ID } from "e2e/support/cypress_sample_instance_data";++const API_KEY_USAGE_PATH = "/monitor/api-key-usage";+const ADMIN_GROUP_ID = 2;+const SEEDED_KEY_NAME = "e2e_seeded_key";+const UNUSED_KEY_NAME = "e2e_unused_key";+const ADMIN_DISPLAY_NAME = "Bobby Tables";++type CreateApiKeyResponse = { id: number };++function seedApiKeyUsage(+ apiKeyId: number,+): Cypress.Chainable<Cypress.Response<{ inserted: number }>> {+ return cy.request("POST", "/api/testing/api-keys/seed-usage", {+ api_key_id: apiKeyId,+ user_id: ADMIN_USER_ID,+ created_by_id: ADMIN_USER_ID,+ });+}++function visitApiKeyUsagePage(): void {+ cy.intercept("GET", "/api/database/13371337/metadata*").as("auditMetadata");++ cy.visit(API_KEY_USAGE_PATH);+ cy.wait("@auditMetadata");+}++// The first query against the audit view can take a while to settle locally, so this gates on+// aria-busy clearing (rather than a network alias, which races against the Usage tab's own chart+// queries sharing the same /api/dataset endpoint) before asserting on rendered content.+function eventsTable() {+ cy.findByTestId("api-key-usage-events-table", { timeout: 20000 }).should(+ "have.attr",+ "aria-busy",+ "false",+ );+ return cy.findByTestId("api-key-usage-events-table");+}++function selectApiKeyFilter(label: string): void {+ cy.findByTestId("api-key-usage-filter-select").click();+ H.popover().findByRole("option", { name: label }).click();+}++// The events table has 11 columns and doesn't fit the default viewport.+describe("scenarios > monitor > api key usage", { viewportWidth: 1600 }, () => {+ beforeEach(() => {+ H.restore();+ cy.signInAsAdmin();+ H.activateToken("pro-self-hosted");+ });++ it("shows seeded usage and lets an admin filter by API key and date", () => {+ H.createApiKey(SEEDED_KEY_NAME, ADMIN_GROUP_ID).then(+ ({ body }: { body: CreateApiKeyResponse }) => {+ seedApiKeyUsage(body.id);+ },+ );+ H.createApiKey(UNUSED_KEY_NAME, ADMIN_GROUP_ID);++ visitApiKeyUsagePage();++ cy.log("The nav item lives directly under Monitor");+ cy.findByRole("link", { name: "API key usage" }).should("be.visible");++ cy.log("The Usage tab renders with the seeded key (not the empty state)");+ H.main().within(() => {+ cy.findByRole("heading", { name: "API key usage" }).should("be.visible");+ cy.findByText("No API key activity").should("not.exist");+ cy.findByText(SEEDED_KEY_NAME).should("be.visible");+ });++ cy.log(+ "The API key filter scopes the Key activity table, but an unused key still shows its own row",+ );+ selectApiKeyFilter(UNUSED_KEY_NAME);+ H.main().within(() => {+ cy.findByText("No API key activity").should("not.exist");+ cy.findByText(UNUSED_KEY_NAME).should("be.visible");+ cy.findByText(SEEDED_KEY_NAME).should("not.exist");+ });+ selectApiKeyFilter("All API keys");+ H.main().findByText(SEEDED_KEY_NAME).should("be.visible");++ cy.log("The Events tab shows the seeded call, attributed to its creator");+ H.main().findByRole("link", { name: "Events" }).click();+ eventsTable().within(() => {+ cy.findByText("Created by").should("be.visible");+ cy.findByText(SEEDED_KEY_NAME).should("be.visible");+ cy.findByText(ADMIN_DISPLAY_NAME).should("be.visible");+ });++ cy.log(+ "There's no separate user filter — the API key filter is the primary way to scope the page",+ );+ cy.findByTestId("conversation-filters-user-select").should("not.exist");++ cy.log("Filtering by the seeded API key keeps the call");+ selectApiKeyFilter(SEEDED_KEY_NAME);+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");++ cy.log(+ "Filtering by an unused API key shows the events table's own empty state, not the whole page",+ );+ selectApiKeyFilter(UNUSED_KEY_NAME);+ H.main().findByText("No API key activity").should("not.exist");+ eventsTable().findByText("No calls found").should("be.visible");++ cy.log("Clearing the API key filter restores the call");+ selectApiKeyFilter("All API keys");+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");++ cy.log("Widening the date range still includes the just-seeded call");+ cy.findByTestId("conversation-filters-date-select").click();+ H.popover().findByText("Last 7 days").click();+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");+ });+});diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/db.clj b/enterprise/backend/src/metabase_enterprise/api_keys/db.cljnew file mode 100644index 00000000000..f09fba54da5--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/api_keys/db.clj@@ -0,0 +1,15 @@+(ns metabase-enterprise.api-keys.db+ "Application database queries for the enterprise api-keys module. Every function here is a direct Toucan 2 call with+ no additional logic, so the rest of the module never talks to `toucan2.core` itself."+ (:require+ [toucan2.core :as t2]))++(defn insert-usage-logs!+ "Insert the ApiKeyUsageLog `rows` as one batch."+ [rows]+ (t2/insert! :model/ApiKeyUsageLog rows))++(defn delete-usage-logs-occurred-before!+ "Delete the ApiKeyUsageLogs whose `occurred_at` is before `cutoff`, returning the number deleted."+ [cutoff]+ (t2/delete! :model/ApiKeyUsageLog {:where [:< :occurred_at cutoff]}))diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/init.clj b/enterprise/backend/src/metabase_enterprise/api_keys/init.cljnew file mode 100644index 00000000000..52e0a1d5445--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/api_keys/init.clj@@ -0,0 +1,13 @@+(ns metabase-enterprise.api-keys.init+ "Startup wiring for the enterprise API keys module — loads the scheduled API key usage trimmer and+ the usage/last_used_at flush loop so their lifecycle methods run on boot (on every EE instance,+ matching where API key usage is collected).++ `metabase-enterprise.api-keys.usage` is a `defenterprise` implementation namespace, which `require`s+ lazily on the *first call* to `metabase.api-keys.usage/record-api-key-usage!` — too late for its+ `task/init!` (trimmer) and `startup/def-startup-logic!`/`def-shutdown-logic!` (flush loop)+ registrations, which are each walked once at boot/shutdown. Requiring it here forces it to load up+ front instead."+ (:require+ [metabase-enterprise.api-keys.task.api-key-usage-trimmer]+ [metabase-enterprise.api-keys.usage]))diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.clj b/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.cljnew file mode 100644index 00000000000..bfb19e120a0--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.clj@@ -0,0 +1,53 @@+(ns metabase-enterprise.api-keys.task.api-key-usage-trimmer+ "Scheduled task to delete `api_key_usage_log` rows older than the configured+ `ai-usage-max-retention-days`. Mirrors the Metabot `ai-usage-trimmer`, the MCP usage trimmer, and+ the Agent API usage trimmer: API key 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-enterprise.api-keys.db :as api-keys.db]+ [metabase.metabot.settings :as metabot.settings]+ [metabase.task.core :as task]+ [metabase.util.log :as log])+ (:import+ (org.quartz DisallowConcurrentExecution)))++(set! *warn-on-reflection* true)++(def ^:private trimmer-job-key (jobs/key "metabase.task.api-keys.usage-trimmer.job"))+(def ^:private trimmer-trigger-key (triggers/key "metabase.task.api-keys.usage-trimmer.trigger"))++(defn- trim-old-api-key-usage-data!+ []+ (let [retention-days (metabot.settings/ai-usage-max-retention-days)]+ (if (nil? retention-days)+ (log/info "Skipping API key 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 API key usage log rows older than %d days." (long retention-days))+ (let [rows (api-keys.db/delete-usage-logs-occurred-before! cutoff)]+ (log/infof "API key usage log cleanup complete. Deleted %d rows." (or rows 0)))))))++(task/defjob ^{DisallowConcurrentExecution true+ :doc "Delete old API key usage log rows"}+ ApiKeyUsageTrimmer [_ctx]+ (trim-old-api-key-usage-data!))++(defmethod task/init! ::ApiKeyUsageTrimmer+ [_]+ (let [job (jobs/build+ (jobs/of-type ApiKeyUsageTrimmer)+ (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:29:41. The offset from the MCP (23:19:41) and Agent API (23:24:41) trimmers+ ;; just staggers the 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 29 23 * * ?")))]+ (task/schedule-task! job trigger)))diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/usage.clj b/enterprise/backend/src/metabase_enterprise/api_keys/usage.cljnew file mode 100644index 00000000000..f684266b4ed--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/api_keys/usage.clj@@ -0,0 +1,300 @@+(ns metabase-enterprise.api-keys.usage+ "Enterprise implementation of API-key usage logging.++ Writes one lean `api_key_usage_log` row per API-key-authenticated request and stamps+ `api_key.last_used_at` for liveness. Collection runs on every EE instance (`:feature :none`),+ mirroring `ai_usage_log`; the `ip_address` and `user_agent` columns are populated only when+ `analytics-pii-retention-enabled` is on (itself `:audit-app`-gated). The table has no free-text+ error column to gate — see `metabase.api-keys.usage` for why.++ Both writes coalesce in memory and flush on a fixed interval via a scheduled task, not Grouper: a+ Grouper queue falls back to a *blocking* put once full, which would stall the request thread behind+ a slow DB write. The usage-log write bounds a pending vector and drops (logged) rather than blocks+ once full; the last_used_at write coalesces to one pending entry per key, so it never needs a+ capacity bound at all — see the two sections below for each.++ Every write is best-effort: a failure is logged and swallowed so logging never fails the API+ request and adds negligible latency. The two writes are independent of each other's success or+ failure, even though callers only see a single [[record-api-key-usage!]] entry point."+ (:require+ [java-time.api :as t]+ [metabase-enterprise.api-keys.db :as ee.api-keys.db]+ [metabase.analytics.core :as analytics]+ [metabase.analytics.sdk :as analytics.sdk]+ [metabase.api-keys.core :as api-keys]+ [metabase.api-keys.usage :as api-keys.usage]+ [metabase.premium-features.core :refer [defenterprise]]+ [metabase.request.core :as request]+ [metabase.startup.core :as startup]+ [metabase.util :as u]+ [metabase.util.log :as log])+ (:import+ (java.util.concurrent Executors ScheduledExecutorService ThreadFactory TimeUnit)))++(set! *warn-on-reflection* true)++(def ^:private route-template-max-length+ "Cap on the stored route_template length, matching the `api_key_usage_log.route_template` column width."+ 255)++(def ^:private unmatched-route-template+ "Recorded in `route_template` when a request authenticated with an API key reached routing but+ matched no endpoint (a real 404) — an absent template here is a real, valid event (someone probing+ for routes, a client hitting a typo'd URL), not something to discard. Distinguishable from a real+ template at a glance: a matched template always starts with `/`."+ "(unmatched)")++(def ^:private no-route-template+ "Recorded in `route_template` when a request authenticated with an API key reached a handler that+ isn't `defendpoint`-based (health checks, docs, a premium-feature 402 raised before routing) — nil+ here, unlike [[unmatched-route-template]], doesn't mean someone probed for a nonexistent route."+ "(no-template)")++(def ^:private http-method-max-length+ "Cap on the stored http_method length, matching the `api_key_usage_log.http_method` column width."+ 10)++(def ^:private ip-address-max-length+ "Cap on the stored ip_address length, matching the `api_key_usage_log.ip_address` column width. Long+ enough for IPv6; a forwarded-for header longer than that is truncated rather than failing the insert."+ 45)++(def ^:private embedding-client-max-length+ "Cap on the stored embedding_client length, matching the `api_key_usage_log.embedding_client` column+ width. Caller-supplied and unvalidated, unlike client_name — truncate rather than fail the insert."+ 255)++(def ^:private embedding-hostname-max-length+ "Cap on the stored embedding_hostname length, matching the `api_key_usage_log.embedding_hostname`+ column width. `extract-hostname` already truncates to this width; kept here so this row survives a+ future change to that shared helper."+ 512)++;;; ------------------------------------------------- usage log ----------------------------------------------------++(def ^:private usage-log-batch-capacity+ "How many rows the pending usage-log queue holds before a new row is dropped rather than queued."+ 500)++(def ^:private flush-interval-seconds+ "How often pending usage-log rows and last_used_at stamps flush to the database."+ 10)++(def ^:private not-null-columns+ "The `api_key_usage_log` columns declared NOT NULL that this namespace can't always fill in from the+ request alone. Rows are inserted in batches, so a row missing one of these would fail every row+ batched with it, not just itself — an incomplete row is dropped before it is queued instead.+ `route_template` isn't here: an unmatched route is a real event, recorded as+ [[unmatched-route-template]] rather than discarded — see [[record-api-key-usage!]]."+ [:api_key_id :http_method :status :duration_ms :client_name])++(defonce ^:private pending-usage-logs (atom []))++;; Counts drops between flushes rather than logging each one — a burst past the cap can drop+;; hundreds of rows a second, and one warning per row would itself flood the log. See+;; [[flush-usage-logs!]], which logs the total once and resets this.+(defonce ^:private dropped-usage-log-count (atom 0))++(defn- offer-usage-log!+ "Appends `row` to the pending batch, unless it's already at [[usage-log-batch-capacity]] — a full+ queue drops the row rather than blocking the request thread waiting for room. Uses `swap-vals!`+ rather than a `volatile!` set from inside the `swap!` function: under CAS contention `swap!` can+ invoke that function more than once, so an early attempt that sees the queue full and flags a drop+ can still lose the race to a retry that finds room and conjes the row — counting a drop for a row+ that was actually queued. Comparing the before/after values instead only counts a drop for the+ transition that actually won."+ [row]+ (let [[old new] (swap-vals! pending-usage-logs+ (fn [rows]+ (if (>= (count rows) usage-log-batch-capacity)+ rows+ (conj rows row))))]+ (when (identical? old new)+ (swap! dropped-usage-log-count inc))))++(defn- flush-usage-logs!+ "Scheduled-task handler: atomically take the current pending rows and insert them as one batch.+ Also takes and logs, once, the row count [[offer-usage-log!]] dropped since the last flush — see+ [[dropped-usage-log-count]]."+ []+ (let [[rows] (reset-vals! pending-usage-logs [])+ [dropped] (reset-vals! dropped-usage-log-count 0)]+ (when (pos? dropped)+ (log/warnf "Dropped %d API key usage log rows; the pending queue was full" dropped))+ (when (seq rows)+ (log/debugf "Inserting %d api_key_usage_log rows" (count rows))+ (try+ (ee.api-keys.db/insert-usage-logs! rows)+ (catch Throwable e+ (log/warn e "Failed to insert API key usage log rows"))))))++;;; ---------------------------------------------- last_used_at ----------------------------------------------------++;; A coalescing map, not a Grouper queue of events: a Grouper queue keeps every event until it flushes, so a hot+;; key piles up hundreds of entries between flushes only to have all but the newest discarded at flush time. Here,+;; each request updates its key's entry *in place* — a busy key costs one map entry, not one entry per request — and+;; a scheduled task flushes the current contents on a fixed interval. `reset-vals!` atomically swaps in a fresh+;; empty map and returns the one it replaced, so a request arriving mid-flush lands in the new map and is picked up+;; next interval, never lost and never blocking the flush.++;; api-key-id -> the latest `occurred-at` seen for it since the last flush.+(defonce ^:private pending-last-used-at (atom {}))++(defn- stamp-last-used-at! [api-key-id timestamp]+ (swap! pending-last-used-at update api-key-id+ (fn [existing] (if existing (t/max existing timestamp) timestamp))))++(defn- flush-last-used-at!+ "Scheduled-task handler: atomically take the current pending map and issue one bulk UPDATE for it.+ Keys skipped because a concurrent writer held the row go back into the pending map for the next+ flush, merged against whatever arrived for them in the meantime (the newer of the two wins) rather+ than overwriting it."+ []+ (let [[batch] (reset-vals! pending-last-used-at {})]+ (when (seq batch)+ (log/debugf "Updating last_used_at for %d API keys" (count batch))+ (try+ (let [skipped (api-keys/update-api-keys-last-used-at! batch)]+ (when (seq skipped)+ (log/debugf "Retrying last_used_at for %d busy API keys next flush" (count skipped))+ (swap! pending-last-used-at #(merge-with t/max % skipped))))+ (catch Throwable e+ (log/warn e "Failed to update API key last_used_at"))))))++;;; -------------------------------------------- flush scheduling ---------------------------------------------------++;; A JVM-local scheduled executor, not Quartz: pending-usage-logs and pending-last-used-at are per-JVM+;; atoms, but our Quartz is clustered (JDBC job store), so a recurring trigger only ever fires on one+;; node. A node that never wins trigger acquisition would never flush its own in-memory state — its+;; usage-log queue would fill and drop every row, and its last_used_at stamps would never reach the+;; DB. Each node instead runs its own single-threaded executor for its own pending state, mirroring+;; `metabase.mq.publish-buffer`.++(defn- safe-flush!+ "Runs both flush functions, swallowing any throwable. `scheduleAtFixedRate` silently stops+ rescheduling a task that throws an uncaught exception, which would freeze the flusher for the rest+ of the JVM's life; each flush function already catches its own errors, but this is a second line of+ defense so a future change to either can't silently kill the flush loop."+ []+ (try+ (flush-usage-logs!)+ (flush-last-used-at!)+ (catch Throwable e+ (log/error e "Unexpected error in API key usage flush; flusher continues"))))++(defonce ^:private flush-executor (atom nil))++(defn- start-flush!+ "Starts a daemon thread that flushes pending usage-log rows and last_used_at stamps every+ [[flush-interval-seconds]]. Idempotent. Returns `true` if THIS call created the executor, `false`+ if one was already running."+ []+ (let [exec (Executors/newSingleThreadScheduledExecutor+ (reify ThreadFactory+ (newThread [_ r]+ (doto (Thread. r "api-key-usage-flush")+ (.setDaemon true)))))]+ (if (compare-and-set! flush-executor nil exec)+ (do (.scheduleAtFixedRate exec ^Runnable safe-flush! flush-interval-seconds flush-interval-seconds TimeUnit/SECONDS)+ true)+ (do (.shutdown exec) false))))++(defn- stop-flush!+ "Stops the flush thread, then force-flushes anything still pending so a graceful shutdown doesn't+ lose the last interval's worth of rows/stamps."+ []+ (when-let [^ScheduledExecutorService exec (first (reset-vals! flush-executor nil))]+ (.shutdownNow exec))+ (safe-flush!))++(defmethod startup/def-startup-logic! ::ApiKeyUsageFlush+ [_]+ (start-flush!))++(defmethod startup/def-shutdown-logic! ::ApiKeyUsageFlush+ [_]+ (stop-flush!))++;;; ------------------------------------------------- entry point ---------------------------------------------------++(defn- request-user-agent [request] (get-in request [:headers "user-agent"]))+(defn- request-embedding-client [request] (get-in request [:headers "x-metabase-client"]))+(defn- request-embedding-hostname [request]+ (analytics.sdk/extract-hostname (get-in request [:headers "x-metabase-embed-referrer"])))++(defenterprise record-api-key-usage!+ "EE: record one completed API-key-authenticated request. Queues one `api_key_usage_log` row and one+ `last_used_at` event, both flushed on a scheduled interval, never synchronously on the request thread.++ Takes the raw `request`/`response` and extracts everything itself, plus `extra-info` for the+ handful of values only the caller can supply: `route-template` (read from the carrier the caller+ installed before routing ran — see `metabase.api.macros/route-template-carrier-key`; nil for a+ request that never reached a `defendpoint` handler, recorded as [[unmatched-route-template]] for a+ real 404 or [[no-route-template]] otherwise (health checks, docs, a 402 raised before routing) —+ rather than dropping the row, since neither case is an incomplete event), `duration-ms` (measured by the+ caller around the whole request), and `occurred-at` (captured on the request thread rather than left+ for the DB to fill in at INSERT time — the row lands via a scheduled flush, up to the flush interval+ later, so a DB-computed default would record when the flush ran, not when the request happened).++ `user_id` is the key's own synthetic service-account user (used for permission checks, not a real+ person); `created_by_id` is the real human who created the key, read off the same auth query — see+ `metabase.server.db/user-data-for-api-key-prefix-query`. Both non-PII.++ `ip_address` and `user_agent` are PII — stored only when `analytics-pii-retention-enabled` is on.+ `client_name` is classified from `user-agent` via [[metabase.api-keys.usage/detect-client]] and+ always recorded — non-PII, mirrors `agent_api_call_log`'s `client_name`. `embedding_client` is the+ raw `X-Metabase-Client` header, passed through unclassified and non-PII, supplementary to+ `client_name`. `embedding_hostname` is the hostname parsed from the embed referrer header, non-PII,+ always recorded — only meaningful alongside `embedding_client`. `route_template`, `http_method`,+ `embedding_client`, and `embedding_hostname` are truncated to their column widths; a row missing a+ NOT NULL value the caller can't have controlled (see [[not-null-columns]]) is dropped rather than+ queued, so it can't sink the batch it would land in — the `last_used_at` event is queued regardless,+ since `api-key-id` is always present on an API-key-authenticated request."+ :feature :none+ [request response {:keys [route-template duration-ms occurred-at]}]+ (let [api-key-id (:api-key-id request)+ user-agent (request-user-agent request)+ occurred-at (or occurred-at (t/offset-date-time))]+ (when api-key-id+ (try+ (stamp-last-used-at! api-key-id occurred-at)+ (catch Throwable e+ (log/warn e "Failed to record API key last_used_at"))))+ (try+ (let [;; `pii-fields-from` returns the gated PII columns only when retention is on (nil+ ;; otherwise). Allowlist the two columns this row has, so a new field on the shared helper+ ;; can't silently start persisting here without a deliberate change.+ pii (some-> (analytics/pii-fields-from {:user-agent user-agent+ :ip-address (request/ip-address request)})+ (select-keys [:user_agent :ip_address])+ (update :ip_address #(some-> % (u/truncate ip-address-max-length))))+ row (merge {:api_key_id api-key-id+ :user_id (:metabase-user-id request)+ :created_by_id (:api-key-creator-id request)+ :route_template (or (some-> route-template (u/truncate route-template-max-length))+ (if (= 404 (:status response))+ unmatched-route-template+ no-route-template))+ :http_method (some-> (:request-method request) name u/upper-case-en+ (u/truncate http-method-max-length))+ :status (:status response)+ :duration_ms duration-ms+ :occurred_at occurred-at+ :client_name (api-keys.usage/detect-client user-agent)+ :embedding_client (some-> (request-embedding-client request) (u/truncate embedding-client-max-length))+ :embedding_hostname (some-> (request-embedding-hostname request) (u/truncate embedding-hostname-max-length))}+ pii)]+ (if-let [missing (not-empty (remove #(some? (get row %)) not-null-columns))]+ (log/warnf "Not recording API key usage log row, missing %s" (pr-str missing))+ (offer-usage-log! row)))+ (catch Throwable e+ (log/warn e "Failed to record API key usage")))))++(defenterprise flush-pending-writes!+ "EE: synchronously flush the pending usage-log and last_used_at batches instead of waiting for the+ scheduled interval. Only meaningful for tests that need a just-recorded event to be immediately+ queryable."+ :feature :none+ []+ (flush-usage-logs!)+ (flush-last-used-at!))diff --git a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.cljindex f551828f6a1..0761c7834a1 100644--- a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj+++ b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj@@ -34,7 +34,8 @@"v_metabot_messages""v_ai_usage_log""v_mcp_tool_calls"- "v_agent_api_calls"})+ "v_agent_api_calls"+ "v_api_key_usage"})(defenterprise check-audit-db-permissions"Performs a number of permission checks to ensure that a query on the Audit database can be run.diff --git a/enterprise/backend/src/metabase_enterprise/core/init.clj b/enterprise/backend/src/metabase_enterprise/core/init.cljindex 5f5f6c46683..92ecf9e0d37 100644--- a/enterprise/backend/src/metabase_enterprise/core/init.clj+++ b/enterprise/backend/src/metabase_enterprise/core/init.clj@@ -9,6 +9,7 @@[metabase-enterprise.action-v2.init][metabase-enterprise.advanced-config.init][metabase-enterprise.agent-api.init]+ [metabase-enterprise.api-keys.init][metabase-enterprise.audit-app.init][metabase-enterprise.cache.init][metabase-enterprise.custom-viz-plugin.init]diff --git a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.cljindex c5c70beeaf2..60c4014f2db 100644--- a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj+++ b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj@@ -72,6 +72,7 @@"AnalysisFinding""AnalysisFindingError""ApiKey"+ "ApiKeyUsageLog""ApplicationPermissionsRevision""AuditLog""AuthIdentity"diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.cljnew file mode 100644index 00000000000..16b20327600--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.clj@@ -0,0 +1,46 @@+(ns metabase-enterprise.api-keys.task.api-key-usage-trimmer-test+ (:require+ [clojure.test :refer :all]+ [java-time.api :as t]+ [metabase-enterprise.api-keys.task.api-key-usage-trimmer :as api-key-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}` — API key+;; usage is collected on every EE instance, so its trimmer must run regardless of the audit-app feature.++(defn- usage-log [occurred-at]+ {:api_key_id 1234+ :route_template "/api/usage-trimmer-test/:id"+ :http_method "GET"+ :status 200+ :duration_ms 12+ :client_name "curl"+ :occurred_at occurred-at})++(deftest trims-rows-older-than-custom-retention-test+ (testing "with retention set to 30 days, usage rows older than 30 days are deleted"+ (mt/with-temp+ [:model/ApiKeyUsageLog {recent :id} (usage-log (t/offset-date-time))+ :model/ApiKeyUsageLog {boundary :id} (usage-log (t/minus (t/offset-date-time) (t/days 31)))+ :model/ApiKeyUsageLog {old :id} (usage-log (t/minus (t/offset-date-time) (t/days 200)))]+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 30]+ (#'api-key-usage-trimmer/trim-old-api-key-usage-data!)+ (is (= #{recent}+ (t2/select-fn-set :id :model/ApiKeyUsageLog {:where [:in :id [recent boundary old]]}))+ "usage 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/ApiKeyUsageLog {recent :id} (usage-log (t/offset-date-time))+ :model/ApiKeyUsageLog {old :id} (usage-log (t/minus (t/offset-date-time) (t/years 5)))]+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 0]+ (#'api-key-usage-trimmer/trim-old-api-key-usage-data!)+ (is (= #{recent old}+ (t2/select-fn-set :id :model/ApiKeyUsageLog {:where [:in :id [recent old]]})))))))diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.cljnew file mode 100644index 00000000000..5acb6fc6972--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.clj@@ -0,0 +1,132 @@+(ns metabase-enterprise.api-keys.usage-instrumentation-test+ "End-to-end tests for the API-key usage hook in `metabase.server.middleware.log/log-api-call`: real HTTP requests+ through the real middleware and routing stack, asserting the rows that actually land in `api_key_usage_log`.++ The pieces are unit-tested elsewhere (`metabase-enterprise.api-keys.usage-test` for the recorders,+ `metabase.server.middleware.log-test` for the hook, `metabase.api.util.handlers-test` for route-template+ reconstruction). What can only be checked here is that they are wired together — in particular that+ `route_template` survives the trip from the routing tree back up to the log middleware, which sees only the+ pre-routing request."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [metabase-enterprise.api-keys.usage :as ee-usage]+ [metabase.permissions.core :as perms]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [metabase.test.http-client :as client]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(use-fixtures :once (fixtures/initialize :db :test-users :web-server))++(defn- rows-for!+ "Forces the pending usage-log rows to flush before reading — they coalesce in memory between+ scheduled flushes, so a row written moments ago may not be on disk yet."+ [api-key-id]+ (#'ee-usage/flush-usage-logs!)+ (t2/select :model/ApiKeyUsageLog :api_key_id api-key-id {:order-by [[:id :asc]]}))++(defn- last-used-at!+ "Forces the pending `last_used_at` stamps to flush before reading — they coalesce in memory between+ scheduled flushes, so a stamp made moments ago may not be on disk yet."+ [api-key-id]+ (#'ee-usage/flush-last-used-at!)+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))++(defn- api-key-headers [unmasked-key]+ {:request-options {:headers {"x-api-key" unmasked-key, "user-agent" "metabase-cli/1.2.3"}}})++(defn- do-with-api-key!+ "Create a real API key over the API, run `f` with its unmasked key and id, then clean up the key and its usage rows.+ Both the usage-log row and the `last_used_at` stamp coalesce in memory between scheduled flushes —+ see [[rows-for!]] and [[last-used-at!]], which force a flush before reading."+ [f]+ (let [{unmasked-key :unmasked_key, api-key-id :id}+ (mt/user-http-request :crowberto :post 200 "api-key"+ {:group_id (:id (perms/all-users-group))+ :name (str (random-uuid))})]+ (try+ (f unmasked-key api-key-id)+ (finally+ (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id)+ (t2/delete! :model/ApiKey :id api-key-id)))))++(deftest api-key-request-is-recorded-test+ (testing "an API-key-authenticated request to a defendpoint records one row, attributed to the key that made it"+ (do-with-api-key!+ (fn [unmasked-key api-key-id]+ (client/client :get 200 "user/current" (api-key-headers unmasked-key))+ (let [[row :as rows] (rows-for! api-key-id)]+ (is (= 1 (count rows)))+ (testing "the route template made it up from the routing tree — this is the whole point of the hook"+ (is (= "/api/user/current" (:route_template row))))+ (is (= api-key-id (:api_key_id row)))+ (is (= (t2/select-one-fn :user_id :model/ApiKey :id api-key-id) (:user_id row)))+ (is (= (mt/user->id :crowberto) (:created_by_id row))+ "crowberto created the key over the API in do-with-api-key!")+ (is (= "GET" (:http_method row)))+ (is (= 200 (:status row)))+ (is (int? (:duration_ms row)))+ (is (= "metabase-cli" (:client_name row)))+ (testing "embedding_client is absent — the common case, no X-Metabase-Client header sent"+ (is (nil? (:embedding_client row)))))+ (testing "and last_used_at is stamped"+ (is (some? (last-used-at! api-key-id))))))))++(deftest api-key-request-records-embedding-client-test+ (testing "the X-Metabase-Client header, when present, is recorded alongside client_name"+ (do-with-api-key!+ (fn [unmasked-key api-key-id]+ (client/client :get 200 "user/current"+ (update (api-key-headers unmasked-key) :request-options+ update :headers assoc "x-metabase-client" "embedding-sdk-react"))+ (let [[row] (rows-for! api-key-id)]+ (is (= "embedding-sdk-react" (:embedding_client row)))+ (testing "client_name stays the User-Agent classification — unaffected by the header"+ (is (= "metabase-cli" (:client_name row)))))))))++(deftest api-key-request-records-embedding-hostname-test+ (testing "the embed referrer header, when present, is parsed into embedding_hostname alongside embedding_client"+ (do-with-api-key!+ (fn [unmasked-key api-key-id]+ (client/client :get 200 "user/current"+ (update (api-key-headers unmasked-key) :request-options+ update :headers assoc+ "x-metabase-client" "embedding-sdk-react"+ "x-metabase-embed-referrer" "https://example.com/app"))+ (let [[row] (rows-for! api-key-id)]+ (is (= "embedding-sdk-react" (:embedding_client row)))+ (is (= "example.com" (:embedding_hostname row))))))))++(deftest api-key-request-records-the-template-not-the-uri-test+ (testing "a route with a path param records the template, never the concrete id"+ (do-with-api-key!+ (fn [unmasked-key api-key-id]+ ;; also the error path: `check-404` *throws*, so this response is built by `catch-api-exceptions` from the+ ;; exception rather than by the endpoint. The route template still has to survive that.+ (client/client :get 404 "card/99999999" (api-key-headers unmasked-key))+ (let [[row] (rows-for! api-key-id)]+ (is (= "/api/card/:id" (:route_template row)))+ (is (= 404 (:status row))))))))++(deftest session-authenticated-requests-are-not-recorded-test+ (testing "requests authenticated any other way record nothing at all"+ (do-with-api-key!+ (fn [_unmasked-key api-key-id]+ (let [rows-before (t2/count :model/ApiKeyUsageLog)]+ (mt/user-http-request :crowberto :get 200 "user/current")+ (is (= rows-before (t2/count :model/ApiKeyUsageLog)))+ (is (empty? (rows-for! api-key-id))))))))++(deftest unmatched-route-is-recorded-test+ (testing "a request that matches no endpoint is still a real event — recorded with the unmatched sentinel,+ not dropped"+ (do-with-api-key!+ (fn [unmasked-key api-key-id]+ (client/client :get 404 "user/current/not-a-real-route" (api-key-headers unmasked-key))+ (let [[row] (rows-for! api-key-id)]+ (is (= "(unmatched)" (:route_template row)))+ (is (= 404 (:status row))))+ (testing "and the key is still marked as used — the request did authenticate"+ (is (some? (last-used-at! api-key-id))))))))diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.cljnew file mode 100644index 00000000000..173cd286dc6--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.clj@@ -0,0 +1,499 @@+(ns metabase-enterprise.api-keys.usage-test+ "Tests for [[metabase.api-keys.usage/record-api-key-usage!]] — one lean `api_key_usage_log` row per+ API-key-authenticated request, plus the `api_key.last_used_at` stamp. Exercises the `defenterprise`+ dispatch via the OSS entry point in `metabase.api-keys.usage`. Collection runs on every EE instance+ (`:feature :none`); PII is gated by `analytics-pii-retention-enabled` (itself `:audit-app`-gated).+ Both writes coalesce in memory between scheduled flushes — [[record!]] forces the usage-log flush on+ every call; `last_used_at` tests call the private `flush-last-used-at!` explicitly, since some of+ them specifically check the pre-flush state. `synchronous-batch-updates` no longer applies to either+ write — it only ever affected Grouper, which neither path uses anymore."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [java-time.api :as t]+ [metabase-enterprise.api-keys.usage :as ee-usage]+ [metabase.api-keys.core :as api-keys]+ [metabase.api-keys.usage :as usage]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [metabase.util :as u]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(use-fixtures :once (fixtures/initialize :db :test-users))++(defn- unique-route+ "A route template unique to one test, so rows can be found and cleaned up without colliding with+ anything else in the table."+ []+ (str "/api/usage-test/" (mt/random-name) "/:id"))++(defn- row-for [route]+ (t2/select-one :model/ApiKeyUsageLog :route_template route))++(defn- last-used-at [api-key-id]+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))++(defn- request-info+ "A complete [[record!]] input map, overridable per test."+ [route & {:as overrides}]+ (merge {:api-key-id 1234+ :user-id (mt/user->id :rasta)+ :creator-id (mt/user->id :crowberto)+ :route-template route+ :http-method "GET"+ :status 200+ :duration-ms 12+ :user-agent "curl/8.4.0"+ :ip-address "203.0.113.7"}+ overrides))++(defn- record!+ "Translates a flat [[request-info]] map into the real `(request response extra-info)` shape the+ recorder now takes, invokes it, then forces the usage-log row to flush — it coalesces in memory+ between scheduled flushes, so a row written moments ago may not be on disk yet. (`last_used_at` is+ not flushed here — tests that need it call the private `flush-last-used-at!` explicitly, since some+ of them specifically check the pre-flush state.)"+ [{:keys [api-key-id user-id creator-id route-template http-method status duration-ms occurred-at+ user-agent ip-address embedding-client embedding-hostname]}]+ (usage/record-api-key-usage!+ {:api-key-id api-key-id+ :metabase-user-id user-id+ :api-key-creator-id creator-id+ :request-method (some-> http-method u/lower-case-en keyword)+ :headers (cond-> {}+ user-agent (assoc "user-agent" user-agent)+ ip-address (assoc "x-forwarded-for" ip-address)+ embedding-client (assoc "x-metabase-client" embedding-client)+ embedding-hostname (assoc "x-metabase-embed-referrer" (str "https://" embedding-hostname)))}+ {:status status}+ {:route-template route-template+ :duration-ms duration-ms+ :occurred-at occurred-at})+ (#'ee-usage/flush-usage-logs!))++;;; ------------------------------------------- usage log row --------------------------------------------++(deftest record-api-key-usage!-writes-row-test+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled true]+ (let [route (unique-route)]+ (try+ (record! (request-info route+ :http-method "POST"+ :status 201))+ (let [row (row-for route)]+ (testing "non-PII columns"+ (is (= 1234 (:api_key_id row)))+ (is (= (mt/user->id :rasta) (:user_id row)))+ (is (= (mt/user->id :crowberto) (:created_by_id row)))+ (is (= "POST" (:http_method row)))+ (is (= 201 (:status row)))+ (is (= 12 (:duration_ms row)))+ (is (some? (:occurred_at row)))+ (is (= "curl" (:client_name row))))+ (testing "PII columns populated when retention is on"+ (is (= "curl/8.4.0" (:user_agent row)))+ (is (= "203.0.113.7" (:ip_address row)))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))++(deftest record-api-key-usage!-occurred-at-is-caller-supplied-test+ (testing "occurred_at reflects the caller's timestamp, not whenever the batch happens to flush"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.+ occurred-at (-> (t/instant) (t/minus (t/hours 3)) (t/truncate-to :micros)+ (t/offset-date-time (t/zone-offset 0)))]+ (try+ (record! (request-info route :occurred-at occurred-at))+ (is (= occurred-at (:occurred_at (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-pii-gate-test+ (testing "ip_address / user_agent are stored only when retention is on"+ (mt/with-premium-features #{:audit-app}+ (testing "retention on: PII columns populated"+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled true]+ (let [route (unique-route)]+ (try+ (record! (request-info route))+ (let [row (row-for route)]+ (is (= "curl/8.4.0" (:user_agent row)))+ (is (= "203.0.113.7" (:ip_address row))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))+ (testing "retention off: the row is still written, PII columns stay null"+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled false]+ (let [route (unique-route)]+ (try+ (record! (request-info route))+ (let [row (row-for route)]+ (is (some? row))+ (is (= 200 (:status row)))+ (is (nil? (:user_agent row)))+ (is (nil? (:ip_address row))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))))++(deftest record-api-key-usage!-client-name-is-never-gated-test+ (testing "client_name is classified from user-agent and recorded even when PII retention is off"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled false]+ (let [route (unique-route)]+ (try+ (record! (request-info route :user-agent "metabase-cli/1.2.3"))+ (let [row (row-for route)]+ (is (= "metabase-cli" (:client_name row)))+ (testing "but the raw user_agent stays gated"+ (is (nil? (:user_agent row)))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-embedding-client-test+ (testing "embedding_client carries the raw X-Metabase-Client header, never gated, unlike client_name it's not classified"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled false]+ (let [route (unique-route)]+ (try+ (record! (request-info route :embedding-client "embedding-sdk-react"))+ (is (= "embedding-sdk-react" (:embedding_client (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))+ (testing "absent when not passed — the common case for API-key traffic"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)]+ (try+ (record! (request-info route))+ (is (nil? (:embedding_client (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-truncates-embedding-client-test+ (testing "an over-long embedding_client is truncated to the column width so the row still records"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)+ long-value (apply str (repeat 300 \x))]+ (try+ (record! (request-info route :embedding-client long-value))+ (is (= 255 (count (:embedding_client (row-for route)))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-embedding-hostname-test+ (testing "embedding_hostname carries the parsed hostname, never gated"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true+ analytics-pii-retention-enabled false]+ (let [route (unique-route)]+ (try+ (record! (request-info route :embedding-hostname "example.com"))+ (is (= "example.com" (:embedding_hostname (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))+ (testing "absent when not passed"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)]+ (try+ (record! (request-info route))+ (is (nil? (:embedding_hostname (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-truncates-embedding-hostname-test+ (testing "an over-long embedding_hostname is truncated to the column width so the row still records"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)+ long-value (apply str (repeat 600 \x))]+ (try+ (record! (request-info route :embedding-hostname long-value))+ (is (= 512 (count (:embedding_hostname (row-for route)))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-unrecognized-user-agent-is-other-test+ (testing "an unrecognized or absent User-Agent classifies as \"other\""+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)]+ (try+ (record! (request-info route :user-agent nil))+ (is (= "other" (:client_name (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-truncates-route-template-test+ (testing "an over-long route_template is truncated to the column width so the row still records"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (apply str (unique-route) (repeat 300 \x))]+ (try+ (record! (request-info route))+ (is (= 255 (count (:route_template (row-for (subs route 0 255))))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template (subs route 0 255)))))))))++(deftest record-api-key-usage!-unmatched-route-is-recorded-test+ (testing "a nil route-template on a 404 is recorded with the unmatched sentinel, not dropped"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ ;; a dedicated api-key-id, since the stored route_template is the sentinel rather than+ ;; `route` — this test can't find its row by route like the others do+ (let [api-key-id 424242]+ (try+ (record! (request-info (unique-route) :api-key-id api-key-id :route-template nil :status 404))+ (is (= "(unmatched)"+ (:route_template (t2/select-one :model/ApiKeyUsageLog :api_key_id api-key-id))))+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id))))))))++(deftest record-api-key-usage!-non-404-nil-route-template-is-recorded-test+ (testing "a nil route-template on anything other than a 404 (health checks, docs, a 402 raised+ before routing) is recorded with a different sentinel — it isn't someone probing for a+ nonexistent route, so labeling it the same way would be misleading"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [api-key-id 434343]+ (try+ (record! (request-info (unique-route) :api-key-id api-key-id :route-template nil :status 200))+ (is (= "(no-template)"+ (:route_template (t2/select-one :model/ApiKeyUsageLog :api_key_id api-key-id))))+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id))))))))++(deftest record-api-key-usage!-drops-incomplete-log-row-test+ (testing "a row missing a NOT NULL value is dropped rather than queued, so it can't sink its batch"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)]+ (try+ (record! (request-info route :api-key-id nil))+ (is (nil? (row-for route)))+ (testing "a complete row still records afterwards"+ (record! (request-info route))+ (is (some? (row-for route))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-collection-runs-without-audit-app-test+ (testing "collection happens on any EE instance (:feature :none), but PII stays null without :audit-app"+ (mt/with-premium-features #{}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (let [route (unique-route)]+ (try+ (record! (request-info route))+ (let [row (row-for route)]+ (testing "non-PII row is written"+ (is (some? row))+ (is (= (mt/user->id :rasta) (:user_id row))))+ (testing "PII is null because retention can't be enabled without :audit-app"+ (is (nil? (:user_agent row)))+ (is (nil? (:ip_address row)))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-log-row-is-best-effort-test+ (testing "a failed usage-log insert is swallowed and never propagates to the caller"+ (mt/with-premium-features #{:audit-app}+ (mt/with-temporary-setting-values [synchronous-batch-updates true]+ (mt/with-dynamic-fn-redefs [t2/insert! (fn [& _] (throw (ex-info "boom" {})))]+ (is (nil? (record! (request-info (unique-route))))))))))++(deftest offer-usage-log!-drops-rows-once-full-test+ (testing "a full pending queue drops a new row rather than blocking the request thread for room"+ (let [pending (deref #'ee-usage/pending-usage-logs)+ original @pending]+ (try+ (reset! pending (vec (repeat 500 {:dummy true})))+ (#'ee-usage/offer-usage-log! {:dummy true})+ (is (= 500 (count @pending)) "the queue was already at capacity, so the new row was dropped")+ (finally (reset! pending original))))))++(deftest offer-usage-log!-counts-drops-for-flush-to-log-once-test+ (testing "drops accumulate in a counter that flush-usage-logs! takes and resets, rather than each drop logging on its own"+ (let [pending (deref #'ee-usage/pending-usage-logs)+ dropped (deref #'ee-usage/dropped-usage-log-count)+ original-pending @pending+ original-dropped @dropped]+ (try+ (reset! pending (vec (repeat 500 {:dummy true})))+ (reset! dropped 0)+ (#'ee-usage/offer-usage-log! {:dummy true})+ (#'ee-usage/offer-usage-log! {:dummy true})+ (is (= 2 @dropped) "two dropped rows are counted, not logged individually")+ (reset! pending [])+ (mt/with-log-messages-for-level [messages [metabase-enterprise.api-keys.usage :warn]]+ (#'ee-usage/flush-usage-logs!)+ (is (=? [{:level :warn, :message #"^Dropped 2 API key usage log rows.*"}]+ (messages))+ "the two drops are logged once, as a single total, not once per drop"))+ (is (= 0 @dropped) "flush takes and resets the counter after logging the total once")+ (finally+ (reset! pending original-pending)+ (reset! dropped original-dropped))))))++;;; ------------------------------------------ last_used_at --------------------------------------------++(deftest record-api-key-usage!-stamps-last-used-at-test+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_1234567890"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ (let [updated-at-before (t2/select-one-fn :updated_at :model/ApiKey :id api-key-id)+ route (unique-route)]+ (try+ (is (nil? (last-used-at api-key-id)))+ (record! (request-info route :api-key-id api-key-id))+ (testing "not written until the next flush — coalesced in memory, not a synchronous write"+ (is (nil? (last-used-at api-key-id))))+ (#'ee-usage/flush-last-used-at!)+ (is (some? (last-used-at api-key-id)))+ (testing "the stamp bypasses the model hooks, so updated_at never moves"+ (is (= updated-at-before+ (t2/select-one-fn :updated_at :model/ApiKey :id api-key-id))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))++(deftest record-api-key-usage!-coalesces-last-used-at-before-flush-test+ (testing "multiple events for the same key before a flush collapse to the max timestamp, one UPDATE"+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_3333333333"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.+ (let [now #(-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))+ earlier (t/minus (now) (t/minutes 5))+ later (now)+ route (unique-route)]+ (try+ ;; out of order on purpose — the later timestamp must win regardless of arrival order+ (record! (request-info route :api-key-id api-key-id :occurred-at later))+ (record! (request-info route :api-key-id api-key-id :occurred-at earlier))+ (#'ee-usage/flush-last-used-at!)+ (is (= later (last-used-at api-key-id)))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-last-used-at-independent-per-key-test+ (testing "one key's event does not affect another key's last_used_at"+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {key-1 :id} {::api-keys/unhashed-key "mb_1111111111"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}+ :model/ApiKey {key-2 :id} {::api-keys/unhashed-key "mb_2222222222"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ (let [route (unique-route)]+ (try+ (record! (request-info route :api-key-id key-1))+ (#'ee-usage/flush-last-used-at!)+ (is (some? (last-used-at key-1)))+ (is (nil? (last-used-at key-2)))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest record-api-key-usage!-last-used-at-is-best-effort-test+ (testing "a nil id skips the write entirely"+ (mt/with-premium-features #{}+ (is (nil? (record! (request-info (unique-route) :api-key-id nil))))))+ (testing "a failed flush is swallowed rather than thrown"+ (mt/with-premium-features #{}+ (let [route (unique-route)]+ (try+ (record! (request-info route :api-key-id Integer/MAX_VALUE))+ (mt/with-dynamic-fn-redefs [t2/query (fn [& _] (throw (ex-info "boom" {})))]+ (is (nil? (#'ee-usage/flush-last-used-at!))))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))++(deftest flush-last-used-at!-requeues-skipped-keys-test+ (testing "a key the DB layer skips (e.g. a busy row) goes back into the pending map, merged against+ newer arrivals rather than overwritten by the stale retry"+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_4444444444"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.+ (let [now #(-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))+ earlier (now)+ later (t/plus earlier (t/seconds 5))+ route (unique-route)]+ (try+ (record! (request-info route :api-key-id api-key-id :occurred-at earlier))+ ;; simulate the lock step finding every key busy: nothing is actually written+ (mt/with-dynamic-fn-redefs [api-keys/update-api-keys-last-used-at! (fn [id->timestamp] id->timestamp)]+ (#'ee-usage/flush-last-used-at!))+ (is (nil? (last-used-at api-key-id)) "still pending — the redef simulated a busy row")+ ;; a fresher event lands before the key is retried+ (record! (request-info route :api-key-id api-key-id :occurred-at later))+ (#'ee-usage/flush-last-used-at!)+ (is (= later (last-used-at api-key-id)) "the retried write kept the newer of the two timestamps")+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++;;; -------------------------------------------- concurrency --------------------------------------------+;; Real threads, not `synchronous-batch-updates` — exercising the actual concurrent paths (many request+;; threads racing the in-memory queues, then a flush) rather than simulating them serially.++(deftest concurrent-last-used-at-stamps-keep-the-newest-timestamp-test+ (testing "many concurrent stamps for one key never lose the newest timestamp to a race"+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_5555555555"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ (let [route (unique-route)+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.+ base (-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))+ n 50+ timestamps (mapv #(t/plus base (t/seconds %)) (range n))+ latest (last timestamps)]+ (try+ (run! deref+ (mapv (fn [ts] (future (record! (request-info route :api-key-id api-key-id :occurred-at ts))))+ (shuffle timestamps)))+ (#'ee-usage/flush-last-used-at!)+ (is (= latest (last-used-at api-key-id)))+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))++(deftest concurrent-usage-log-offers-do-not-lose-rows-test+ (testing "many concurrent usage-log rows below capacity are never lost to a race in the pending queue"+ (mt/with-premium-features #{:audit-app}+ (let [api-key-id 636363+ n 50+ routes (mapv #(str (unique-route) "-" %) (range n))]+ (try+ (run! deref (mapv (fn [route] (future (record! (request-info route :api-key-id api-key-id)))) routes))+ (#'ee-usage/flush-usage-logs!)+ (is (= n (t2/count :model/ApiKeyUsageLog :api_key_id api-key-id)))+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id)))))))++;;; ------------------------------------------ flush scheduling ------------------------------------------+;; JVM-local, not Quartz — see `start-flush!`'s docstring. Both writes coalesce in the same shared atoms+;; every other test in this namespace uses, so `stop-flush!` (called liberally below) is just the same+;; force-flush every other test already does, wrapped with idempotent executor teardown.++(deftest start-flush!-is-idempotent-test+ (testing "a second call shuts down the executor it just created instead of replacing the one already running"+ (#'ee-usage/stop-flush!) ; clean slate, in case an earlier boot already started the real flush loop+ (try+ (is (true? (#'ee-usage/start-flush!)) "the first call creates the executor")+ (is (false? (#'ee-usage/start-flush!)) "a second call is a no-op")+ (finally (#'ee-usage/stop-flush!)))))++(deftest stop-flush!-force-flushes-pending-state-test+ (testing "stop-flush! flushes a pending last_used_at stamp without waiting for the interval"+ (mt/with-premium-features #{}+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_9999999999"+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)}]+ (let [route (unique-route)]+ (try+ (is (nil? (last-used-at api-key-id)))+ (record! (request-info route :api-key-id api-key-id))+ (is (nil? (last-used-at api-key-id)) "not flushed yet — still coalescing")+ (#'ee-usage/stop-flush!)+ (is (some? (last-used-at api-key-id)) "stop-flush! force-flushed it")+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.cljnew file mode 100644index 00000000000..ede1af43759--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.clj@@ -0,0 +1,183 @@+(ns metabase-enterprise.api-keys.v-api-key-usage-test+ "Tests for the `v_api_key_usage` SQL view. Client identity and PII are stored on each request row;+ the view derives `client_display_name` from it. Two separate identities: `actor_user_id` is the+ row's own `user_id` (the key's synthetic service-account user, used for permission checks, never a+ real person) — `creator_id`/`creator_display_name`/`group_name` come from `created_by_id` (the real+ human who made the key) and the key's own group (via the key's synthetic user, not the creator's+ memberships — a key has one group, a creator may have several). The view LEFT JOINs api_key and+ core_user on purpose — `api_key_usage_log` has no foreign keys, so rows outlive a deleted key or+ user."+ (:require+ [clojure.test :refer [deftest is testing use-fixtures]]+ [java-time.api :as t]+ [metabase.api-keys.core :as api-keys]+ [metabase.api-keys.usage :as api-keys.usage]+ [metabase.app-db.core :as mdb]+ [metabase.permissions.core :as perms]+ [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_api_key_usage, returning only rows for the given log ids."+ [log-ids]+ (t2/query {:select [:*]+ :from [:v_api_key_usage]+ :where [:in :log_id log-ids]}))++(defn- find-row [rows log-id]+ (some #(when (= (:log_id %) log-id) %) rows))++(defn- log-row+ "A minimal `api_key_usage_log` row, with every NOT NULL column filled in."+ [m]+ (merge {:api_key_id Integer/MAX_VALUE+ :route_template "/api/card/:id"+ :http_method "GET"+ :status 200+ :duration_ms 12+ :client_name "other"+ :occurred_at (t/offset-date-time)}+ m))++(deftest joins-and-derived-columns-test+ (testing "the view separates the key's actor (synthetic user) from its creator, and group_name+ follows the actor, not the creator"+ (mt/with-temp+ [;; the creator: a real human, in a different group from the key itself+ :model/User {creator-id :id} {:first_name "Ada" :last_name "Lovelace"}+ :model/PermissionsGroup {creator-group :id} {:name "Admins"}+ :model/PermissionsGroupMembership _ {:user_id creator-id :group_id creator-group}+ ;; the key's own synthetic service-account user, in its own (different) group+ :model/User {actor-id :id} {:first_name "key" :last_name "service-account"}+ :model/PermissionsGroup {key-group :id} {:name "Analysts"}+ :model/PermissionsGroupMembership _ {:user_id actor-id :group_id key-group}+ :model/ApiKey {key-id :id} {::api-keys/unhashed-key "mb_1234567890"+ :name "Reporting key"+ :user_id actor-id+ :creator_id creator-id+ :updated_by_id creator-id}+ :model/ApiKeyUsageLog {log-id :id} (log-row {:api_key_id key-id+ :user_id actor-id+ :created_by_id creator-id+ :route_template "/api/card/:id"+ :http_method "POST"+ :status 201+ :duration_ms 42+ :client_name "metabase-cli"+ :embedding_client "embedding-sdk-react"+ :embedding_hostname "example.com"+ :ip_address "10.0.0.7"+ :user_agent "metabase-cli/1.2.3"})]+ (is (=? {:route_template "/api/card/:id"+ :http_method "POST"+ :status 201+ :duration_ms 42+ :api_key_id key-id+ :api_key_name "Reporting key"+ :actor_user_id actor-id+ :creator_id creator-id+ :creator_display_name "Ada Lovelace"+ :group_name "Analysts"+ :client_name "metabase-cli"+ :client_display_name "Metabase CLI"+ :embedding_client "embedding-sdk-react"+ :embedding_hostname "example.com"+ :ip_address "10.0.0.7"+ :user_agent "metabase-cli/1.2.3"}+ (find-row (query-view [log-id]) log-id))))))++(deftest group-name-falls-back-to-all-users-test+ (testing "a key whose actor belongs to no group but All Users gets \"All Users\", not a null group_name"+ (mt/with-temp+ [;; every new non-tenant user is added to All Users on insert — no explicit membership needed+ :model/User {creator-id :id} {}+ :model/User {actor-id :id} {}+ :model/ApiKey {key-id :id} {::api-keys/unhashed-key "mb_0000000000"+ :name "All Users only key"+ :user_id actor-id+ :creator_id creator-id+ :updated_by_id creator-id}+ :model/ApiKeyUsageLog {log-id :id} (log-row {:api_key_id key-id+ :user_id actor-id+ :created_by_id creator-id})]+ (is (= (:name (perms/all-users-group))+ (:group_name (find-row (query-view [log-id]) log-id)))))))++(deftest missing-key-and-creator-test+ (testing "a row whose key/creator are gone (or were never set) survives, with null join columns"+ (mt/with-temp+ [:model/ApiKeyUsageLog {orphan-id :id} (log-row {:api_key_id Integer/MAX_VALUE+ :user_id Integer/MAX_VALUE+ :created_by_id nil})]+ (let [row (find-row (query-view [orphan-id]) orphan-id)]+ (is (some? row) "the row is not dropped")+ (is (=? {:route_template "/api/card/:id"+ :api_key_id Integer/MAX_VALUE+ :api_key_name nil+ :creator_id nil+ :creator_display_name nil+ :group_name nil}+ row))))))++(deftest pii-columns-passthrough-test+ (testing "ip_address / user_agent pass through as null when PII collection was off at write time"+ (mt/with-temp+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:ip_address nil :user_agent nil})]+ (is (=? {:ip_address nil :user_agent nil :embedding_client nil}+ (find-row (query-view [log-id]) log-id))))))++(deftest creator-display-name-falls-back-to-email-test+ (testing "a creator with no last name falls back to their email"+ (mt/with-temp+ [:model/User {creator-id :id, email :email} {:first_name "Ada" :last_name nil}+ :model/ApiKeyUsageLog {log-id :id} (log-row {:created_by_id creator-id})]+ (is (=? {:creator_display_name email}+ (find-row (query-view [log-id]) log-id))))))++;; Guard the hand-maintained client_name -> client_display_name coupling. These pairs must stay in+;; sync with the CASE in the v_api_key_usage view SQL and `supported-client-keys` / `detect-client`+;; in metabase.api-keys.usage; drift on either side breaks this test rather than silently+;; mislabeling clients.+(def ^:private client-name->display-name+ {"metabase-cli" "Metabase CLI"+ "curl" "curl"+ "postman" "Postman"+ "python-requests" "Python"+ "r" "R"+ "node" "Node.js"+ "other" "Other"})++(deftest client-display-name-mapping-test+ (testing "the mapping covers exactly the canonical client keys plus the \"other\" catch-all"+ (is (= (conj api-keys.usage/supported-client-keys "other")+ (set (keys client-name->display-name)))))+ (testing "every client_name maps to the expected display name"+ (doseq [[client-name expected] client-name->display-name]+ (mt/with-temp+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:client_name client-name})]+ (is (= expected (:client_display_name (find-row (query-view [log-id]) log-id)))+ (format "client_name %s should map to %s" (pr-str client-name) (pr-str expected))))))+ (testing "an unrecognized client_name passes through unchanged"+ (mt/with-temp+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:client_name "brand-new-client"})]+ (is (= "brand-new-client"+ (:client_display_name (find-row (query-view [log-id]) log-id)))))))++(deftest creator-display-name-has-a-plain-string-type-on-h2-test+ (testing "creator_display_name isn't typed VARCHAR_IGNORECASE on H2 (#EMB-2154)"+ ;; core_user.email is declared VARCHAR_IGNORECASE on H2 for case-insensitive lookups, and+ ;; COALESCE(name-concat, email) inherits that type. Metabase's H2 type mapper doesn't+ ;; recognize VARCHAR_IGNORECASE, so it falls back to an unknown column type, and+ ;; metabase-lib silently excludes unknown-typed columns from the FE's sortable columns —+ ;; the view's own `CAST(... AS VARCHAR)` is what keeps this column a plain, sortable string.+ (when (= (mdb/db-type) :h2)+ (let [column-type (-> (t2/query "SELECT DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS+ WHERE TABLE_NAME = 'V_API_KEY_USAGE'+ AND COLUMN_NAME = 'CREATOR_DISPLAY_NAME'")+ first :data_type)]+ (is (not= "VARCHAR_IGNORECASE" column-type))))))diff --git a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.cljindex b9d5276befd..d447052bfbc 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@@ -41,6 +41,7 @@:model/AnalysisFinding:model/AnalysisFindingError:model/ApiKey+ :model/ApiKeyUsageLog:model/AuthIdentity:model/ImplicitAction:model/QueryActiondiff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsxindex 18dcafacc35..96393c1735a 100644--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx@@ -1,3 +1,4 @@+import type { ReactNode } from "react";import { useMemo, useState } from "react";import { P, match } from "ts-pattern";import { t } from "ttag";@@ -214,6 +215,11 @@ type ConversationFiltersProps = {groupOptions: { value: string; label: string }[];tenantOptions: { value: string; label: string }[];hasTenants: boolean;+ /** Hides the user select for pages where filtering by user isn't a meaningful concept. */+ hasUsers?: boolean;+ /** Rendered right after the Group select, before User/Date — for a caller-specific filter that+ * belongs grouped with Group rather than after the rest of this shared bar. */+ extraFilter?: ReactNode;};export function ConversationFilters({@@ -230,6 +236,8 @@ export function ConversationFilters({groupOptions,tenantOptions,hasTenants,+ hasUsers = true,+ extraFilter,}: ConversationFiltersProps) {return (<Flex gap="sm" wrap="wrap" align="center">@@ -256,15 +264,18 @@ export function ConversationFilters({bdrs="xs"data-testid="conversation-filters-group-select"/>- <Select- data={[{ value: "", label: t`All users` }, ...userOptions]}- value={user ?? ""}- onChange={(val) => onUserChange(val === "" ? null : val)}- searchable- w={FILTER_WIDTH}- bdrs="xs"- data-testid="conversation-filters-user-select"- />+ {extraFilter}+ {hasUsers && (+ <Select+ data={[{ value: "", label: t`All users` }, ...userOptions]}+ value={user ?? ""}+ onChange={(val) => onUserChange(val === "" ? null : val)}+ searchable+ w={FILTER_WIDTH}+ bdrs="xs"+ data-testid="conversation-filters-user-select"+ />+ )}<ConversationDateFilter value={date} onChange={onDateChange} /></Flex>);diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.tsindex a009fac8ae7..cd1c5fb1b0f 100644--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts@@ -19,6 +19,8 @@ type UseAuditTableResult = {provider: MetadataProvider | null;table: TableMetadata | CardMetadata | null;isLoading: boolean;+ /** A failed metadata request. Without it, a failure looks the same as a view that doesn't exist. */+ error: unknown;};/**@@ -29,8 +31,11 @@ type UseAuditTableResult = {* (case-insensitive to handle H2 uppercasing).*/export function useAuditTable(viewName: string): UseAuditTableResult {- const { data: database, isLoading: isLoadingTables } =- useGetDatabaseMetadataQuery({ id: AUDIT_DB_ID, skip_fields: true });+ const {+ data: database,+ isLoading: isLoadingTables,+ error: databaseError,+ } = useGetDatabaseMetadataQuery({ id: AUDIT_DB_ID, skip_fields: true });const tableId = useMemo(() => {const lowerName = viewName.toLowerCase();@@ -55,9 +60,8 @@ export function useAuditTable(viewName: string): UseAuditTableResult {[provider, table],);- const { data: queryMetadata } = useGetAdhocQueryMetadataQuery(- datasetQuery ?? skipToken,- );+ const { data: queryMetadata, error: queryMetadataError } =+ useGetAdhocQueryMetadataQuery(datasetQuery ?? skipToken);const isLoadingFields = table != null && queryMetadata == null;@@ -65,5 +69,6 @@ export function useAuditTable(viewName: string): UseAuditTableResult {provider,table: isLoadingFields ? null : table,isLoading: isLoadingTables || isLoadingFields,+ error: databaseError ?? queryMetadataError,};}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsxnew file mode 100644index 00000000000..00ae7cca2ff--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsx@@ -0,0 +1,44 @@+import fetchMock from "fetch-mock";++import { renderHookWithProviders, waitFor } from "__support__/ui";+import { createMockDatabase } from "metabase-types/api/mocks";++import { AUDIT_DB_ID } from "../constants";++import { useAuditTable } from "./useAuditTable";++const METADATA_URL = `path:/api/database/${AUDIT_DB_ID}/metadata`;++describe("useAuditTable", () => {+ it("returns the error when the metadata request fails", async () => {+ fetchMock.get(METADATA_URL, {+ status: 500,+ body: { message: "boom" },+ });++ const { result } = renderHookWithProviders(+ () => useAuditTable("v_api_key_usage"),+ {},+ );++ await waitFor(() => expect(result.current.isLoading).toBe(false));+ expect(result.current.error).toBeDefined();+ expect(result.current.table).toBeNull();+ });++ it("returns no error when the lookup succeeds but the view isn't there", async () => {+ fetchMock.get(+ METADATA_URL,+ createMockDatabase({ id: AUDIT_DB_ID, tables: [] }),+ );++ const { result } = renderHookWithProviders(+ () => useAuditTable("v_api_key_usage"),+ {},+ );++ await waitFor(() => expect(result.current.isLoading).toBe(false));+ expect(result.current.error).toBeUndefined();+ expect(result.current.table).toBeNull();+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsxnew file mode 100644index 00000000000..c58ff74f2ce--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsx@@ -0,0 +1,249 @@+import { useMemo } from "react";+import { t } from "ttag";++import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";+import { DateTime } from "metabase/common/components/DateTime";+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";+import { MonitorEmptyState } from "metabase/monitor/components/MonitorEmptyState";+import {+ Box,+ Card,+ Ellipsified,+ Flex,+ Skeleton,+ Text,+ TreeTable,+ type TreeTableColumnDef,+ TreeTableSkeleton,+ useTreeTableInstance,+} from "metabase/ui";+import { EMPTY_CELL_PLACEHOLDER } from "metabase/utils/constants";+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import {+ apiKeyMatchesScope,+ buildKeyActivityQuery,+} from "metabase-enterprise/monitor/api-key-usage/query-utils";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";+import type { ApiKey } from "metabase-types/api";++const getNodeId = (apiKey: ApiKey) => String(apiKey.id);++type ApiKeyActivityRow = ApiKey;++/** Most recently active first, keys with no activity in the window last. */+export function compareByLastUsedAtDesc(+ a: ApiKeyActivityRow,+ b: ApiKeyActivityRow,+): number {+ if (a.last_used_at == null) {+ return b.last_used_at == null ? 0 : 1;+ }+ if (b.last_used_at == null) {+ return -1;+ }+ return b.last_used_at.localeCompare(a.last_used_at);+}++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++type Props = DataSources &+ ApiKeyUsageFilters & {+ title: string;+ h?: number;+ };++type InnerProps = ApiKeyUsageFilters & {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+ title: string;+ h: number;+};++const TABLE_HEIGHT = 500;++/**+ * Per-key activity table: name, group, and most recent activity for every API key matching the+ * page's API key/user/group filters, most recently active first. Which keys appear is decided by+ * the keys' own metadata from `GET /api/api-key` (id/creator/group), not by activity — a key with+ * no activity in the selected date window still shows up, with a blank "Last used" cell. The+ * timestamp itself comes from a `MAX(occurred_at)` breakout over the audit view, scoped to the+ * same filters as the rest of the page, so it only reflects activity inside the current window.+ */+export function ApiKeyActivityTable({+ provider,+ table,+ groupMembersTable,+ h = TABLE_HEIGHT,+ ...filters+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <ApiKeyActivityTableInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ h={h}+ {...filters}+ />+ );+}++function ApiKeyActivityTableInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ title,+ h,+}: InnerProps) {+ const {+ data: apiKeys,+ isLoading: isLoadingKeys,+ error: keysError,+ } = useListApiKeysQuery();++ const activityQuery = useMemo(+ () =>+ buildKeyActivityQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ }),+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],+ );+ const {+ data: activityData,+ isFetching: isFetchingActivity,+ error: activityError,+ } = useAdhocBreakoutQuery(activityQuery);++ // Maps each key with activity in the filtered window to the timestamp of its latest call.+ const lastActivityByKeyId = useMemo(() => {+ const cols = activityData?.data?.cols ?? [];+ const rows = activityData?.data?.rows ?? [];+ const keyIdIndex = cols.findIndex(+ (col) => col.name?.toLowerCase() === "api_key_id",+ );+ const lastActivityIndex = cols.findIndex(+ (col) => col.source === "aggregation",+ );+ const entries: [number, string | null][] =+ keyIdIndex < 0 || lastActivityIndex < 0+ ? []+ : rows.map((row) => [+ Number(row[keyIdIndex]),+ row[lastActivityIndex] == null+ ? null+ : String(row[lastActivityIndex]),+ ]);+ return new Map(entries);+ }, [activityData]);++ const rows = useMemo<ApiKeyActivityRow[] | undefined>(+ () =>+ apiKeys+ ?.filter((apiKey) =>+ apiKeyMatchesScope(apiKey, { apiKeyId, userId, groupId }),+ )+ .map((apiKey) => ({+ ...apiKey,+ last_used_at: lastActivityByKeyId.get(apiKey.id) ?? undefined,+ }))+ .sort(compareByLastUsedAtDesc),+ [apiKeys, apiKeyId, userId, groupId, lastActivityByKeyId],+ );++ const columns = useMemo<TreeTableColumnDef<ApiKeyActivityRow>[]>(+ () => [+ {+ id: "name",+ header: t`Key name`,+ minWidth: 120,+ accessorFn: (apiKey) => apiKey.name,+ cell: ({ row }) => <Ellipsified>{row.original.name}</Ellipsified>,+ },+ {+ id: "group",+ header: t`Group`,+ minWidth: 100,+ accessorFn: (apiKey) => apiKey.group?.name,+ cell: ({ row }) => (+ <Ellipsified>{row.original.group?.name}</Ellipsified>+ ),+ },+ {+ id: "last_used_at",+ header: t`Last used`,+ minWidth: 120,+ accessorFn: (apiKey) => apiKey.last_used_at,+ sortUndefined: "last",+ cell: ({ row }) =>+ row.original.last_used_at ? (+ <DateTime value={row.original.last_used_at} />+ ) : (+ EMPTY_CELL_PLACEHOLDER+ ),+ },+ ],+ [],+ );++ const treeTableInstance = useTreeTableInstance<ApiKeyActivityRow>({+ data: rows ?? [],+ columns,+ getNodeId,+ });++ const isLoading = isLoadingKeys || (isFetchingActivity && !activityData);+ const error = keysError ?? activityError;++ return (+ <Card withBorder shadow="none" px="xl" pt="lg" pb="lg" h={h}>+ <Text fw="bold" mb="lg">+ {title}+ </Text>+ <Box+ h="calc(100% - 2rem)"+ style={{ overflow: "auto" }}+ data-testid="api-key-activity-table"+ aria-busy={isLoading}+ >+ {error ? (+ <Flex mih="60%" align="center" justify="center">+ <LoadingAndErrorWrapper loading={false} error={error} />+ </Flex>+ ) : isLoading ? (+ <TreeTableSkeleton+ columnWidths={columns.map(() => 1 / columns.length)}+ />+ ) : (+ <TreeTable+ instance={treeTableInstance}+ hierarchical={false}+ ariaLabel={t`API keys`}+ emptyState={<MonitorEmptyState label={t`No key activity`} />}+ />+ )}+ </Box>+ </Card>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.tsnew file mode 100644index 00000000000..4fb8c0e169a--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.ts@@ -0,0 +1,48 @@+import type { ApiKey } from "metabase-types/api";++import { compareByLastUsedAtDesc } from "./ApiKeyActivityTable";++const apiKey = (id: number, lastUsedAt: string | null): ApiKey => ({+ name: `Key ${id}`,+ id,+ group: { id: 1, name: "All Users" },+ creator_id: 1,+ masked_key: "mb_••••••••1234",+ created_at: "2026-01-01T00:00:00Z",+ updated_at: "2026-01-01T00:00:00Z",+ updated_by: { id: 1, common_name: "Bobby Tables" },+ last_used_at: lastUsedAt,+});++describe("compareByLastUsedAtDesc", () => {+ it("sorts most recently active first", () => {+ const older = apiKey(1, "2026-01-01T00:00:00Z");+ const newer = apiKey(2, "2026-02-01T00:00:00Z");++ expect([older, newer].sort(compareByLastUsedAtDesc)).toEqual([+ newer,+ older,+ ]);+ });++ it("sorts keys with no activity in the window last, regardless of input order", () => {+ const active = apiKey(1, "2026-01-01T00:00:00Z");+ const unused = apiKey(2, null);++ expect([unused, active].sort(compareByLastUsedAtDesc)).toEqual([+ active,+ unused,+ ]);+ expect([active, unused].sort(compareByLastUsedAtDesc)).toEqual([+ active,+ unused,+ ]);+ });++ it("leaves two unused keys in a stable relative order", () => {+ const a = apiKey(1, null);+ const b = apiKey(2, null);++ expect([a, b].sort(compareByLastUsedAtDesc)).toEqual([a, b]);+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsxnew file mode 100644index 00000000000..daca0cc826a--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsx@@ -0,0 +1,48 @@+import { useMemo } from "react";+import { t } from "ttag";++import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";+import { Select } from "metabase/ui";+import { apiKeyMatchesScope } from "metabase-enterprise/monitor/api-key-usage/query-utils";++// Matches the width of the shared ConversationFilters selects it sits alongside.+const FILTER_WIDTH = 205;++type Props = {+ value: string | null;+ onChange: (value: string | null) => void;+ /** Narrows the options to keys in this group — a key belongs to exactly one group. */+ groupId: number | undefined;+};++/**+ * The API key an admin is scoping the page to — the primary dimension of this view (see EMB-2391+ * discussion), kept separate from the shared `ConversationFilters` bar since that component is also+ * used by pages with no notion of an API key.+ */+export function ApiKeyFilterSelect({ value, onChange, groupId }: Props) {+ const { data: apiKeys } = useListApiKeysQuery();++ const options = useMemo(+ () =>+ (apiKeys ?? [])+ .filter((apiKey) => apiKeyMatchesScope(apiKey, { groupId }))+ .map((apiKey) => ({+ value: String(apiKey.id),+ label: apiKey.name,+ })),+ [apiKeys, groupId],+ );++ return (+ <Select+ data={[{ value: "", label: t`All API keys` }, ...options]}+ value={value ?? ""}+ onChange={(val) => onChange(val === "" ? null : val)}+ searchable+ w={FILTER_WIDTH}+ bdrs="xs"+ data-testid="api-key-usage-filter-select"+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsxnew file mode 100644index 00000000000..68ff7ca7fa7--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsx@@ -0,0 +1,142 @@+import { useMemo } from "react";+import { t } from "ttag";++import { Skeleton, useMantineTheme } from "metabase/ui";+import { BreakoutChartCard } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import { buildCountBreakoutQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import { toCountBreakoutRawSeries } from "metabase-enterprise/monitor/api-key-usage/raw-series";+import type {+ CardMetadata,+ MetadataProvider,+ Query,+ TableMetadata,+} from "metabase-lib";+import type { VisualizationDisplay } from "metabase-types/api";++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 &+ ApiKeyUsageFilters & {+ title: string;+ display: VisualizationDisplay;+ /** Column to break down call counts by (e.g. `client_display_name`, `route_template`). */+ breakoutColumn: string;+ maxCategories?: number;+ h?: number;+ };++type InnerProps = ApiKeyUsageFilters & {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+ title: string;+ display: VisualizationDisplay;+ breakoutColumn: string;+ maxCategories: number;+ h: number;+};++/**+ * Single-breakout count chart (e.g. calls by client as a pie, calls by route as a row chart).+ * Renders a skeleton until the audit metadata is loaded, then delegates to the inner component.+ */+export function ApiKeyUsageBreakoutChart({+ provider,+ table,+ groupMembersTable,+ h = DEFAULT_CHART_HEIGHT,+ maxCategories = DEFAULT_MAX_CATEGORIES,+ ...rest+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <ApiKeyUsageBreakoutChartInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ h={h}+ maxCategories={maxCategories}+ {...rest}+ />+ );+}++/**+ * Loaded variant of {@link ApiKeyUsageBreakoutChart}: 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 ApiKeyUsageBreakoutChartInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ title,+ display,+ breakoutColumn,+ maxCategories,+ h,+}: InnerProps) {+ const query = useMemo<Query>(+ () =>+ buildCountBreakoutQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ breakoutColumn,+ }),+ [+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ breakoutColumn,+ ],+ );++ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);+ const { themeColor } = useMantineTheme().fn;++ const rawSeries = useMemo(+ () =>+ toCountBreakoutRawSeries(data, jsQuery, {+ display,+ maxCategories,+ otherLabel: t`Other`,+ getColor: themeColor,+ }),+ [data, jsQuery, 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/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsxnew file mode 100644index 00000000000..82cdb6ad1b7--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsx@@ -0,0 +1,113 @@+import { useMemo } from "react";+import { t } from "ttag";++import { Skeleton, useMantineTheme } from "metabase/ui";+import { BreakoutChartCard } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import { buildCallsByDayQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import { toCountBreakoutRawSeries } from "metabase-enterprise/monitor/api-key-usage/raw-series";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";++const CHART_HEIGHT = 320;++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++type Props = DataSources &+ ApiKeyUsageFilters & {+ title: string;+ h?: number;+ };++type InnerProps = ApiKeyUsageFilters & {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+ title: string;+ h: number;+};++/**+ * Line chart of total calls per day. Renders a skeleton until the audit metadata is loaded, then+ * delegates to the inner component.+ */+export function ApiKeyUsageCallsTimelineChart({+ provider,+ table,+ groupMembersTable,+ title,+ h = CHART_HEIGHT,+ ...filters+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return <Skeleton h={h} />;+ }+ return (+ <ApiKeyUsageCallsTimelineChartInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ title={title}+ h={h}+ {...filters}+ />+ );+}++function ApiKeyUsageCallsTimelineChartInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ title,+ h,+}: InnerProps) {+ const query = useMemo(+ () =>+ buildCallsByDayQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ }),+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],+ );++ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);+ const { themeColor } = useMantineTheme().fn;++ const rawSeries = useMemo(+ () =>+ toCountBreakoutRawSeries(data, jsQuery, {+ display: "line",+ otherLabel: t`Other`,+ getColor: themeColor,+ }),+ [data, jsQuery, themeColor],+ );++ return (+ <BreakoutChartCard+ title={title}+ rawSeries={rawSeries}+ isFetching={isFetching}+ display="line"+ h={h}+ otherLabel={t`Other`}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.tsxnew file mode 100644index 00000000000..60a8f2d3a83--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.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 ApiKeyUsageEmptyState() {+ return (+ <Flex flex={1} mih="60vh" align="center" justify="center">+ <EmptyState+ icon="key"+ title={t`No API key activity`}+ message={t`Requests authenticated with an API key will show up here. Try widening the date range or check back once a key is used.`}+ />+ </Flex>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsxnew file mode 100644index 00000000000..08a0230d1d7--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsx@@ -0,0 +1,33 @@+import { ApiKeyUsageEventsTable } from "./ApiKeyUsageEventsTable";+import { useApiKeyUsageContext } from "./context";++export function ApiKeyUsageEventsPage() {+ const {+ dataSources: { provider, table, groupMembersTable },+ chartFilters: { dateFilter, apiKeyId, userId, groupId },+ hasPii,+ page,+ total,+ onPageChange,+ sortingOptions,+ onSortingOptionsChange,+ } = useApiKeyUsageContext();++ return (+ <ApiKeyUsageEventsTable+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ dateFilter={dateFilter}+ apiKeyId={apiKeyId}+ userId={userId}+ groupId={groupId}+ hasPii={hasPii}+ page={page}+ total={total}+ onPageChange={onPageChange}+ sortingOptions={sortingOptions}+ onSortingOptionsChange={onSortingOptionsChange}+ />+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsxnew file mode 100644index 00000000000..9b291f961b9--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsx@@ -0,0 +1,354 @@+import { type ReactNode, useMemo } from "react";+import { t } from "ttag";++import { DateTime } from "metabase/common/components/DateTime";+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";+import { PaginationControls } from "metabase/common/components/PaginationControls";+import { useScrollToTop, useSortingStateChange } from "metabase/common/hooks";+import { MonitorEmptyState } from "metabase/monitor/components/MonitorEmptyState";+import { MonitorTableCard } from "metabase/monitor/components/MonitorTableCard";+import {+ Box,+ Ellipsified,+ Flex,+ LoadingOverlay,+ Stack,+ TreeTable,+ type TreeTableColumnDef,+ TreeTableSkeleton,+ useTreeTableInstance,+} from "metabase/ui";+import { EMPTY_CELL_PLACEHOLDER } from "metabase/utils/constants";+import { formatNumber } from "metabase/utils/formatting";+import { useApiKeyUsageEventsQuery } from "metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery";+import {+ API_KEY_USAGE_EVENT_SORT_COLUMNS,+ type ApiKeyUsageEventSortColumn,+ type ApiKeyUsageFilters,+ apiKeyUsageEventColumnKeys,+ buildEventsQuery,+} from "metabase-enterprise/monitor/api-key-usage/query-utils";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";+import type { RowValue, RowValues, SortingOptions } from "metabase-types/api";++export const EVENTS_PAGE_SIZE = 25;++const DEFAULT_SORTING: SortingOptions<ApiKeyUsageEventSortColumn> = {+ sort_column: "occurred_at",+ sort_direction: "desc",+};++type EventColumn = {+ key: ApiKeyUsageEventSortColumn;+ title: string;+ sort?: ApiKeyUsageEventSortColumn;+ align?: "right";+ grow?: boolean;+ /** Overrides the default auto-width cap — for columns whose content doesn't fit in 200px. */+ maxAutoWidth?: number;+ render?: (value: RowValue) => ReactNode;+};++const EVENT_COLUMN_META: Record<+ ApiKeyUsageEventSortColumn,+ () => Omit<EventColumn, "key">+> = {+ log_id: () => ({ title: t`ID`, sort: "log_id" }),+ occurred_at: () => ({+ title: t`Occurred at`,+ sort: "occurred_at",+ maxAutoWidth: 240,+ render: (value) =>+ value == null ? (+ EMPTY_CELL_PLACEHOLDER+ ) : (+ <DateTime value={String(value)} />+ ),+ }),+ route_template: () => ({+ title: t`Route`,+ sort: "route_template",+ grow: true,+ render: (value) =>+ value == null ? (+ EMPTY_CELL_PLACEHOLDER+ ) : (+ <Ellipsified>{String(value)}</Ellipsified>+ ),+ }),+ http_method: () => ({ title: t`Method`, sort: "http_method" }),+ status: () => ({ title: t`Status`, sort: "status", align: "right" }),+ duration_ms: () => ({+ title: t`Duration (ms)`,+ sort: "duration_ms",+ align: "right",+ render: (value) =>+ value == null ? EMPTY_CELL_PLACEHOLDER : formatNumber(Number(value)),+ }),+ api_key_name: () => ({ title: t`API key`, sort: "api_key_name" }),+ creator_display_name: () => ({+ title: t`Created by`,+ sort: "creator_display_name",+ }),+ client_display_name: () => ({+ title: t`Client`,+ sort: "client_display_name",+ }),+ embedding_client: () => ({+ title: t`Embedding client`,+ sort: "embedding_client",+ }),+ embedding_hostname: () => ({+ title: t`Embedding hostname`,+ sort: "embedding_hostname",+ }),+ ip_address: () => ({ title: t`IP address`, sort: "ip_address" }),+};++export function eventColumns(hasPii: boolean): EventColumn[] {+ return apiKeyUsageEventColumnKeys(hasPii).map((key) => ({+ key,+ ...EVENT_COLUMN_META[key](),+ }));+}++function renderCell(column: EventColumn, value: RowValue): ReactNode {+ if (column.render) {+ return column.render(value);+ }+ return value == null || value === "" ? EMPTY_CELL_PLACEHOLDER : String(value);+}++type EventRow = { id: string } & Record<string, RowValue>;++type PaginationProps = {+ page: number;+ total: number;+ onPageChange: (page: number) => void;+};++type SortProps = {+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>;+ onSortingOptionsChange: (+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>,+ ) => void;+};++type Nullable<T> = { [K in keyof T]: T[K] | null };++type MetadataSources = {+ provider: MetadataProvider;+ table: TableMetadata | CardMetadata;+ groupMembersTable: TableMetadata | CardMetadata;+};++type BaseProps = ApiKeyUsageFilters &+ PaginationProps &+ SortProps & {+ hasPii: boolean;+ };++type Props = BaseProps & Nullable<MetadataSources>;+type InnerProps = BaseProps & MetadataSources;++export function ApiKeyUsageEventsTable({+ provider,+ table,+ groupMembersTable,+ ...rest+}: Props) {+ if (!provider || !table || !groupMembersTable) {+ return null;+ }+ return (+ <ApiKeyUsageEventsTableInner+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ {...rest}+ />+ );+}++function ApiKeyUsageEventsTableInner({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ hasPii,+ page,+ total,+ onPageChange,+ sortingOptions,+ onSortingOptionsChange,+}: InnerProps) {+ const columns = useMemo(() => eventColumns(hasPii), [hasPii]);++ const { sort_column: sortColumn, sort_direction: sortDirection } =+ sortingOptions;+ const effectiveSorting = useMemo(() => {+ const visibleSortColumns = new Set(+ columns.map((column) => column.sort).filter(Boolean),+ );+ return visibleSortColumns.has(sortColumn)+ ? { sort_column: sortColumn, sort_direction: sortDirection }+ : DEFAULT_SORTING;+ }, [columns, sortColumn, sortDirection]);++ const query = useMemo(+ () =>+ buildEventsQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ sortColumn: effectiveSorting.sort_column,+ sortDirection: effectiveSorting.sort_direction,+ hasPii,+ }),+ [+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ effectiveSorting,+ hasPii,+ ],+ );++ const { data, isFetching, error } = useApiKeyUsageEventsQuery(+ query,+ page,+ EVENTS_PAGE_SIZE,+ );++ // The result columns (`data.data.cols`) are the full, warehouse-ordered set the query returns —+ // not the curated `columns` we render. So we map each curated column to its position in the+ // result by name. Names are upper- or lower-cased depending on the warehouse, so match case-insensitively.+ const columnIndex = useMemo(() => {+ const cols = data?.data?.cols ?? [];+ return new Map(cols.map((col, index) => [col.name.toLowerCase(), index]));+ }, [data]);++ const rows: EventRow[] = useMemo(() => {+ const rawRows: RowValues[] = data?.data?.rows ?? [];+ return rawRows.map((rawRow, rowIndex) => {+ const values = Object.fromEntries(+ columns.map((column) => {+ const index = columnIndex.get(column.key);+ return [column.key, index != null ? rawRow[index] : null];+ }),+ );+ const id = String(values.log_id ?? `${page}-${rowIndex}`);+ return { id, ...values };+ });+ }, [data, columns, columnIndex, page]);++ const treeColumns = useMemo<TreeTableColumnDef<EventRow>[]>(+ () =>+ columns.map((column) => ({+ id: column.key,+ header: column.title,+ ...(column.grow+ ? { minWidth: 280 }+ : {+ width: "auto" as const,+ minWidth: 120,+ maxAutoWidth: column.maxAutoWidth ?? 200,+ }),+ enableSorting: !!column.sort,+ sortDescFirst: column.sort === "occurred_at",+ accessorFn: (row) => row[column.key],+ cell: ({ row }) => {+ const node = renderCell(column, row.original[column.key]);+ return column.align === "right" ? (+ <Box ta="right" w="100%">+ {node}+ </Box>+ ) : (+ node+ );+ },+ })),+ [columns],+ );++ const { sortingState, onSortingChange } = useSortingStateChange({+ sortingOptions: effectiveSorting,+ columns: API_KEY_USAGE_EVENT_SORT_COLUMNS,+ defaultSorting: DEFAULT_SORTING,+ onSortingOptionsChange,+ });++ const treeTableInstance = useTreeTableInstance<EventRow>({+ data: rows,+ columns: treeColumns,+ sorting: sortingState,+ manualSorting: true,+ getNodeId: (row) => row.id,+ onSortingChange,+ });++ useScrollToTop({+ ref: treeTableInstance.containerRef,+ keys: [page, effectiveSorting],+ skip: isFetching,+ });++ const skeletonColumnWidths = columns.map(() => 1 / columns.length);++ return (+ <Stack gap="lg" flex={1} mih={0}>+ <MonitorTableCard+ aria-busy={isFetching}+ data-testid="api-key-usage-events-table"+ >+ {error ? (+ <Flex mih="60vh" align="center" justify="center">+ <LoadingAndErrorWrapper loading={false} error={error} />+ </Flex>+ ) : !data ? (+ <TreeTableSkeleton columnWidths={skeletonColumnWidths} />+ ) : (+ <>+ <LoadingOverlay visible={isFetching} />+ <TreeTable+ instance={treeTableInstance}+ hierarchical={false}+ ariaLabel={t`Calls`}+ emptyState={<MonitorEmptyState label={t`No calls found`} />}+ getRowProps={() => ({ "data-testid": "api-key-usage-event" })}+ />+ </>+ )}+ </MonitorTableCard>++ {data && !error && (+ <Flex justify="flex-end">+ <PaginationControls+ page={page}+ pageSize={EVENTS_PAGE_SIZE}+ itemsLength={rows.length}+ total={total}+ showTotal+ onPreviousPage={() => onPageChange(page - 1)}+ onNextPage={() => onPageChange(page + 1)}+ />+ </Flex>+ )}+ </Stack>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsxnew file mode 100644index 00000000000..4652f9a5940--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsx@@ -0,0 +1,69 @@+import { t } from "ttag";++import { SimpleGrid, Stack } from "metabase/ui";++import { ApiKeyActivityTable } from "./ApiKeyActivityTable";+import { ApiKeyUsageBreakoutChart } from "./ApiKeyUsageBreakoutChart";+import { ApiKeyUsageCallsTimelineChart } from "./ApiKeyUsageCallsTimelineChart";+import { useApiKeyUsageContext } from "./context";++export function ApiKeyUsagePage() {+ const {+ dataSources: { provider, table, groupMembersTable },+ chartFilters: { dateFilter, apiKeyId, userId, groupId },+ } = useApiKeyUsageContext();++ return (+ <Stack gap="xl">+ <ApiKeyActivityTable+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ dateFilter={dateFilter}+ apiKeyId={apiKeyId}+ userId={userId}+ groupId={groupId}+ title={t`Key activity`}+ h={500}+ />+ <ApiKeyUsageCallsTimelineChart+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ dateFilter={dateFilter}+ apiKeyId={apiKeyId}+ userId={userId}+ groupId={groupId}+ title={t`Calls over time`}+ />+ <SimpleGrid cols={2} spacing="xl">+ <ApiKeyUsageBreakoutChart+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ dateFilter={dateFilter}+ apiKeyId={apiKeyId}+ userId={userId}+ groupId={groupId}+ title={t`Calls by client`}+ display="pie"+ breakoutColumn="client_display_name"+ h={500}+ />+ <ApiKeyUsageBreakoutChart+ provider={provider}+ table={table}+ groupMembersTable={groupMembersTable}+ dateFilter={dateFilter}+ apiKeyId={apiKeyId}+ userId={userId}+ groupId={groupId}+ title={t`Calls by route`}+ display="row"+ breakoutColumn="route_template"+ h={500}+ />+ </SimpleGrid>+ </Stack>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsxnew file mode 100644index 00000000000..91a4deb22ed--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsx@@ -0,0 +1,277 @@+import type { ReactNode } from "react";+import { useMemo } from "react";+import { t } from "ttag";++import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";+import {+ type PillTab,+ PillTabNavigation,+} from "metabase/common/components/PillTabNavigation";+import { useUrlState } from "metabase/common/hooks/use-url-state";+import { MonitorHeaderTitle } from "metabase/monitor/components/MonitorHeaderTitle";+import { MonitorMain } from "metabase/monitor/components/MonitorLayout";+import { Outlet, useLocation } from "metabase/router";+import { useSetting } from "metabase/settings";+import { Flex, Loader, Stack } from "metabase/ui";+import * as Urls from "metabase/urls";+import {+ ConversationFilters as ApiKeyUsageFilterBar,+ parseId,+ useFilterOptions,+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters";+import { useAuditTable } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable";+import {+ VIEW_API_KEY_USAGE,+ VIEW_GROUP_MEMBERS,+} from "metabase-enterprise/monitor/api-key-usage/constants";+import { useApiKeyUsageHasData } from "metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData";+import { isKeyOutsideGroup } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import { apiKeyUsageUrlStateConfig } from "metabase-enterprise/monitor/api-key-usage/url-state";++import { ApiKeyFilterSelect } from "./ApiKeyFilterSelect";+import { ApiKeyUsageEmptyState } from "./ApiKeyUsageEmptyState";+import {+ ApiKeyUsageContextProvider,+ type ApiKeyUsageContextValue,+} from "./context";++type RouteContentProps = {+ children: ReactNode;+ error: unknown;+ isInitialLoading: boolean;+};++function RouteContent({+ children,+ error,+ isInitialLoading,+}: RouteContentProps) {+ if (error !== undefined && error !== null) {+ return (+ <Flex mih="60vh" align="center" justify="center">+ <LoadingAndErrorWrapper loading={false} error={error} />+ </Flex>+ );+ }++ if (isInitialLoading) {+ return (+ <Flex mih="60vh" align="center" justify="center">+ <Loader size="lg" />+ </Flex>+ );+ }++ return children;+}++export function ApiKeyUsageSectionLayout() {+ const location = useLocation();+ const [+ { date, user, group, tenant, api_key, page, sort_column, sort_direction },+ { patchUrlState },+ ] = useUrlState(location, apiKeyUsageUrlStateConfig);++ const {+ dateFilter,+ userId,+ groupId,+ groupNoFilterValue,+ userOptions,+ groupOptions,+ } = useFilterOptions({ date, user, group, tenant });++ const { data: apiKeys } = useListApiKeysQuery();+ const selectedApiKey = useMemo(+ () => apiKeys?.find((apiKey) => apiKey.id === parseId(api_key)),+ [apiKeys, api_key],+ );+ // Group and API key work like State and City: Group is only ever set by the user, the key list+ // is narrowed to the chosen group, and picking another group clears a key that isn't in it. The+ // UI can't produce a key outside the group, but a stale or hand-edited URL can — ignore the key+ // then, rather than let the two filters silently return nothing.+ const keyOutsideGroup = isKeyOutsideGroup(selectedApiKey, groupId);+ const apiKeyId = keyOutsideGroup ? undefined : parseId(api_key);++ const hasPii = useSetting("analytics-pii-retention-enabled") === true;+ const usageAudit = useAuditTable(VIEW_API_KEY_USAGE);+ const groupMembersAudit = useAuditTable(VIEW_GROUP_MEMBERS);++ const dataSources = useMemo(+ () => ({+ provider: usageAudit.provider,+ table: usageAudit.table,+ groupMembersTable: groupMembersAudit.table,+ }),+ [usageAudit.provider, usageAudit.table, groupMembersAudit.table],+ );+ const chartFilters = useMemo(+ () => ({ dateFilter, apiKeyId, userId, groupId }),+ [apiKeyId, dateFilter, groupId, userId],+ );+ const sortingOptions = useMemo(+ () => ({ sort_column, sort_direction }),+ [sort_column, sort_direction],+ );++ const {+ isInitialLoading,+ isRefetching,+ hasData,+ count,+ error,+ tablesMissing,+ } = useApiKeyUsageHasData({+ ...dataSources,+ ...chartFilters,+ isLoadingTables: usageAudit.isLoading || groupMembersAudit.isLoading,+ });+ // `tablesMissing` wins over `hasData`: the charts and tables below can't do anything useful+ // with a null table either — they'd just sit on their own skeletons forever — so show the+ // empty state instead of rendering them once the lookup has settled as missing.+ const showEmpty =+ !isInitialLoading && !isRefetching && (!hasData || tablesMissing);++ const usagePath = Urls.monitorApiKeyUsageOverview();+ const eventsPath = Urls.monitorApiKeyUsageEvents();+ const tabs: PillTab[] = [+ {+ label: t`Usage`,+ to: `${usagePath}${location.search}`,+ isSelected: (pathname) => pathname === usagePath,+ },+ {+ label: t`Events`,+ to: `${eventsPath}${location.search}`,+ isSelected: (pathname) => pathname === eventsPath,+ },+ ];++ const isTableRoute = location.pathname === eventsPath;+ const outletContext = useMemo<ApiKeyUsageContextValue>(+ () => ({+ dataSources,+ chartFilters,+ hasPii,+ page,+ total: count,+ onPageChange: (newPage) =>+ patchUrlState({ page: newPage }, { immediate: true }),+ sortingOptions,+ onSortingOptionsChange: (newSorting) =>+ patchUrlState({+ sort_column: newSorting.sort_column,+ sort_direction: newSorting.sort_direction,+ page: 0,+ }),+ }),+ [+ chartFilters,+ count,+ dataSources,+ hasPii,+ page,+ patchUrlState,+ sortingOptions,+ ],+ );++ // Tabs + filters stay outside the scrollable area below (rendered once per branch, same+ // elements, just never scrolled past) so they're always visible regardless of page length.+ const tabsAndFilters = (+ <>+ <PillTabNavigation tabs={tabs} />+ <ApiKeyUsageFilterBar+ date={date}+ onDateChange={(val) => patchUrlState({ date: val, page: 0 })}+ user={user}+ onUserChange={(val) => patchUrlState({ user: val, page: 0 })}+ userOptions={userOptions}+ group={group}+ onGroupChange={(val) =>+ patchUrlState({+ group: val,+ // Like picking a new State: a key that isn't in the new group is cleared.+ ...(isKeyOutsideGroup(+ selectedApiKey,+ val == null ? null : Number(val),+ )+ ? { api_key: null }+ : {}),+ page: 0,+ })+ }+ groupOptions={groupOptions}+ groupNoFilterValue={groupNoFilterValue}+ // Tenants aren't a meaningful concept for API-key usage — see EMB-2391, which will make+ // this shared filter bar's tenant support properly optional instead of hardcoded off here.+ tenant={null}+ onTenantChange={() => {}}+ tenantOptions={[]}+ hasTenants={false}+ // The API key filter (below) is the primary way to scope this page; a separate user+ // filter is redundant now that "Created by" is just a column.+ hasUsers={false}+ extraFilter={+ <ApiKeyFilterSelect+ value={keyOutsideGroup ? null : api_key}+ onChange={(val) => patchUrlState({ api_key: val, page: 0 })}+ groupId={groupId}+ />+ }+ />+ </>+ );++ const pageContent = (+ <RouteContent+ error={error ?? usageAudit.error ?? groupMembersAudit.error}+ isInitialLoading={isInitialLoading}+ >+ {showEmpty ? (+ <ApiKeyUsageEmptyState />+ ) : (+ <ApiKeyUsageContextProvider value={outletContext}>+ <Outlet />+ </ApiKeyUsageContextProvider>+ )}+ </RouteContent>+ );++ if (isTableRoute) {+ return (+ <Flex h="100%" wrap="nowrap">+ <MonitorMain>+ <Stack gap="xl" flex={1} mih={0}>+ <MonitorHeaderTitle>{t`API key usage`}</MonitorHeaderTitle>+ {tabsAndFilters}+ <Stack+ gap="lg"+ flex={1}+ mih={0}+ display="flex"+ style={{ flexDirection: "column" }}+ >+ {pageContent}+ </Stack>+ </Stack>+ </MonitorMain>+ </Flex>+ );+ }++ return (+ <Flex h="100%" wrap="nowrap">+ <MonitorMain>+ <Stack gap="xl" flex={1} mih={0}>+ <MonitorHeaderTitle>{t`API key usage`}</MonitorHeaderTitle>+ {tabsAndFilters}+ <Stack gap="lg" flex={1} mih={0} style={{ overflowY: "auto" }}>+ {pageContent}+ </Stack>+ </Stack>+ </MonitorMain>+ </Flex>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsxnew file mode 100644index 00000000000..12ed8fac72c--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsx@@ -0,0 +1,59 @@+import { type ReactNode, createContext, useContext } from "react";++import type {+ ApiKeyUsageEventSortColumn,+ ApiKeyUsageFilters,+} from "metabase-enterprise/monitor/api-key-usage/query-utils";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";+import type { SortingOptions } from "metabase-types/api";++type ApiKeyUsageDataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+};++export type ApiKeyUsageContextValue = {+ dataSources: ApiKeyUsageDataSources;+ chartFilters: ApiKeyUsageFilters;+ hasPii: boolean;+ page: number;+ total: number;+ onPageChange: (page: number) => void;+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>;+ onSortingOptionsChange: (+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>,+ ) => void;+};++const ApiKeyUsageContext = createContext<ApiKeyUsageContextValue | null>(null);++type ApiKeyUsageContextProviderProps = {+ children: ReactNode;+ value: ApiKeyUsageContextValue;+};++export function ApiKeyUsageContextProvider({+ children,+ value,+}: ApiKeyUsageContextProviderProps) {+ return (+ <ApiKeyUsageContext.Provider value={value}>+ {children}+ </ApiKeyUsageContext.Provider>+ );+}++export function useApiKeyUsageContext(): ApiKeyUsageContextValue {+ const context = useContext(ApiKeyUsageContext);+ if (context === null) {+ throw new Error(+ "useApiKeyUsageContext must be used within ApiKeyUsageContextProvider",+ );+ }+ return context;+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.tsnew file mode 100644index 00000000000..8c1d801f555--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.ts@@ -0,0 +1,3 @@+export { ApiKeyUsageSectionLayout } from "./ApiKeyUsageSectionLayout";+export { ApiKeyUsagePage } from "./ApiKeyUsagePage";+export { ApiKeyUsageEventsPage } from "./ApiKeyUsageEventsPage";diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.tsnew file mode 100644index 00000000000..07bda4214bd--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.ts@@ -0,0 +1,7 @@+export {+ AUDIT_DB_ID,+ VIEW_GROUP_MEMBERS,+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/constants";++// View name in the audit database for API key usage analytics.+export const VIEW_API_KEY_USAGE = "v_api_key_usage";diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.tsnew file mode 100644index 00000000000..3a51ab376c1--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.ts@@ -0,0 +1,36 @@+import { useMemo } from "react";++import { skipToken, useGetAdhocQueryQuery } from "metabase/api";+import { paginateEventsQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import type { Query } from "metabase-lib";+import * as Lib from "metabase-lib";+import type { Dataset } from "metabase-types/api";++type EventsPageResult = {+ data: Dataset | undefined;+ isFetching: boolean;+ error: unknown;+};++/**+ * 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 useApiKeyUsageEventsQuery(+ 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, error } = useGetAdhocQueryQuery(+ jsQuery ?? skipToken,+ );++ return { data, isFetching, error };+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.tsnew file mode 100644index 00000000000..ccae1738b34--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.ts@@ -0,0 +1,167 @@+import { useMemo, useRef } from "react";++import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";+import {+ apiKeyMatchesScope,+ buildTotalCountQuery,+} from "metabase-enterprise/monitor/api-key-usage/query-utils";+import type {+ CardMetadata,+ MetadataProvider,+ TableMetadata,+} from "metabase-lib";++type DataSources = {+ provider: MetadataProvider | null;+ table: TableMetadata | CardMetadata | null;+ groupMembersTable: TableMetadata | CardMetadata | null;+ /** Whether the `table`/`groupMembersTable` lookup itself (view name -> table metadata) is+ * still resolving — distinct from the data queries below, which only start once this settles.+ * Without this, a view the audit db hasn't synced yet would leave `table` null and `query`+ * null forever, and the page would spin forever with no escape hatch. */+ isLoadingTables: boolean;+};++type ResolvedArgs = {+ /** Whether the `table`/`groupMembersTable` lookup itself is still resolving. */+ isLoadingTables: boolean;+ isFetching: boolean;+ isFetchingKeys: boolean;+ /** Null means either still loading the tables, or the tables were never found. */+ query: unknown;+ data: unknown;+ apiKeys: unknown;+ hasError: boolean;+};++/**+ * Whether every input this hook depends on has settled, one way or another. Once the table+ * lookup is done, a still-null `query` means the view genuinely isn't there to query (nothing+ * more to wait for) rather than still loading — treated the same as a resolved, empty count.+ * Without that distinction, a view the audit db hasn't synced yet would leave `query` null+ * forever, and the page would spin forever with no escape hatch.+ */+export function isResolved({+ isLoadingTables,+ isFetching,+ isFetchingKeys,+ query,+ data,+ apiKeys,+ hasError,+}: ResolvedArgs): boolean {+ return (+ !isLoadingTables &&+ !isFetching &&+ !isFetchingKeys &&+ apiKeys !== undefined &&+ (query === null || data !== undefined || hasError)+ );+}++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 API keys — regardless of their usage. */+ hasData: boolean;+ /** Total number of calls matching the current filters — drives the events pagination. */+ count: number;+ /** Set when the count query itself failed (e.g. a 500) — the page should show an error, not spin forever. */+ error: unknown;+ /** The table lookup settled, but found no table to query at all (the audit db hasn't synced the+ * view). The charts and tables below this page can't do anything with a null table either — they+ * just sit on their own skeletons forever — so the caller should show the empty/error state+ * instead of rendering them, regardless of `hasData`. */+ tablesMissing: boolean;+};++/**+ * Drives the page's load/empty/data states. "Has data" means at least one API key matches the+ * current API key/user/group filters, or the filtered call count is nonzero — independent of+ * whether a *matching* key currently has usage, so the Key activity table can still show a key+ * with no activity instead of the page going empty, and a deleted key's history stays reachable+ * (see `count > 0` below). Still runs the filtered total-count query, since the Events tab's+ * pagination needs it. 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 useApiKeyUsageHasData({+ provider,+ table,+ groupMembersTable,+ isLoadingTables,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+}: DataSources & ApiKeyUsageFilters): Result {+ const query = useMemo(+ () =>+ provider && table && groupMembersTable+ ? buildTotalCountQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ })+ : null,+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],+ );++ const { data, isFetching, error } = useAdhocBreakoutQuery(query);+ const {+ data: apiKeys,+ isFetching: isFetchingKeys,+ error: keysError,+ } = useListApiKeysQuery();++ // Latch once the first count resolves (successfully or not); from then on a fetch is a+ // refetch, not initial load.+ const hasLoadedOnce = useRef(false);+ const combinedError = error ?? keysError;+ const hasError = combinedError != null;+ const resolved = isResolved({+ isLoadingTables,+ isFetching,+ isFetchingKeys,+ query,+ data,+ apiKeys,+ hasError,+ });+ 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);+ // `count > 0` keeps a deleted key's history reachable: once no live key matches the filters,+ // nothing in `apiKeys` can match either, but the usage log rows (and the key's name on them)+ // still exist and still match the filters' date range.+ const hasData =+ count > 0 ||+ (apiKeys?.some((apiKey) =>+ apiKeyMatchesScope(apiKey, { apiKeyId, userId, groupId }),+ ) ??+ false);++ const tablesMissing =+ !isLoadingTables &&+ (provider == null || table == null || groupMembersTable == null);++ return {+ isInitialLoading: !hasLoadedOnce.current,+ isRefetching: hasLoadedOnce.current && (isFetching || isFetchingKeys),+ hasData,+ count,+ error: combinedError,+ tablesMissing,+ };+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.tsnew file mode 100644index 00000000000..c6821c4d69f--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.ts@@ -0,0 +1,56 @@+import { isResolved } from "./useApiKeyUsageHasData";++const resolvedArgs = {+ isLoadingTables: false,+ isFetching: false,+ isFetchingKeys: false,+ query: {},+ data: {},+ apiKeys: [],+ hasError: false,+};++describe("isResolved", () => {+ it("is false while the table lookup is still loading, even with a query already built", () => {+ expect(isResolved({ ...resolvedArgs, isLoadingTables: true })).toBe(false);+ });++ it("is true once the table lookup finishes but finds no table (query stays null) — the bug this guards against", () => {+ expect(isResolved({ ...resolvedArgs, query: null, data: undefined })).toBe(+ true,+ );+ });++ it("is false if the table lookup finished with no table, but the keys list hasn't settled yet", () => {+ expect(+ isResolved({+ ...resolvedArgs,+ query: null,+ data: undefined,+ isFetchingKeys: true,+ }),+ ).toBe(false);+ });++ it("is false while the count query is still fetching, with a table found", () => {+ expect(isResolved({ ...resolvedArgs, isFetching: true })).toBe(false);+ });++ it("is false while the count data hasn't arrived yet, with a table found", () => {+ expect(isResolved({ ...resolvedArgs, data: undefined })).toBe(false);+ });++ it("is true once the count data arrives, with a table found", () => {+ expect(isResolved(resolvedArgs)).toBe(true);+ });++ it("is true on an error, even with no count data", () => {+ expect(+ isResolved({ ...resolvedArgs, data: undefined, hasError: true }),+ ).toBe(true);+ });++ it("is false until the keys list itself has loaded", () => {+ expect(isResolved({ ...resolvedArgs, apiKeys: undefined })).toBe(false);+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.tsnew file mode 100644index 00000000000..bf79d6bc97a--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.ts@@ -0,0 +1,16 @@+import { PLUGIN_MONITOR } from "metabase/plugins";+import { hasPremiumFeature } from "metabase-enterprise/settings";++import { getApiKeyUsageRoutes } from "./routes";++/**+ * API key usage is gated on `audit_app` (the same token feature that gates the rest of the+ * Monitor "Logs and activity" section), not on any AI-specific feature — this page is plain+ * REST-API-call analytics and intentionally does not live under AI Auditing.+ */+export function initializePlugin() {+ if (hasPremiumFeature("audit_app")) {+ PLUGIN_MONITOR.isApiKeyUsageEnabled = true;+ PLUGIN_MONITOR.getApiKeyUsageRoutes = getApiKeyUsageRoutes;+ }+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.tsnew file mode 100644index 00000000000..d265e386382--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.ts@@ -0,0 +1,367 @@+import type { DateFilterValue } from "metabase/querying/common/types";+import {+ applyDateFilter,+ applyIdFilter,+ breakoutByColumn,+ findColumn,+ joinGroupMembers,+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/query-utils";+import type {+ CardMetadata,+ ColumnMetadata,+ MetadataProvider,+ Query,+ TableMetadata,+} from "metabase-lib";+import * as Lib from "metabase-lib";+import type { ApiKey, SortDirection } from "metabase-types/api";++export type ApiKeyUsageFilters = {+ dateFilter: DateFilterValue;+ apiKeyId?: number;+ userId?: number;+ groupId?: number;+};++/**+ * Whether `apiKey` matches the page's API key/user/group filters, by the key's own metadata+ * (id/creator/group) rather than its usage. Shared by anything that needs to know which keys are+ * in scope independent of whether they have any activity — e.g. the Key activity table, and the+ * check for whether the page has anything to show at all.+ */+export function apiKeyMatchesScope(+ apiKey: ApiKey,+ {+ apiKeyId,+ userId,+ groupId,+ }: Pick<ApiKeyUsageFilters, "apiKeyId" | "userId" | "groupId">,+): boolean {+ return (+ (apiKeyId == null || apiKey.id === apiKeyId) &&+ (userId == null || apiKey.creator_id === userId) &&+ (groupId == null || apiKey.group.id === groupId)+ );+}++/**+ * Whether `apiKey` is outside the Group filter's `groupId`. With no group set ("All groups"),+ * every key is inside. Group and API key filter like State and City: the key list only offers the+ * chosen group's keys, and picking a group the selected key isn't in clears the key. So the UI+ * never produces an outside key itself — only a stale or hand-edited URL can.+ */+export function isKeyOutsideGroup(+ apiKey: Pick<ApiKey, "group"> | undefined,+ groupId: number | null | undefined,+): boolean {+ return apiKey != null && groupId != null && apiKey.group.id !== groupId;+}++type ApiKeyUsageDataSources = {+ 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 API key/user/group filters to a query. The API key and user filters are plain+ * equality checks on columns the view already has. The group filter means the key's own group —+ * matching the Key activity table (which scopes by `apiKey.group.id`, the key's group from+ * `GET /api/api-key`) — so it joins the audit `v_group_members` view on `actor_user_id`, not the+ * creator: a key has exactly one group through its own user, while its creator may belong to+ * several. Each no-ops when its id is unset.+ */+function applyScopeFilters(+ query: Query,+ {+ apiKeyId,+ userId,+ groupId,+ }: Pick<ApiKeyUsageFilters, "apiKeyId" | "userId" | "groupId">,+ groupMembersTable: TableMetadata | CardMetadata,+): Query {+ query = applyIdFilter(query, "api_key_id", apiKeyId);+ // `userId` here means the key's creator (the "Created by" filter) — the view's `creator_id`,+ // not its `actor_user_id` (the key's own synthetic service-account user).+ query = applyIdFilter(query, "creator_id", userId);+ query =+ groupId != null+ ? joinGroupMembers(query, groupMembersTable, "actor_user_id")+ : 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+ * (API key/user/group) filters applied. Centralizing it keeps the filter handling in one place so+ * a builder can't silently drop a filter.+ */+function buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {+ let query = Lib.queryFromTableOrCardMetadata(provider, table);+ query = applyDateFilter(query, dateFilter, "occurred_at");+ query = applyScopeFilters(+ query,+ { apiKeyId, userId, groupId },+ 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;+}++/** Add an `occurred_at` breakout bucketed by day (falls back to the raw column if the day bucket is unavailable). */+function breakoutByOccurredAtDay(query: Query): Query {+ const col = findColumn(query, "occurred_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);+}++type CountBreakoutQueryOpts = ApiKeyUsageFilters &+ ApiKeyUsageDataSources & {+ 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 route, by user.+ */+export function buildCountBreakoutQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ breakoutColumn,+}: CountBreakoutQueryOpts): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ });+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByColumn(query, breakoutColumn);+ query = orderByCountDesc(query);+ return query;+}++/**+ * Build a "calls per day" query — a single-series time series of the total call count. Used by+ * the "Calls over time" chart.+ */+export function buildCallsByDayQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ });+ query = Lib.aggregateByCount(query, 0);+ query = breakoutByOccurredAtDay(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).+ */+export function buildTotalCountQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ });+ query = Lib.aggregateByCount(query, 0);+ return query;+}++/** Add a MAX(occurred_at) aggregation, mirroring the shared module's `addSumAggregation`. */+function aggregateByMaxOccurredAt(query: Query): Query {+ const operators = Lib.availableAggregationOperators(query, 0);+ const maxOperator = operators.find(+ (operator) => Lib.displayInfo(query, 0, operator).shortName === "max",+ );+ if (!maxOperator) {+ return query;+ }+ const column = Lib.aggregationOperatorColumns(maxOperator).find(+ (col) =>+ Lib.displayInfo(query, 0, col).name?.toLowerCase() === "occurred_at",+ );+ return column+ ? Lib.aggregate(query, 0, Lib.aggregationClause(maxOperator, column))+ : query;+}++/**+ * Build a "most recent activity per API key" query: one row per key with at least one call+ * matching the current filters, breaking out by `api_key_id` and aggregating its latest+ * `occurred_at`. Used to scope the Key activity table's rows — and its "Last used" column — to+ * the same date/API key/user/group filters as the rest of the page.+ */+export function buildKeyActivityQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ });+ query = breakoutByColumn(query, "api_key_id");+ query = aggregateByMaxOccurredAt(query);+ return query;+}++export const API_KEY_USAGE_EVENT_SORT_COLUMNS = [+ "log_id",+ "occurred_at",+ "route_template",+ "http_method",+ "status",+ "duration_ms",+ "api_key_name",+ "creator_display_name", // the key's creator, shown in the UI as "Created by"+ "client_display_name",+ "embedding_client",+ "embedding_hostname",+ "ip_address",+] as const;++export type ApiKeyUsageEventSortColumn =+ (typeof API_KEY_USAGE_EVENT_SORT_COLUMNS)[number];++// Columns in API_KEY_USAGE_EVENT_SORT_COLUMNS that only show up when PII retention is on.+const PII_ONLY_COLUMNS: ApiKeyUsageEventSortColumn[] = ["ip_address"];++export function apiKeyUsageEventColumnKeys(+ hasPii: boolean,+): ApiKeyUsageEventSortColumn[] {+ return API_KEY_USAGE_EVENT_SORT_COLUMNS.filter(+ (column) => hasPii || !PII_ONLY_COLUMNS.includes(column),+ );+}++/** 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;+}++function projectToEventColumns(query: Query, hasPii: boolean): Query {+ const fields = apiKeyUsageEventColumnKeys(hasPii)+ .map((name) => findColumn(query, name, Lib.fieldableColumns))+ .filter((column): column is ColumnMetadata => column != null);+ return Lib.withFields(query, 0, fields);+}++type EventsQueryOpts = ApiKeyUsageFilters &+ ApiKeyUsageDataSources & {+ sortColumn?: ApiKeyUsageEventSortColumn;+ sortDirection?: SortDirection;+ hasPii: boolean;+ };++export function buildEventsQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ sortColumn = "occurred_at",+ sortDirection = "desc",+ hasPii,+}: EventsQueryOpts): Query {+ let query = buildBaseQuery({+ provider,+ table,+ groupMembersTable,+ dateFilter,+ apiKeyId,+ userId,+ groupId,+ });++ query = orderByColumn(query, sortColumn, sortDirection);+ query = orderByColumn(query, "log_id", "desc");+ query = projectToEventColumns(query, hasPii);++ 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/monitor/api-key-usage/query-utils.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.unit.spec.tsnew file mode 100644index 00000000000..4d33e4ec5fc--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.unit.spec.ts@@ -0,0 +1,98 @@+import type { ApiKey } from "metabase-types/api";++import {+ apiKeyMatchesScope,+ apiKeyUsageEventColumnKeys,+ isKeyOutsideGroup,+} from "./query-utils";++const apiKey: ApiKey = {+ id: 1,+ name: "Test key",+ group: { id: 2, name: "Administrators" },+ creator_id: 3,+ masked_key: "mb_************abcd",+ created_at: "2026-01-01T00:00:00Z",+ updated_at: "2026-01-01T00:00:00Z",+ updated_by: { id: 3, common_name: "Admin" },+ last_used_at: null,+};++describe("apiKeyMatchesScope", () => {+ it("matches when no filters are set", () => {+ expect(apiKeyMatchesScope(apiKey, {})).toBe(true);+ });++ it("matches on api key id", () => {+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 1 })).toBe(true);+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 99 })).toBe(false);+ });++ it("matches on creator id", () => {+ expect(apiKeyMatchesScope(apiKey, { userId: 3 })).toBe(true);+ expect(apiKeyMatchesScope(apiKey, { userId: 99 })).toBe(false);+ });++ it("matches on group id", () => {+ expect(apiKeyMatchesScope(apiKey, { groupId: 2 })).toBe(true);+ expect(apiKeyMatchesScope(apiKey, { groupId: 99 })).toBe(false);+ });++ it("requires every set filter to match", () => {+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 1, userId: 99 })).toBe(false);+ });+});++describe("isKeyOutsideGroup", () => {+ it("is false when no key is selected", () => {+ expect(isKeyOutsideGroup(undefined, 5)).toBe(false);+ });++ it("is false when the group is the key's own group", () => {+ expect(isKeyOutsideGroup(apiKey, 2)).toBe(false);+ });++ it("is false with no group set (All groups)", () => {+ expect(isKeyOutsideGroup(apiKey, null)).toBe(false);+ expect(isKeyOutsideGroup(apiKey, undefined)).toBe(false);+ });++ it("is true when the group isn't the key's own group", () => {+ expect(isKeyOutsideGroup(apiKey, 5)).toBe(true);+ });+});++describe("apiKeyUsageEventColumnKeys", () => {+ it("returns only the base columns when PII retention is off", () => {+ expect(apiKeyUsageEventColumnKeys(false)).toEqual([+ "log_id",+ "occurred_at",+ "route_template",+ "http_method",+ "status",+ "duration_ms",+ "api_key_name",+ "creator_display_name",+ "client_display_name",+ "embedding_client",+ "embedding_hostname",+ ]);+ });++ it("includes ip_address only when PII retention is on", () => {+ expect(apiKeyUsageEventColumnKeys(true)).toEqual([+ "log_id",+ "occurred_at",+ "route_template",+ "http_method",+ "status",+ "duration_ms",+ "api_key_name",+ "creator_display_name",+ "client_display_name",+ "embedding_client",+ "embedding_hostname",+ "ip_address",+ ]);+ });+});diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.tsnew file mode 100644index 00000000000..adbc4700bdb--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.ts@@ -0,0 +1,106 @@+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 (in particular, when `max` is unset — used for the day breakout, which+ * should never be collapsed).+ */+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`/`line`+ * displays. Long tails are collapsed into a single "Other" category when `maxCategories` is set.+ */+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,+ ),+ },+ },+ ];+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.tsnew file mode 100644index 00000000000..4eaec80f391--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.ts@@ -0,0 +1,81 @@+import type { StructuredDatasetQuery } from "metabase-types/api";++import { toCountBreakoutRawSeries } from "./raw-series";++const jsQuery: StructuredDatasetQuery = {+ database: 1,+ type: "query",+ query: {},+};++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 (e.g. the day-breakout timeline chart)", () => {+ const rows = [+ ["2026-01-01", 10],+ ["2026-01-02", 7],+ ["2026-01-03", 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/monitor/api-key-usage/routes.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/routes.tsxnew file mode 100644index 00000000000..2fa86194d87--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/routes.tsx@@ -0,0 +1,41 @@+import { Route, redirect, registerPagePrefetch } from "metabase/router";+import * as Urls from "metabase/urls";++/**+ * The API key usage pages sit behind one barrel, so a single `import()` reaches all three and+ * they land in one chunk by construction — no risk of the webpackChunkName comments drifting+ * apart and silently splitting the bundle.+ */+const pages = () =>+ import(/* webpackChunkName: "api-key-usage" */ "./components");++const apiKeyUsageSectionLayout = () =>+ pages().then(({ ApiKeyUsageSectionLayout }) => ({+ Component: ApiKeyUsageSectionLayout,+ }));++const apiKeyUsagePage = () =>+ pages().then(({ ApiKeyUsagePage }) => ({ Component: ApiKeyUsagePage }));++const apiKeyUsageEventsPage = () =>+ pages().then(({ ApiKeyUsageEventsPage }) => ({+ Component: ApiKeyUsageEventsPage,+ }));++/**+ * Hovering the Monitor sidebar link starts the fetch, so the chunk is usually in hand by the+ * time the click lands.+ */+registerPagePrefetch(Urls.monitorApiKeyUsage(), apiKeyUsageSectionLayout);++export function getApiKeyUsageRoutes() {+ return (+ <>+ <Route index element={redirect("usage")} />+ <Route lazy={apiKeyUsageSectionLayout}>+ <Route path="usage" lazy={apiKeyUsagePage} />+ <Route path="events" lazy={apiKeyUsageEventsPage} />+ </Route>+ </>+ );+}diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.tsnew file mode 100644index 00000000000..cd77b5e03f9--- /dev/null+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.ts@@ -0,0 +1,76 @@+import {+ type QueryParam,+ type UrlStateConfig,+ getFirstParamValue,+ parsePage,+ parseSortColumn,+ parseSortDirection,+} from "metabase/common/hooks/use-url-state";+import {+ type FilterUrlState,+ filterUrlStateConfig,+ mergeUrlStateConfig,+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/url-state";+import type { SortDirection } from "metabase-types/api";++import {+ API_KEY_USAGE_EVENT_SORT_COLUMNS,+ type ApiKeyUsageEventSortColumn,+} from "./query-utils";++type ApiKeyUsageEventsUrlState = {+ /** The API key an admin is scoping the page to — not part of the shared filter bar, so it's+ * tracked here rather than in `FilterUrlState`. */+ api_key: string | null;+ /** Current page of the row-level events table, 0-indexed. */+ page: number;+ sort_column: ApiKeyUsageEventSortColumn;+ sort_direction: SortDirection;+};++export type ApiKeyUsageUrlState = FilterUrlState & ApiKeyUsageEventsUrlState;++const DEFAULT_SORT_COLUMN: ApiKeyUsageEventSortColumn = "occurred_at";+const DEFAULT_SORT_DIRECTION: SortDirection = "desc";++function parseApiKey(param: QueryParam): string | null {+ const value = getFirstParamValue(param);+ return value && value.trim().length > 0 ? value.trim() : null;+}++const apiKeyUsageEventsUrlStateConfig: UrlStateConfig<ApiKeyUsageEventsUrlState> =+ {+ parse: (query) => ({+ api_key: parseApiKey(query.api_key),+ page: parsePage(query.page),+ sort_column: parseSortColumn(+ query.sort_column,+ API_KEY_USAGE_EVENT_SORT_COLUMNS,+ DEFAULT_SORT_COLUMN,+ ),+ sort_direction: parseSortDirection(+ query.sort_direction,+ DEFAULT_SORT_DIRECTION,+ ),+ }),+ serialize: ({ api_key, page, sort_column, sort_direction }) => ({+ api_key: api_key ?? undefined,+ 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,+ }),+ };++const mergedUrlStateConfig = mergeUrlStateConfig(+ filterUrlStateConfig,+ apiKeyUsageEventsUrlStateConfig,+);++export const apiKeyUsageUrlStateConfig: UrlStateConfig<ApiKeyUsageUrlState> = {+ ...mergedUrlStateConfig,+ // This page has no user/creator filter concept — "Created by" is just a column now — so a+ // stray `?user=` query param must not silently scope every query.+ parse: (query) => ({ ...mergedUrlStateConfig.parse(query), user: null }),+};diff --git a/enterprise/frontend/src/metabase-enterprise/plugins.ts b/enterprise/frontend/src/metabase-enterprise/plugins.tsindex 4b322364e4e..d165f26bcc8 100644--- a/enterprise/frontend/src/metabase-enterprise/plugins.ts+++ b/enterprise/frontend/src/metabase-enterprise/plugins.ts@@ -32,6 +32,7 @@ import { initializePlugin as initializeGroupManagers } from "./group_managers";import { initializePlugin as initializeMetabot } from "./metabot";import { initializePlugin as initializeModelPersistence } from "./model_persistence";import { initializePlugin as initializeModeration } from "./moderation";+import { initializePlugin as initializeMonitorApiKeyUsage } from "./monitor/api-key-usage";import { initializePlugin as initializeMonitorDependencyDiagnostics } from "./monitor/dependency-diagnostics";import { initializePlugin as initializeMonitorSessionManagement } from "./monitor/session-management";import { initializePlugin as initializeTools } from "./monitor/tools";@@ -88,6 +89,7 @@ export function initializePlugins() {initializeMetabot();initializeModelPersistence();initializeModeration();+ initializeMonitorApiKeyUsage();initializeMonitorDependencyDiagnostics();initializeMonitorSessionManagement();initializeMultiFactorAuth();diff --git a/frontend/src/metabase-types/analytics/event.ts b/frontend/src/metabase-types/analytics/event.tsindex dc84fa74312..6357c9c3053 100644--- a/frontend/src/metabase-types/analytics/event.ts+++ b/frontend/src/metabase-types/analytics/event.ts@@ -76,25 +76,3 @@ export type InviteToViewOpenedEvent = ValidateEvent<{triggered_from: "dashboard" | "question";target_id: number | null;}>;--export type MonitorOpenedEvent = ValidateEvent<{- event: "monitor_opened";- triggered_from: "nav_menu";-}>;--export type MonitorSectionClickedEvent = ValidateEvent<{- event: "monitor_section_clicked";- event_detail:- | "diagnostics"- | "erroring-questions"- | "alerts"- | "tasks"- | "jobs"- | "logs"- | "model-caching"- | "session-management"- | "ai-auditing-usage-stats"- | "ai-auditing-conversations"- | "ai-auditing-mcp"- | "ai-auditing-cli";-}>;diff --git a/frontend/src/metabase-types/api/admin.ts b/frontend/src/metabase-types/api/admin.tsindex 5f9b5203ee4..ecc968c506a 100644--- a/frontend/src/metabase-types/api/admin.ts+++ b/frontend/src/metabase-types/api/admin.ts@@ -15,6 +15,8 @@ export type ApiKey = {id: number;common_name: string;};+ /** Throttled liveness timestamp, stamped on each authenticated request. Null until first use. */+ last_used_at?: string | null;};export type CreateApiKeyRequest = {diff --git a/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx b/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsxindex 81e5b059af5..6b57f2f2d4d 100644--- a/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx+++ b/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx@@ -3,6 +3,7 @@ import { useCallback, useMemo, useState } from "react";import { t } from "ttag";import ApiKeysEmptyIllustration from "assets/img/api-keys-empty.svg?component";+import { ForwardRefLink } from "metabase/common/components/Link";import { DelayedLoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper/DelayedLoadingAndErrorWrapper";import { SettingsPageWrapper } from "metabase/settings-components";import {@@ -22,6 +23,7 @@ import {type TreeTableColumnDef,useTreeTableInstance,} from "metabase/ui";+import * as Urls from "metabase/urls";import { formatDateTimeWithUnit } from "metabase/value-formatting";import type { ApiKey } from "metabase-types/api";@@ -260,9 +262,19 @@ export const ManageApiKeys = () => {{t`Create API keys to let users authenticate API calls or make them programmatically.`}</Text></Box>- <Button variant="filled" onClick={() => setModal("create")}>- {t`Create an API key`}- </Button>+ <Group gap="sm">+ <Button+ variant="subtle"+ component={ForwardRefLink}+ to={Urls.monitorApiKeyUsage()}+ leftSection={<Icon name="key" />}+ >+ {t`View API key usage`}+ </Button>+ <Button variant="filled" onClick={() => setModal("create")}>+ {t`Create an API key`}+ </Button>+ </Group></Group><Card withBorder radius="sm" p={0} style={{ overflow: "hidden" }}>{showLoadingOrError ? (diff --git a/frontend/src/metabase/common/monitor/analytics.ts b/frontend/src/metabase/common/monitor/analytics.tsindex bfbb918f444..07b7436c364 100644--- a/frontend/src/metabase/common/monitor/analytics.ts+++ b/frontend/src/metabase/common/monitor/analytics.ts@@ -1,21 +1,30 @@import { trackSimpleEvent } from "metabase/analytics";-import type {- MonitorOpenedEvent,- MonitorSectionClickedEvent,-} from "metabase-types/analytics/event";-export type MonitorSection = MonitorSectionClickedEvent["event_detail"];+export type MonitorSection =+ | "diagnostics"+ | "erroring-questions"+ | "alerts"+ | "tasks"+ | "jobs"+ | "logs"+ | "model-caching"+ | "session-management"+ | "ai-auditing-usage-stats"+ | "ai-auditing-conversations"+ | "ai-auditing-mcp"+ | "ai-auditing-cli"+ | "api-key-usage";export const trackMonitorOpened = () => {trackSimpleEvent({event: "monitor_opened",triggered_from: "nav_menu",- } satisfies MonitorOpenedEvent);+ });};export const trackMonitorSectionClicked = (section: MonitorSection) => {trackSimpleEvent({event: "monitor_section_clicked",event_detail: section,- } satisfies MonitorSectionClickedEvent);+ });};diff --git a/frontend/src/metabase/common/monitor/selectors.ts b/frontend/src/metabase/common/monitor/selectors.tsindex 74068fe9668..5f45e9d8e82 100644--- a/frontend/src/metabase/common/monitor/selectors.ts+++ b/frontend/src/metabase/common/monitor/selectors.ts@@ -46,6 +46,15 @@ export function canAccessAiAuditing(state: State) {return getUserIsAdmin(state);}+// Admin-only, unlike the rest of Monitoring tools: the page loads `GET /api/api-key`, which is+// superuser-only, so a non-admin with just the monitoring application permission would hit a 403.+export function canAccessApiKeyUsage(state: State) {+ if (isWithinIframe()) {+ return false;+ }+ return getUserIsAdmin(state);+}+export function canAccessMonitor(state: State) {return (canAccessMonitorDiagnostics(state) ||diff --git a/frontend/src/metabase/common/monitor/selectors.unit.spec.ts b/frontend/src/metabase/common/monitor/selectors.unit.spec.tsindex 974338a1691..4d3722e78ae 100644--- a/frontend/src/metabase/common/monitor/selectors.unit.spec.ts+++ b/frontend/src/metabase/common/monitor/selectors.unit.spec.ts@@ -8,6 +8,7 @@ import {import {canAccessAiAuditing,canAccessAlertsManagement,+ canAccessApiKeyUsage,canAccessMonitor,canAccessMonitorDiagnostics,canAccessMonitoringTools,@@ -326,3 +327,49 @@ describe("canAccessAiAuditing", () => {expect(canAccessAiAuditing(state)).toBe(false);});});++describe("canAccessApiKeyUsage", () => {+ beforeEach(() => {+ jest.clearAllMocks();+ isWithinIframe.mockReturnValue(false);+ });++ it("returns false when in embedding iframe", () => {+ isWithinIframe.mockReturnValue(true);+ const state = createMockState({+ currentUser: createMockUser({ is_superuser: true }),+ });++ expect(canAccessApiKeyUsage(state)).toBe(false);+ });++ it("returns true when user is admin", () => {+ const state = createMockState({+ currentUser: createMockUser({ is_superuser: true }),+ });++ expect(canAccessApiKeyUsage(state)).toBe(true);+ });++ it("returns false for an analyst without admin", () => {+ const state = createMockState({+ currentUser: createMockUser({+ is_superuser: false,+ is_data_analyst: true,+ }),+ });++ expect(canAccessApiKeyUsage(state)).toBe(false);+ });++ it("returns false for a non-admin with the monitoring application permission", () => {+ const state = createMockState({+ currentUser: createMockUser({+ is_superuser: false,+ permissions: { can_access_monitoring: true },+ }),+ });++ expect(canAccessApiKeyUsage(state)).toBe(false);+ });+});diff --git a/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsx b/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsxnew file mode 100644index 00000000000..3e367f01c19--- /dev/null+++ b/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsx@@ -0,0 +1,19 @@+import { t } from "ttag";++import { usePageTitle } from "metabase/hooks/use-page-title";+import { BaseUpsellPage } from "metabase/monitor/upsells";++export function ApiKeyUsageUpsellPage() {+ usePageTitle(t`API key usage`);++ return (+ <BaseUpsellPage+ campaign="monitor-api-key-usage"+ location="monitor-api-key-usage-page"+ header={t`API key usage`}+ title={t`See who's calling your API`}+ description={t`Track which API keys are active, who's using them, and which routes and clients they're calling — so you can spot stale keys and unexpected usage.`}+ image="app/assets/img/upsell-api-usage-analytics.png"+ />+ );+}diff --git a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsxindex 616d0bc0429..6a12d67c674 100644--- a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx+++ b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx@@ -9,6 +9,7 @@ import {import {canAccessAiAuditing,canAccessAlertsManagement,+ canAccessApiKeyUsage,canAccessMonitorDiagnostics,canAccessMonitoringTools,canAccessSessionManagement,@@ -26,9 +27,11 @@ import * as Urls from "metabase/urls";import { MonitorContent } from "./MonitorContent";-function getActiveSection(pathname: string): MonitorSection | null {+type ActiveSection = MonitorSection | null;++function getActiveSection(pathname: string): ActiveSection {return match(pathname)- .returnType<MonitorSection | null>()+ .returnType<ActiveSection>().with(P.string.startsWith(Urls.dependencyDiagnostics()),() => "diagnostics",@@ -45,6 +48,7 @@ function getActiveSection(pathname: string): MonitorSection | null {P.string.startsWith(Urls.monitorModelPersistenceLog()),() => "model-caching",)+ .with(P.string.startsWith(Urls.monitorApiKeyUsage()), () => "api-key-usage").with(P.string.startsWith(Urls.monitorSessions()),() => "session-management",@@ -89,6 +93,7 @@ export function MonitorLayout() {const canAccessAlerts = useSelector(canAccessAlertsManagement);const canAccessSessions = useSelector(canAccessSessionManagement);const canAccessAiAuditingTab = useSelector(canAccessAiAuditing);+ const canAccessApiKeyUsageTab = useSelector(canAccessApiKeyUsage);const activeSection = getActiveSection(pathname);@@ -187,6 +192,17 @@ export function MonitorLayout() {onClick={() => trackMonitorSectionClicked("session-management")}/>)}+ {canAccessApiKeyUsageTab && (+ <AreaTab+ label={t`API key usage`}+ icon="key"+ to={Urls.monitorApiKeyUsage()}+ isSelected={activeSection === "api-key-usage"}+ showLabel={isNavbarOpened}+ isGated={!hasAuditAppFeature}+ onClick={() => trackMonitorSectionClicked("api-key-usage")}+ />+ )}</AreaTabGroup>)}{canAccessAiAuditingTab && hasAuditAppFeature && (diff --git a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsxindex de3e69b5b0b..129e72d3770 100644--- a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx+++ b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx@@ -153,6 +153,7 @@ describe("MonitorLayout", () => {["Application logs", Urls.monitorLogs()],["Model persistence log", Urls.monitorModelPersistenceLog()],["Session management", Urls.monitorSessions()],+ ["API key usage", Urls.monitorApiKeyUsage()],];expectedTabs.forEach(([name, href]) => {@@ -201,6 +202,11 @@ describe("MonitorLayout", () => {route: Urls.monitorSessions(),section: "session-management",},+ {+ label: "API key usage",+ route: Urls.monitorApiKeyUsage(),+ section: "api-key-usage",+ },] as const;it.each(SECTION_CASES)(@@ -326,7 +332,7 @@ describe("MonitorLayout", () => {});});- it("hides Dependency diagnostics for a monitoring-only user, and hides Alerts management (admin-only)", async () => {+ it("hides Dependency diagnostics for a monitoring-only user, and hides Alerts management and API key usage (admin-only)", async () => {setup({user: createMockUser({is_superuser: false,@@ -353,6 +359,10 @@ describe("MonitorLayout", () => {expect(screen.queryByRole("link", { name: "Alerts management" }),).not.toBeInTheDocument();+ // the page loads GET /api/api-key, which is superuser-only+ expect(+ screen.queryByRole("link", { name: "API key usage" }),+ ).not.toBeInTheDocument();});it("hides Alerts management for an analyst even with the monitoring permission", async () => {diff --git a/frontend/src/metabase/monitor/route-guards.tsx b/frontend/src/metabase/monitor/route-guards.tsxindex bfee9a50c9e..a25f30dff9b 100644--- a/frontend/src/metabase/monitor/route-guards.tsx+++ b/frontend/src/metabase/monitor/route-guards.tsx@@ -1,6 +1,7 @@import {canAccessAiAuditing,canAccessAlertsManagement,+ canAccessApiKeyUsage,canAccessMonitor,canAccessMonitorDiagnostics,canAccessMonitoringTools,@@ -43,6 +44,11 @@ const UserCanAccessAiAuditing = createRedirectGuard("/unauthorized",);+const UserCanAccessApiKeyUsage = createRedirectGuard(+ (state) => canAccessApiKeyUsage(state),+ "/unauthorized",+);+export const CanAccessMonitor = () => (<MetabaseIsSetup><UserIsAuthenticated>@@ -82,3 +88,9 @@ export const CanAccessAiAuditing = () => (<Outlet /></UserCanAccessAiAuditing>);++export const CanAccessApiKeyUsage = () => (+ <UserCanAccessApiKeyUsage>+ <Outlet />+ </UserCanAccessApiKeyUsage>+);diff --git a/frontend/src/metabase/monitor/route-guards.unit.spec.tsx b/frontend/src/metabase/monitor/route-guards.unit.spec.tsxindex a51f8fe4720..543bda189d9 100644--- a/frontend/src/metabase/monitor/route-guards.unit.spec.tsx+++ b/frontend/src/metabase/monitor/route-guards.unit.spec.tsx@@ -11,6 +11,7 @@ import {import {CanAccessAiAuditing,CanAccessAlertsManagement,+ CanAccessApiKeyUsage,CanAccessMonitor,} from "./route-guards";@@ -230,4 +231,71 @@ describe("monitor route-guards", () => {expect(screen.queryByText("ai auditing page")).not.toBeInTheDocument();});});++ describe("CanAccessApiKeyUsage", () => {+ interface SetupOpts {+ currentUser?: ReturnType<typeof createMockUser>;+ }++ const setup = ({ currentUser }: SetupOpts = {}) => {+ return renderWithProviders(+ <>+ <Route element={<CanAccessApiKeyUsage />}>+ <Route+ path="/monitor/api-key-usage"+ element={<div>api key usage page</div>}+ />+ </Route>+ <Route path="/unauthorized" element={<div>unauthorized</div>} />+ </>,+ {+ storeInitialState: createMockState({+ currentUser,+ settings: createMockSettingsState({ "has-user-setup": true }),+ }),+ withRouter: true,+ initialRoute: "/monitor/api-key-usage",+ },+ );+ };++ it("renders the page for superusers", async () => {+ setup({ currentUser: createMockUser({ is_superuser: true }) });++ expect(await screen.findByText("api key usage page")).toBeInTheDocument();+ });++ it("redirects a non-admin with monitoring permission to unauthorized without redirect-back", async () => {+ const { router } = setup({+ currentUser: createMockUser({+ is_superuser: false,+ is_data_analyst: false,+ permissions: { can_access_monitoring: true },+ }),+ });++ await waitFor(() => {+ expect(router?.location.pathname).toBe("/unauthorized");+ });++ expect(parseSearchQuery(router?.location.search ?? "")).toEqual({});+ expect(screen.queryByText("api key usage page")).not.toBeInTheDocument();+ });++ it("redirects an analyst to unauthorized without redirect-back", async () => {+ const { router } = setup({+ currentUser: createMockUser({+ is_superuser: false,+ is_data_analyst: true,+ }),+ });++ await waitFor(() => {+ expect(router?.location.pathname).toBe("/unauthorized");+ });++ expect(parseSearchQuery(router?.location.search ?? "")).toEqual({});+ expect(screen.queryByText("api key usage page")).not.toBeInTheDocument();+ });+ });});diff --git a/frontend/src/metabase/monitor/routes.tsx b/frontend/src/metabase/monitor/routes.tsxindex fcb9e2b167c..265d7eb115c 100644--- a/frontend/src/metabase/monitor/routes.tsx+++ b/frontend/src/metabase/monitor/routes.tsx@@ -29,6 +29,7 @@ import * as Urls from "metabase/urls";import {CanAccessAiAuditing,CanAccessAlertsManagement,+ CanAccessApiKeyUsage,CanAccessMonitor,CanAccessMonitorDiagnostics,CanAccessMonitoringTools,@@ -67,6 +68,13 @@ const dependencyDiagnosticsUpsellPage = () =>Component: DependencyDiagnosticsUpsellPage,}));+const apiKeyUsageUpsellPage = () =>+ import(+ /* webpackChunkName: "monitor" */ "metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage"+ ).then(({ ApiKeyUsageUpsellPage }) => ({+ Component: ApiKeyUsageUpsellPage,+ }));+const jobInfoApp = () =>import(/* webpackChunkName: "monitor" */ "metabase/monitor/tools/components/JobInfoApp"@@ -146,6 +154,22 @@ export function getMonitorRoutes() {</Route></Route>+ {/* Admin-only, unlike the rest of Monitoring tools above — the page loads+ `GET /api/api-key`, superuser-only, so a non-admin with just the monitoring+ application permission would hit a 403. */}+ <Route element={<CanAccessApiKeyUsage />}>+ {PLUGIN_MONITOR.isApiKeyUsageEnabled ? (+ <Route path="api-key-usage">+ {PLUGIN_MONITOR.getApiKeyUsageRoutes()}+ </Route>+ ) : (+ <Route path="api-key-usage">+ <Route index lazy={apiKeyUsageUpsellPage} />+ <Route path="*" lazy={apiKeyUsageUpsellPage} />+ </Route>+ )}+ </Route>+<Route element={<CanAccessAlertsManagement />}><Route path="notifications">{getNotificationsRoutes()}</Route></Route>diff --git a/frontend/src/metabase/monitor/routes.unit.spec.tsx b/frontend/src/metabase/monitor/routes.unit.spec.tsxindex fe3874660af..6072be3bda7 100644--- a/frontend/src/metabase/monitor/routes.unit.spec.tsx+++ b/frontend/src/metabase/monitor/routes.unit.spec.tsx@@ -6,7 +6,7 @@ describe("monitor routes", () => {it("resolves every page", async () => {const loaders = lazyLoaders(getMonitorRoutes());- expect(loaders).toHaveLength(15);+ expect(loaders).toHaveLength(17);for (const load of loaders) {expect((await load()).Component).toBeDefined();diff --git a/frontend/src/metabase/plugins/oss/monitor.ts b/frontend/src/metabase/plugins/oss/monitor.tsindex e6195932c32..afc9aa3904d 100644--- a/frontend/src/metabase/plugins/oss/monitor.ts+++ b/frontend/src/metabase/plugins/oss/monitor.ts@@ -7,6 +7,8 @@ type MonitorPlugin = {getDependencyDiagnosticsRoutes: () => ReactNode;isSessionManagementEnabled: boolean;getSessionManagementRoutes: () => ReactNode;+ isApiKeyUsageEnabled: boolean;+ getApiKeyUsageRoutes: () => ReactNode;};const getDefaultPluginMonitor = (): MonitorPlugin => ({@@ -14,6 +16,8 @@ const getDefaultPluginMonitor = (): MonitorPlugin => ({getDependencyDiagnosticsRoutes: () => null,isSessionManagementEnabled: false,getSessionManagementRoutes: () => null,+ isApiKeyUsageEnabled: false,+ getApiKeyUsageRoutes: () => null,});export const PLUGIN_MONITOR = definePluginSlot(getDefaultPluginMonitor);diff --git a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.cssindex 5c3b5603e13..1973871ac2d 100644--- a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css+++ b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css@@ -11,6 +11,7 @@.headerRow {border-bottom: 1px solid var(--mb-color-border-neutral);background-color: var(--mb-color-background_page-primary);+ user-select: none;}.cell {diff --git a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.cssindex dea369589d5..cdb513fa612 100644--- a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css+++ b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css@@ -29,6 +29,7 @@.content {display: flex;+ user-select: none;&:hover {background-color: var(--mb-color-background_surface-hover);@@ -68,12 +69,14 @@.treeCell {overflow: hidden;+ user-select: text;}.cell {overflow: hidden;text-overflow: ellipsis;white-space: nowrap;+ user-select: text;}.link {diff --git a/frontend/src/metabase/urls/monitor.ts b/frontend/src/metabase/urls/monitor.tsindex 4bb2e97fdd2..f044448e556 100644--- a/frontend/src/metabase/urls/monitor.ts+++ b/frontend/src/metabase/urls/monitor.ts@@ -142,3 +142,15 @@ export function monitorAiAuditingCliUsage() {export function monitorAiAuditingCliCalls() {return `${monitorAiAuditingCli()}/calls`;}++export function monitorApiKeyUsage() {+ return `${ROOT_URL}/api-key-usage`;+}++export function monitorApiKeyUsageOverview() {+ return `${monitorApiKeyUsage()}/usage`;+}++export function monitorApiKeyUsageEvents() {+ return `${monitorApiKeyUsage()}/events`;+}diff --git a/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.png b/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.pngnew file mode 100644index 00000000000..c82f8195d26Binary files /dev/null and b/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.png differdiff --git a/resources/migrations/065/20260907_api_key_usage_analytics.yaml b/resources/migrations/065/20260907_api_key_usage_analytics.yamlnew file mode 100644index 00000000000..1d84c92d82b--- /dev/null+++ b/resources/migrations/065/20260907_api_key_usage_analytics.yaml@@ -0,0 +1,163 @@+## API Key usage analytics storage layer.+##+## Two pieces:+## - api_key.last_used_at — cheap liveness for "is this key still in use?", updated in place.+## - api_key_usage_log — one row per API-key-authenticated request, modeled on+## agent_api_call_log / mcp_tool_call_log.+##+## The log row carries the resolved user and the key's real creator so the view needs no join back+## to api_key, which lets rows outlive a deleted key. `user_id` is the key's own synthetic+## service-account user (used for permission checks); `created_by_id` is the real human who created+## the key. `route_template` is the reconstructed Compojure route (e.g. /api/card/:id), never the raw+## URI or query string — those carry entity ids and filter values.++databaseChangeLog:+ - logicalFilePath: migrations/065_update_migrations.yaml++ - changeSet:+ id: v65.2026-09-07T00:00:00+ author: sfragnaud+ comment: Add api_key.last_used_at+ changes:+ - addColumn:+ tableName: api_key+ columns:+ - column:+ name: last_used_at+ type: ${timestamp_type}+ remarks: When this API key was last used to authenticate a request; NULL until first use. Updated in place (throttled), not per request.+ constraints:+ nullable: true++ - changeSet:+ id: v65.2026-09-07T00:00:01+ author: sfragnaud+ comment: Create api_key_usage_log table+ changes:+ - createTable:+ tableName: api_key_usage_log+ remarks: One row per API-key-authenticated request; user and key creator denormalized on so the view needs no api_key join (modeled on agent_api_call_log)+ columns:+ - column:+ name: id+ type: bigint+ autoIncrement: true+ remarks: Autoincrement primary key+ constraints:+ primaryKey: true+ nullable: false+ - column:+ name: api_key_id+ type: int+ remarks: The API key that authenticated the request. Deliberately not a foreign key so deleting a key does not cascade away its usage history.+ constraints:+ nullable: false+ - column:+ name: user_id+ type: int+ remarks: The API key's own synthetic service-account user, resolved at request time; NULL when the key has no user. Used for permission checks, not a real person. Not a foreign key, for the same reason as api_key_id. Non-PII.+ constraints:+ nullable: true+ - column:+ name: created_by_id+ type: int+ remarks: The real human who created the API key, resolved from the same auth query as user_id; NULL when the key has no user. Not a foreign key, for the same reason as api_key_id. Non-PII.+ constraints:+ nullable: true+ - column:+ name: route_template+ type: varchar(255)+ remarks: Reconstructed route template of the request, e.g. /api/card/:id. Never the raw URI or query string. Non-PII.+ constraints:+ nullable: false+ - column:+ name: http_method+ type: varchar(10)+ remarks: HTTP method of the request, e.g. GET or POST. Non-PII.+ constraints:+ nullable: false+ - column:+ name: status+ type: int+ remarks: HTTP status code of the response. Non-PII. Streamed responses (for example query results) always store 202, because the real status is only known after the stream ends, so do not read 202 as an outcome.+ constraints:+ nullable: false+ - column:+ name: duration_ms+ type: int+ remarks: Wall-clock duration of the request in milliseconds+ constraints:+ nullable: false+ - column:+ name: occurred_at+ type: ${timestamp_type}+ defaultValueComputed: current_timestamp+ remarks: When the request happened, captured on the request thread. The default is a fallback only — the recorder always sets this explicitly, since the row itself may not land in the table until a scheduled flush later.+ constraints:+ nullable: false+ - column:+ name: ip_address+ type: varchar(45)+ remarks: Client IP captured at request time, PII (gated by analytics-pii-retention-enabled).+ constraints:+ nullable: true+ - column:+ name: user_agent+ type: varchar(512)+ remarks: Raw User-Agent header captured at request time, PII (gated by analytics-pii-retention-enabled).+ constraints:+ nullable: true+ - column:+ name: client_name+ type: varchar(255)+ remarks: Caller classified from the raw User-Agent (metabase-cli, curl, postman, python-requests, r, node, or other). Non-PII, always recorded — distinct from the raw, PII-gated user_agent column.+ constraints:+ nullable: false+ - column:+ name: embedding_client+ type: varchar(255)+ remarks: Raw X-Metabase-Client header value, when present. Non-PII, same status as view_log/query_execution.embedding_client. Supplementary to client_name (the primary classification axis) — almost never set on API-key traffic, since the SDK/embed.js clients that send it authenticate via JWT/SSO, not API keys.+ constraints:+ nullable: true+ rollback:+ - dropTable:+ tableName: api_key_usage_log++ - changeSet:+ id: v65.2026-09-07T00:00:02+ author: sfragnaud+ comment: Index on api_key_usage_log.api_key_id+ changes:+ - createIndex:+ indexName: idx_api_key_usage_log_api_key_id+ tableName: api_key_usage_log+ columns:+ - column:+ name: api_key_id+ rollback: # dropped with table++ - changeSet:+ id: v65.2026-09-07T00:00:03+ author: sfragnaud+ comment: Index on api_key_usage_log.created_by_id+ changes:+ - createIndex:+ indexName: idx_api_key_usage_log_created_by_id+ tableName: api_key_usage_log+ columns:+ - column:+ name: created_by_id+ rollback: # dropped with table++ - changeSet:+ id: v65.2026-09-07T00:00:04+ author: sfragnaud+ comment: Index on api_key_usage_log.occurred_at+ changes:+ - createIndex:+ indexName: idx_api_key_usage_log_occurred_at+ tableName: api_key_usage_log+ columns:+ - column:+ name: occurred_at+ rollback: # dropped with tablediff --git a/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yaml b/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yamlnew file mode 100644index 00000000000..6d29b2d4f32--- /dev/null+++ b/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yaml@@ -0,0 +1,35 @@+## Add embedding_hostname to api_key_usage_log.+##+## The createTable changeset for api_key_usage_log (20260907_api_key_usage_analytics.yaml) already+## shipped as far as this branch's own ancestry is concerned — editing it in place, like the earlier+## client_name/embedding_client columns did, would change its checksum out from under any branch+## that already recorded it. That's a real (not just style) requirement: Liquibase validates a+## changeset's checksum against what was previously applied, and CI's cross-branch-migration-test+## boots this PR's base branch first, then this PR's branch, so any downstream edit to an+## already-applied changeset fails validation. A new column always needs a new changeset here.+##+## Filename intentionally sorts between the table-creation migration (20260907) and the view+## migration (20260910) — includeAll processes files alphabetically, and the view's SELECT+## references this column, so the column must exist before the view is (re)created.++databaseChangeLog:+ - logicalFilePath: migrations/065_update_migrations.yaml++ - changeSet:+ id: v65.2026-09-08T00:00:00+ author: sfragnaud+ comment: Add embedding_hostname to api_key_usage_log+ changes:+ - addColumn:+ tableName: api_key_usage_log+ columns:+ - column:+ name: embedding_hostname+ type: varchar(512)+ remarks: Hostname parsed from the embed referrer header, when present. Non-PII, same status as view_log/query_execution/metabot_conversation.embedding_hostname. Only meaningful alongside embedding_client.+ constraints:+ nullable: true+ rollback:+ - dropColumn:+ tableName: api_key_usage_log+ columnName: embedding_hostnamediff --git a/resources/migrations/065/20260910_api_key_usage_analytics_view.yaml b/resources/migrations/065/20260910_api_key_usage_analytics_view.yamlnew file mode 100644index 00000000000..9bebfbae35f--- /dev/null+++ b/resources/migrations/065/20260910_api_key_usage_analytics_view.yaml@@ -0,0 +1,35 @@+## Create the v_api_key_usage view for API-key usage analytics.+##+## Filename intentionally sorts after 20260907_api_key_usage_analytics.yaml (the table-creation+## migration) so Liquibase — which processes change-log files alphabetically — creates the+## api_key_usage_log table before this view references it.+##+## Client identity + PII are stored on each request row, so v_api_key_usage reads them straight off+## api_key_usage_log. Every join is a LEFT JOIN: api_key_usage_log deliberately has no foreign keys+## on api_key_id / user_id / created_by_id so rows outlive a deleted key or user — an inner join+## would silently drop that history, so api_key_name / creator_display_name / group_name are simply+## NULL once the referenced row is gone.++databaseChangeLog:+ - logicalFilePath: migrations/065_update_migrations.yaml++ - changeSet:+ id: v65.2026-09-10T00:00:10+ author: sfragnaud+ runOnChange: true+ comment: Create v_api_key_usage view for API-key usage analytics+ changes:+ - sqlFile:+ dbms: postgresql+ path: ../instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql+ relativeToChangelogFile: true+ - sqlFile:+ dbms: mysql,mariadb+ path: ../instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql+ relativeToChangelogFile: true+ - sqlFile:+ dbms: h2+ path: ../instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql+ relativeToChangelogFile: true+ rollback:+ - sql: DROP VIEW IF EXISTS v_api_key_usagediff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sqlnew file mode 100644index 00000000000..fde5ff8ab30--- /dev/null+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql@@ -0,0 +1,52 @@+DROP VIEW IF EXISTS v_api_key_usage;++CREATE OR REPLACE VIEW v_api_key_usage AS+SELECT+ t.id AS log_id,+ t.occurred_at,+ t.route_template,+ t.http_method,+ t.status,+ t.duration_ms,+ t.api_key_id AS api_key_id,+ ak.name AS api_key_name,+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).+ t.user_id AS actor_user_id,+ -- creator: the real human who made the key — a different person from the actor above.+ t.created_by_id AS creator_id,+ -- CAST to VARCHAR: H2 declares core_user.email VARCHAR_IGNORECASE (for case-insensitive lookups),+ -- and COALESCE inherits that type, which Metabase's H2 type mapper doesn't recognize — it falls back+ -- to an unknown type, and metabase-lib silently excludes unknown-typed columns from sortable columns.+ CAST(COALESCE(creator.first_name || ' ' || creator.last_name, creator.email) AS VARCHAR) AS creator_display_name,+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has+ -- exactly one group, but its creator may belong to several. Ordered so a specific group+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = ak.user_id+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, 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/api_keys/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'curl' THEN 'curl'+ WHEN 'postman' THEN 'Postman'+ WHEN 'python-requests' THEN 'Python'+ WHEN 'r' THEN 'R'+ WHEN 'node' THEN 'Node.js'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.embedding_client AS embedding_client,+ t.embedding_hostname AS embedding_hostname,+ t.ip_address AS ip_address,+ t.user_agent AS user_agent+FROM api_key_usage_log t+LEFT JOIN api_key ak+ ON ak.id = t.api_key_id+LEFT JOIN core_user creator+ ON creator.id = t.created_by_id;diff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sqlnew file mode 100644index 00000000000..6e74dd94e70--- /dev/null+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql@@ -0,0 +1,49 @@+DROP VIEW IF EXISTS v_api_key_usage;++CREATE OR REPLACE VIEW v_api_key_usage AS+SELECT+ t.id AS log_id,+ t.occurred_at,+ t.route_template,+ t.http_method,+ t.status,+ t.duration_ms,+ t.api_key_id AS api_key_id,+ ak.name AS api_key_name,+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).+ t.user_id AS actor_user_id,+ -- creator: the real human who made the key — a different person from the actor above.+ t.created_by_id AS creator_id,+ COALESCE(CONCAT(creator.first_name, ' ', creator.last_name), creator.email) AS creator_display_name,+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has+ -- exactly one group, but its creator may belong to several. Ordered so a specific group+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = ak.user_id+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, 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/api_keys/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'curl' THEN 'curl'+ WHEN 'postman' THEN 'Postman'+ WHEN 'python-requests' THEN 'Python'+ WHEN 'r' THEN 'R'+ WHEN 'node' THEN 'Node.js'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.embedding_client AS embedding_client,+ t.embedding_hostname AS embedding_hostname,+ t.ip_address AS ip_address,+ t.user_agent AS user_agent+FROM api_key_usage_log t+LEFT JOIN api_key ak+ ON ak.id = t.api_key_id+LEFT JOIN core_user creator+ ON creator.id = t.created_by_id;diff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sqlnew file mode 100644index 00000000000..21edcdcf3e2--- /dev/null+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql@@ -0,0 +1,49 @@+DROP VIEW IF EXISTS v_api_key_usage;++CREATE OR REPLACE VIEW v_api_key_usage AS+SELECT+ t.id AS log_id,+ t.occurred_at,+ t.route_template,+ t.http_method,+ t.status,+ t.duration_ms,+ t.api_key_id AS api_key_id,+ ak.name AS api_key_name,+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).+ t.user_id AS actor_user_id,+ -- creator: the real human who made the key — a different person from the actor above.+ t.created_by_id AS creator_id,+ COALESCE(creator.first_name || ' ' || creator.last_name, creator.email) AS creator_display_name,+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has+ -- exactly one group, but its creator may belong to several. Ordered so a specific group+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.+ (SELECT pg.name+ FROM permissions_group_membership pgm+ JOIN permissions_group pg ON pg.id = pgm.group_id+ WHERE pgm.user_id = ak.user_id+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, 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/api_keys/usage.clj (the enum-<->-CASE sync footgun).+ CASE t.client_name+ WHEN 'metabase-cli' THEN 'Metabase CLI'+ WHEN 'curl' THEN 'curl'+ WHEN 'postman' THEN 'Postman'+ WHEN 'python-requests' THEN 'Python'+ WHEN 'r' THEN 'R'+ WHEN 'node' THEN 'Node.js'+ WHEN 'other' THEN 'Other'+ ELSE t.client_name+ END AS client_display_name,+ t.embedding_client AS embedding_client,+ t.embedding_hostname AS embedding_hostname,+ t.ip_address AS ip_address,+ t.user_agent AS user_agent+FROM api_key_usage_log t+LEFT JOIN api_key ak+ ON ak.id = t.api_key_id+LEFT JOIN core_user creator+ ON creator.id = t.created_by_id;diff --git a/src/metabase/api/macros.clj b/src/metabase/api/macros.cljindex 24353ee13c5..ff9cce3131c 100644--- a/src/metabase/api/macros.clj+++ b/src/metabase/api/macros.clj@@ -870,32 +870,64 @@[:map-of ::method [:sequential [:tuple(ms/InstanceOfClass clout.core.CompiledRoute)::handler- [:maybe ::route-metadata]]]])+ [:maybe ::route-metadata]+ #_route-path :string]]])(mu/defn- ns-handler-map :- ::handler-map- "Build a map of method => [[clout-route handler metadata]+] used to power the combined ns handler built- by [[build-ns-handler]]."+ "Build a map of method => [[clout-route handler metadata route-path]+] used to power the combined ns handler built+ by [[build-ns-handler]].++ `route-path` is the raw (uncompiled) Clout pattern the endpoint declared, e.g. `\"/:id\"`. Route-param regexes are+ compiled into the [[clout.core.CompiledRoute]] but deliberately kept out of `route-path`, so it holds placeholder+ names only — that is what [[route-template]] needs."[endpoints :- ::ns-endpoints](->> endpointsvals(group-by #(get-in % [:form :method]))(m/map-vals (fn [routes](mapv (fn [route]- [(clout/route-compile (get-in route [:form :route :path])- (update-keys (get-in route [:form :route :regexes] {}) keyword))- (:handler route)- (get-in route [:form :metadata])])+ (let [path (get-in route [:form :route :path])]+ [(clout/route-compile path (update-keys (get-in route [:form :route :regexes] {}) keyword))+ (:handler route)+ (get-in route [:form :metadata])+ path]))routes)))))(defn- decode-route-params [route-params](update-vals route-params ring.util.codec/url-decode))+(defn- request-route-prefix+ "Route prefix accumulated for `request` so far: the [[metabase.api.util.handlers/route-map-handler]] levels it+ descended through, or — for an ns handler mounted straight under a `compojure.core/context` with no route map in+ between — the context patterns alone."+ [request]+ (or (:route-prefix request)+ (:compojure/route-context request)))++(mu/defn- route-template :- :string+ "Reconstruct the full route template for a matched endpoint, e.g. `\"/api/card/:id\"`.++ `route-prefix` is the prefix accumulated by [[metabase.api.util.handlers/route-map-handler]] as routing descended+ (seeded with the enclosing `compojure.core/context` patterns, so `/api` is included); `route-path` is the+ ns-relative Clout pattern the endpoint declared.++ This is built purely from declared route structure. It never contains request values — no query string, no+ `:query-params`, and no concrete path-param values — which is what makes it safe to store for analytics."+ [route-prefix :- [:maybe :string]+ route-path :- :string]+ (let [prefix (or route-prefix "")]+ ;; A `\"/\"` endpoint is the prefix itself (`GET /api/card` matches the `\"/\"` route of `metabase.queries-rest.api`+ ;; because each route-map level leaves `\"/\"` behind), so don't tack on a meaningless trailing slash.+ (if (= route-path "/")+ (if (str/blank? prefix) "/" prefix)+ (str prefix route-path))))+(mu/defn- find-matching-handler :- [:maybe [:tuple ::request ::handler]]"Find the appropriate handler from `handler-map` to handle `request`. Returns a tuple of[request' handler]- (Request is updated to include parsed Clout parameters and route metadata.)"+ (Request is updated to include parsed Clout parameters, route metadata, and the reconstructed `:route-template`.)"[handler-map :- ::handler-maprequest :- ::request](let [request-method (:request-method request)@@ -904,14 +936,31 @@request (cond-> requestpath (assoc :path-info path))];; TODO -- we could probably make this a little faster by unrolling this loop- (some (fn [[route handler metadata]]+ (some (fn [[route handler metadata route-path]](when-let [route-params (clout/route-matches route request)][(-> request(assoc :route-params (decode-route-params route-params))- (assoc :route-metadata metadata))+ (assoc :route-metadata metadata)+ (assoc :route-template (route-template (request-route-prefix request) route-path)))handler]))handlers)))+(def route-template-carrier-key+ "Request key under which middleware running *above* the routing tree can put a `volatile!` in order to learn which+ route template ended up matching.++ `:route-template` is added to a request that routing builds for the matched endpoint alone+ (see [[find-matching-handler]]); it never travels back up, and neither does anything else reliable. Response+ metadata would cover successful responses, but an endpoint that throws — which is how most 4xx/5xx are produced —+ has its response built from the exception by `metabase.server.middleware.exceptions/catch-api-exceptions`, losing+ any metadata the endpoint's response would have carried. A carrier owned by the outer middleware covers both, the+ same way `log-api-call` already collects DB call counts from deep inside a request.++ The carrier is optional: routing pays a single map lookup regardless, whether or not one is installed. See+ `metabase.server.middleware.route-template-carrier/wrap-route-template-carrier`, which installs one+ unconditionally on every request."+ ::route-template-carrier)+(mu/defn- build-ns-handler :- ::handler"Build a combined Ring handler for all `endpoints` that routes requests to the matching handler (if any)."[endpoints :- ::ns-endpoints]@@ -919,7 +968,9 @@(open-api/handler-with-open-api-spec(fn ns-handler* [request respond raise](if-let [[request* handler] (find-matching-handler handler-map request)]- (handler request* respond raise)+ (do+ (some-> (get request route-template-carrier-key) (vreset! (:route-template request*)))+ (handler request* respond raise))(respond nil)))(fn [prefix](metabase.api.macros.defendpoint.open-api/open-api-spec endpoints prefix)))))diff --git a/src/metabase/api/util/handlers.clj b/src/metabase/api/util/handlers.cljindex 47227f47fd6..c50283931e6 100644--- a/src/metabase/api/util/handlers.clj+++ b/src/metabase/api/util/handlers.clj@@ -15,11 +15,24 @@[(subs path 0 next-slash-index) (subs path next-slash-index (count path))][path "/"])))+(defn- route-prefix+ "The `:route-prefix` for `request` after this route-map level consumed `prefix`.++ The first route-map level seeds the accumulator from `:compojure/route-context` — the route *patterns* of the+ enclosing `compojure.core/context` forms, which is how the leading `/api`+ from [[metabase.server.routes/make-routes]] gets into the template. We use `:compojure/route-context` rather than+ Ring's `:context` because `:context` is sliced out of the request URI and would carry real path-param values for a+ parameterized context; `:compojure/route-context` is always the declared pattern."+ [request prefix]+ (str (or (:route-prefix request) (:compojure/route-context request)) prefix))+(defn- -route-map-handler [route-map](fn [request respond raise](if-let [[prefix rest-of-path] (split-path ((some-fn :path-info :uri) request))](if-let [handler (get route-map prefix)]- (let [request' (assoc request :path-info rest-of-path)]+ (let [request' (-> request+ (assoc :path-info rest-of-path)+ (assoc :route-prefix (route-prefix request prefix)))](handler request' respond raise))(respond nil))(respond nil))))@@ -46,7 +59,11 @@(simple-symbol? v) api.macros/ns-handler))))(defn route-map-handler- "Create a Ring handler from a map of route prefix => handler."+ "Create a Ring handler from a map of route prefix => handler.++ As routing descends, each level appends the prefix it consumed to the request's `:route-prefix`, which+ `metabase.api.macros` turns into the matched request's `:route-template` (e.g. `\"/api/card/:id\"`). Only declared+ route patterns are accumulated — never anything from the request URI or query string."[route-map](let [route-map (prepare-route-map route-map)](open-api/handler-with-open-api-specdiff --git a/src/metabase/api_keys/api.clj b/src/metabase/api_keys/api.cljindex 0b2491a038b..a65f3989ea5 100644--- a/src/metabase/api_keys/api.clj+++ b/src/metabase/api_keys/api.clj@@ -29,7 +29,8 @@:group:unmasked_key:name- :masked_key])+ :masked_key+ :last_used_at])(maybe-expose-key)(update :updated_by #(select-keys % [:common_name :id]))))diff --git a/src/metabase/api_keys/core.clj b/src/metabase/api_keys/core.cljindex e9edf04f565..4975a17a800 100644--- a/src/metabase/api_keys/core.clj+++ b/src/metabase/api_keys/core.clj@@ -1,9 +1,12 @@(ns metabase.api-keys.core(:require+ [metabase.api-keys.db][metabase.api-keys.models.api-key][potemkin :as p]))-(comment metabase.api-keys.models.api-key/keep-me)+(comment+ metabase.api-keys.models.api-key/keep-me+ metabase.api-keys.db/keep-me)(p/import-vars[metabase.api-keys.models.api-key@@ -11,3 +14,7 @@is-api-key-user?prefixcreate-api-key-with-new-user!])++(p/import-vars+ [metabase.api-keys.db+ update-api-keys-last-used-at!])diff --git a/src/metabase/api_keys/db.clj b/src/metabase/api_keys/db.cljindex b651de0c3ea..402a50c1716 100644--- a/src/metabase/api_keys/db.clj+++ b/src/metabase/api_keys/db.clj@@ -2,8 +2,10 @@"Application database queries for the API keys module. Every function here is a direct Toucan 2 call with noadditional logic, so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`)."(:require+ [java-time.api :as t][malli.util :as mut][metabase.api-keys.schema :as api-keys.schema]+ [metabase.app-db.core :as mdb][metabase.lib.schema.id :as lib.schema.id][metabase.users.schema :as users.schema][metabase.util.malli :as mu]@@ -16,9 +18,15 @@(t2/count :model/ApiKey :scope nil))(mu/defn unscoped-api-keys- "The ApiKeys without a scope."+ "The ApiKeys without a scope, most recently used first (nulls last — a key never used sorts after+ every key that has been)."[]- (t2/select :model/ApiKey :scope nil))+ (t2/select :model/ApiKey :scope nil+ {:order-by [[:last_used_at (case (mdb/db-type)+ ;; NULLS LAST isn't valid MySQL syntax, but MySQL already sorts+ ;; NULLs last on DESC by default (it treats NULL as the lowest value).+ (:postgres :h2) :desc-nulls-last+ :mysql :desc)]]}))(mu/defn api-key"The ApiKey with `id`, or nil."@@ -98,3 +106,47 @@[id :- ms/PositiveIntchanges :- (mut/select-keys ::api-keys.schema/api-key.update [:key :key_prefix :updated_by_id])](t2/update! :model/ApiKey :id id changes))++(defn lock-available-key-ids+ "The subset of `ids` not currently locked by another writer, locked for update (`SKIP LOCKED` outside+ H2, whose single-connection test usage neither needs nor supports it). Public so tests can simulate a+ busy row by redefining it, without real cross-connection lock contention."+ [ids]+ (map :id (t2/query (cond-> {:select [:id]+ :from [(t2/table-name :model/ApiKey)]+ :where [:in :id ids]}+ (not= :h2 (mdb/db-type)) (assoc :for [:update :skip-locked])))))++(defn update-api-keys-last-used-at!+ "Move `last_used_at` of each ApiKey in `id->timestamp` forward to its timestamp, without touching+ `updated_at`. Returns the subset of `id->timestamp` that was skipped because another writer held the+ row — the caller should retry those on its next pass rather than wait for them here. A deleted key's+ id is dropped rather than retried: it never comes back from [[lock-available-key-ids]], but it is+ gone for good, not merely busy, so retrying it on every flush would never succeed.++ Locks the rows first with `SELECT ... FOR UPDATE SKIP LOCKED` (outside H2) so a key a concurrent+ writer is editing (e.g. an admin renaming or rotating it) is skipped rather than blocking this+ UPDATE — and, by extension, every unrelated key batched alongside it — until that writer's+ transaction commits.++ A plain UPDATE rather than [[update-api-key!]] on purpose: the model's `before-update` hook hydrates+ the key and publishes an `:event/api-key-update` audit event, which a usage stamp must not do.+ Mirrors [[metabase.query-processor.db/update-cards-last-used-at!]]'s bulk `CASE`/`GREATEST` pattern+ for the same reason: many keys land in one batch, and this is one UPDATE for all of them rather than+ one per key."+ [id->timestamp]+ (t2/with-transaction [_conn]+ (let [available-ids (lock-available-key-ids (keys id->timestamp))]+ (when (seq available-ids)+ (t2/query {:update [(t2/table-name :model/ApiKey)]+ :where [:in :id available-ids]+ :set {:last_used_at (into [:case]+ (mapcat (fn [id]+ [[:= :id id]+ [:greatest [:coalesce :last_used_at (t/offset-date-time 0)]+ (get id->timestamp id)]])+ available-ids))+ :updated_at :updated_at}}))+ (select-keys id->timestamp+ (when-let [busy (seq (remove (set available-ids) (keys id->timestamp)))]+ (t2/select-pks-set :model/ApiKey :id [:in busy]))))))diff --git a/src/metabase/api_keys/models/api_key_usage_log.clj b/src/metabase/api_keys/models/api_key_usage_log.cljnew file mode 100644index 00000000000..4f85daafc00--- /dev/null+++ b/src/metabase/api_keys/models/api_key_usage_log.clj@@ -0,0 +1,9 @@+(ns metabase.api-keys.models.api-key-usage-log+ (:require+ [methodical.core :as methodical]+ [toucan2.core :as t2]))++(methodical/defmethod t2/table-name :model/ApiKeyUsageLog [_model] :api_key_usage_log)++(doto :model/ApiKeyUsageLog+ (derive :metabase/model))diff --git a/src/metabase/api_keys/schema.clj b/src/metabase/api_keys/schema.cljindex 9546861c27a..61ba196c0a2 100644--- a/src/metabase/api_keys/schema.clj+++ b/src/metabase/api_keys/schema.clj@@ -106,6 +106,7 @@[:updated_by_id pos-int?][:scope {:optional true} [:maybe [:ref ::scope]]][:single_collection_id {:optional true} [:maybe pos-int?]]+ [:last_used_at {:optional true} [:maybe [:ref ::timestamp]]];; added by the model's after-select hook[:masked_key {:optional true} :string]])diff --git a/src/metabase/api_keys/usage.clj b/src/metabase/api_keys/usage.cljnew file mode 100644index 00000000000..48fc8d4daa3--- /dev/null+++ b/src/metabase/api_keys/usage.clj@@ -0,0 +1,88 @@+(ns metabase.api-keys.usage+ "API-key usage logging.++ One entry point, [[record-api-key-usage!]], feeds two things per API-key-authenticated `/api/*`+ request: a lean `api_key_usage_log` row, and an `api_key.last_used_at` stamp that answers \"is this+ key still in use?\" cheaply. Callers don't need to know there are two internal write strategies —+ see `metabase-enterprise.api-keys.usage` for why they're split and how each is batched. This is a+ `defenterprise` no-op in OSS — an OSS instance records nothing — with the real writes in+ `metabase-enterprise.api-keys.usage`. Like `ai_usage_log`, collection runs on every EE instance+ (`:feature :none`); the `:audit-app` feature gates the surfaces that read these rows, not the+ writing.++ The function takes the raw Ring `request`/`response` and extracts everything itself; the caller+ (the `log-api-call` hook) supplies only the handful of values it alone can compute — see+ `metabase-enterprise.api-keys.usage/record-api-key-usage!`'s docstring for the `extra-info` shape.++ PII columns (`ip_address`, `user_agent`) 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`. `route_template` is the reconstructed Compojure route (e.g. `/api/card/:id`),+ never the raw URI or query string, so entity ids and filter values never land in the table.++ No free-text error column, deliberately. `mcp_tool_call_log` stores a truncated, PII-gated+ `error_message`, but `/api/*` failures echo submitted request data far more often than MCP tool+ calls do — validation errors quote the offending value, native-query errors quote the SQL — so an+ error string here would drag request payloads into an analytics table behind nothing but a PII+ toggle. `api_key_usage_log` therefore has no error column at all: the non-PII `status` column (the+ HTTP status code) already separates success from failure, and there is nothing free-text left to+ gate.++ `client_name` is classified from the caller's self-reported `User-Agent` via [[detect-client]] —+ analytics only, never used to gate access — mirroring `agent_api_call_log`'s `client_name`. Unlike+ `user_agent` (raw, PII-gated), `client_name` is a canonical, low-cardinality value and is always+ recorded.++ `embedding_client` is the raw `X-Metabase-Client` header, when present — non-PII (same status as+ `view_log`/`query_execution.embedding_client`), passed through unclassified. It's supplementary:+ `client_name` stays the primary classification axis, since almost no API-key traffic sets this+ header (the SDK/embed.js clients that do authenticate via JWT/SSO, not API keys).++ `embedding_hostname` is the hostname parsed from the embed referrer header, when present — non-PII+ (same status as `view_log`/`query_execution`/`metabot_conversation.embedding_hostname`), always+ recorded. Only meaningful alongside `embedding_client`: the SDK sends an API key only on localhost,+ so a non-localhost hostname on embedding traffic is worth flagging."+ (: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_api_key_usage` view SQL (the enum-<->-CASE sync footgun)."+ #{"metabase-cli" "curl" "postman" "python-requests" "r" "node"})++(def ^:private client-name-matchers+ "Ordered `[substring canonical-key]` pairs matched against the lowercased `User-Agent`. First match+ wins. `r-curl` is checked before the generic `curl` so R's httr (whose User-Agent embeds `r-curl`)+ doesn't fall through to the plain curl classification. Covers the tools/languages the public API+ docs demonstrate, plus the Metabase CLI, which authenticates exclusively via API key."+ [["metabase-cli" "metabase-cli"]+ ["postmanruntime" "postman"]+ ["python-requests" "python-requests"]+ ["r-curl" "r"]+ ["got (https" "node"]+ ["curl" "curl"]])++(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-api-key-usage!+ "Record one completed API-key-authenticated request: write an `api_key_usage_log` row and stamp+ `api_key.last_used_at`. OSS no-op."+ metabase-enterprise.api-keys.usage+ [_request _response _extra-info]+ nil)++(defenterprise flush-pending-writes!+ "Synchronously flush any pending [[record-api-key-usage!]] writes instead of waiting for the+ scheduled interval. OSS no-op."+ metabase-enterprise.api-keys.usage+ []+ nil)diff --git a/src/metabase/metabot/settings.clj b/src/metabase/metabot/settings.cljindex 00a090f8f89..5d7222b2eca 100644--- a/src/metabase/metabot/settings.clj+++ b/src/metabase/metabot/settings.clj@@ -332,7 +332,7 @@env-var-value)))(defsetting ai-usage-max-retention-days- (deferred-tru "Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely.")+ (deferred-tru "Number of days to retain rows in the ai_usage_log, metabot_conversation, metabot_message, agent_api_call_log, and api_key_usage_log tables. Minimum value is 30; set to 0 to retain data indefinitely."):type :integer:visibility :admin:setter :none@@ -346,6 +346,7 @@- `metabot_conversation`- `metabot_message`- `agent_api_call_log`+- `api_key_usage_log`Once a day, Metabase deletes rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).If set to 0, Metabase will keep all rows. If you don't set this variable, Metabase keeps rows for 180 days.")diff --git a/src/metabase/models/resolution.clj b/src/metabase/models/resolution.cljindex 55c0c20af08..c66e7bb12ca 100644--- a/src/metabase/models/resolution.clj+++ b/src/metabase/models/resolution.clj@@ -17,6 +17,7 @@: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+ :model/ApiKeyUsageLog metabase.api-keys.models.api-key-usage-log:model/ApplicationPermissionsRevision metabase.permissions.models.application-permissions-revision:model/AuditLog metabase.audit-app.models.audit-log:model/AuthIdentity metabase.auth-identity.models.auth-identitydiff --git a/src/metabase/request/schema.clj b/src/metabase/request/schema.cljindex 432ba6057b6..16930312088 100644--- a/src/metabase/request/schema.clj+++ b/src/metabase/request/schema.clj@@ -18,7 +18,12 @@[:token-scopes {:optional true} [:maybe [:set [:or :keyword :string]]]][:token-scopes-checked {:optional true} :boolean][:data-app-scoped? {:optional true} :boolean]- [:authenticated-via-oauth? {:optional true} :boolean]])+ [:authenticated-via-oauth? {:optional true} :boolean]+ ;; only API-key auth resolves these two: `:api-key-id` identifies the key itself (for per-key usage analytics),+ ;; and `:api-key-creator-id` is the real human who created the key (distinct from `:metabase-user-id`, the key's+ ;; own synthetic service-account user) — both read off the same auth query rather than looked up again later.+ [:api-key-id {:optional true} pos-int?]+ [:api-key-creator-id {:optional true} [:maybe pos-int?]]])(mr/def ::multipart-file"One `:multipart-params` entry for an uploaded file, as `ring.middleware.multipart-params` builds it."@@ -61,6 +66,16 @@[:route-params {:optional true} ms/RingRequestParams][:cookies {:optional true} [:map-of :string ::cookie-attrs]][:route-metadata {:optional true} [:maybe :metabase.api.macros/route-metadata]]+ ;; accumulated by `metabase.api.util.handlers/route-map-handler` as routing descends; consumed by+ ;; `metabase.api.macros/request-route-prefix` to reconstruct the matched route's template.+ [:route-prefix {:optional true} [:maybe :string]]+ ;; the reconstructed Clout pattern of the endpoint that matched, e.g. `/api/card/:id` — see+ ;; `metabase.api.macros/route-template`.+ [:route-template {:optional true} [:maybe :string]]+ ;; a `volatile!` middleware running above the routing tree can install so it learns which route+ ;; template matched, even for a response built from an exception — see+ ;; `metabase.api.macros/route-template-carrier-key`.+ [:metabase.api.macros/route-template-carrier {:optional true} [:maybe (ms/InstanceOfClass clojure.lang.Volatile)]][:compojure/path {:optional true} :string][:compojure/route-context {:optional true} [:maybe :string]][:context {:optional true} [:maybe :string]]@@ -83,6 +98,9 @@[:user-locale {:optional true} [:maybe :string]][:embedding/auth-method {:optional true} [:maybe :string]][:metabase/authed-session-key-hash {:optional true} [:maybe :string]]+ ;; only API-key auth resolves these two — see `::current-user-info`.+ [:api-key-id {:optional true} [:maybe :int]]+ [:api-key-creator-id {:optional true} [:maybe :int]][:token-exchange? {:optional true} :boolean][:metabase.server.middleware.offset-paging/limit {:optional true} [:maybe :int]][:metabase.server.middleware.offset-paging/offset {:optional true} [:maybe :int]]diff --git a/src/metabase/server/db.clj b/src/metabase/server/db.cljindex 96f3b4fd82a..af670ea81f9 100644--- a/src/metabase/server/db.clj+++ b/src/metabase/server/db.clj@@ -66,7 +66,13 @@(fn [enable-advanced-permissions?](first(t2.pipeline/compile*- (cond-> {:select [[:api_key.user_id :metabase-user-id]+ ;; `api-key-id` and `api-key-creator-id` are here for API-key usage analytics: the auth query already has+ ;; both rows joined, so carrying them on the request costs nothing and spares the response path a second+ ;; lookup. `api-key-creator-id` is the real human who created the key — distinct from `metabase-user-id`,+ ;; which is the key's own synthetic service-account user used for permission checks.+ (cond-> {:select [[:api_key.id :api-key-id]+ [:api_key.creator_id :api-key-creator-id]+ [:api_key.user_id :metabase-user-id][:api_key.key :api-key][:user.is_superuser :is-superuser?][:user.is_data_analyst :is-data-analyst?]@@ -132,8 +138,8 @@(t2/query-one (cons sql params))))(mu/defn api-key-user-info- "The user id, api key, superuser/data-analyst/group-manager flags, and locale for the active User whose ApiKey- starts with `key-prefix`, or nil if there is none."+ "The API key id, user id, api key, superuser/data-analyst/group-manager flags, and locale for the active User+ whose ApiKey starts with `key-prefix`, or nil if there is none."[key-prefix :- :stringenable-advanced-permissions? :- :boolean](t2/query-one (cons (user-data-for-api-key-prefix-query enable-advanced-permissions?) [key-prefix])))diff --git a/src/metabase/server/handler.clj b/src/metabase/server/handler.cljindex 3b0780c2eb1..c17e6b25ed0 100644--- a/src/metabase/server/handler.clj+++ b/src/metabase/server/handler.clj@@ -17,6 +17,7 @@[metabase.server.middleware.offset-paging :as mw.offset-paging][metabase.server.middleware.premium-features-cache :as mw.pf-cache][metabase.server.middleware.request-id :as mw.request-id]+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier][metabase.server.middleware.security :as mw.security][metabase.server.middleware.session :as mw.session][metabase.server.middleware.settings-cache :as mw.settings-cache]@@ -115,6 +116,7 @@#'wrap-gzip ; GZIP response if client can handle it#'mw.trace/wrap-trace ; Create root OpenTelemetry span per request (after request-id is available)#'mw.request-id/wrap-request-id ; Add a unique request ID to the request+ #'mw.route-template-carrier/wrap-route-template-carrier ; Install a carrier so routing can report which route matched#'mw.misc/bind-request ; bind `metabase.middleware.misc/*request*` for the duration of the request#'mw.ssl/redirect-to-https-middlewarewrap-reload-dev-mw ; reloads outdated clojure code when --hot flag is passed with the :dev-start aliasdiff --git a/src/metabase/server/middleware/log.clj b/src/metabase/server/middleware/log.cljindex 0a385e7f508..3ff57c68258 100644--- a/src/metabase/server/middleware/log.clj+++ b/src/metabase/server/middleware/log.clj@@ -3,7 +3,10 @@(:require[clojure.core.async :as a][clojure.string :as str]+ [java-time.api :as t]+ [metabase.api-keys.usage :as api-keys.usage][metabase.api.common :as api]+ [metabase.api.macros :as api.macros][metabase.app-db.core :as mdb][metabase.driver.sql-jdbc.execute.diagnostic :as sql-jdbc.execute.diagnostic][metabase.request.core :as request]@@ -24,12 +27,13 @@(set! *warn-on-reflection* true)-;; To simplify passing large amounts of arguments around most functions in this namespace take an "info" map that+;; To simplify passing large amounts of arguments around, the logging functions below take an "info" map that;; looks like;;-;; {:request ..., :response ..., :start-time ..., :call-count-fn ...}+;; {:request ..., :response ..., :start-time ..., :call-count-fn ..., :diag-info-fn ..., :log-context ...};;-;; This map is created in `log-api-call` at the bottom of this namespace.+;; This map is built in `log-api-call` at the bottom of this namespace, once a response exists. API-key usage+;; recording is a separate concern with its own inputs — see [[record-api-key-usage!]] — and never touches it.;;; +----------------------------------------------------------------------------------------------------------------+;;; | Getting & Formatting Request/Response Info |@@ -192,6 +196,47 @@(log-info info)))response)+;;; +----------------------------------------------------------------------------------------------------------------++;;; | API Key Usage Analytics |+;;; +----------------------------------------------------------------------------------------------------------------+++(defn- api-key-request?+ "Whether `request` authenticated with an API key — the only kind of request that gets recorded. Resolved well+ outside this middleware by `metabase.server.middleware.session/wrap-current-user-info`, so it is already on the+ request we closed over. Everything else pays this one keyword lookup and nothing more.++ Checks `:api-key-id` rather than `:embedding/auth-method` — that key is stamped `agent-api`/`metabot`/`public`/+ `guest` etc. for those routes even when the request authenticated with an API key, so matching on `\"api-key\"`+ missed all of them. `:api-key-id` is only ever set by API-key auth, on every route."+ [request]+ (some? (:api-key-id request)))++(defn- record-api-key-usage!+ "Record API-key usage analytics for a completed request.++ Hands the recorder the raw `request`/`response` plus the handful of values only this middleware can supply:+ `route-template` (read off the carrier `metabase.server.middleware.route-template-carrier/wrap-route-template-carrier`+ installed on every request — nil for a request that matched no endpoint and for raw-Compojure handlers that bypass+ `defendpoint`, since neither ever fills it in; a dynamic binding wouldn't survive an async `respond` on another+ thread, which is why this is a carrier and not `api/*current-route*` or similar), `duration-ms` (time to `respond`,+ not to the last byte written — for streaming and core.async responses `respond` is called when the response object+ is created, so this is time-to-response, as it is for the CLI usage log), and `occurred-at` (captured here on the+ request thread rather than left for the DB to fill in at INSERT time — the row lands via a scheduled flush, up to+ the flush interval later, so a DB-computed default would record when the flush ran, not when the request happened).++ Best-effort throughout: the recorders swallow their own failures, and this catches anything else, so usage+ analytics can never fail a request or alter its response."+ [request response start-time]+ (when (api-key-request? request)+ (try+ (api-keys.usage/record-api-key-usage!+ request response+ {:route-template (some-> (get request api.macros/route-template-carrier-key) deref)+ :duration-ms (long (u/since-ms start-time))+ :occurred-at (t/offset-date-time)})+ (catch Throwable e+ (log/warn e "Error recording API key usage")))))+;;; +----------------------------------------------------------------------------------------------------------------+;;; | Middleware |;;; +----------------------------------------------------------------------------------------------------------------+@@ -215,23 +260,33 @@(not ((logging-disabled-uris) uri))))(defn log-api-call- "Logs info about request such as status code, number of DB calls, and time taken to complete."+ "Logs info about request such as status code, number of DB calls, and time taken to complete. Also the write point+ for API-key usage analytics — see [[record-api-key-usage!]]; requests that didn't authenticate with an API key are+ unaffected.++ Console logging and API-key usage recording are independent concerns with independent eligibility: a request+ suppressed from the console log (health checks, `/api/logger/logs`) still has its usage recorded if it+ authenticated with an API key, and vice versa. Neither gates the other."[handler](fn [request respond raise]- (if-not (should-log-request? request)- ;; non-API call or health or logs call, don't log it- (handler request respond raise)- ;; API call, log info about it- (t2/with-call-count [call-count-fn]- (sql-jdbc.execute.diagnostic/capturing-diagnostic-info [diag-info-fn]- (let [info {:request request- :start-time (u/start-timer)- :call-count-fn call-count-fn- :diag-info-fn diag-info-fn}- response->info (fn [response]- (assoc info- :response response- :log-context {:metabase-user-id (or (:metabase-user-id (meta response))- api/*current-user-id*)}))- respond (comp respond logged-response response->info)]- (handler request respond raise)))))))+ (let [should-log? (should-log-request? request)+ api-key? (api-key-request? request)]+ (if-not (or should-log? api-key?)+ ;; neither concern applies — skip the wrapping entirely+ (handler request respond raise)+ (t2/with-call-count [call-count-fn]+ (sql-jdbc.execute.diagnostic/capturing-diagnostic-info [diag-info-fn]+ (let [start-time (u/start-timer)+ respond* (fn [response]+ (when api-key?+ (record-api-key-usage! request response start-time))+ (when should-log?+ (logged-response {:request request+ :response response+ :start-time start-time+ :call-count-fn call-count-fn+ :diag-info-fn diag-info-fn+ :log-context {:metabase-user-id (or (:metabase-user-id (meta response))+ api/*current-user-id*)}}))+ (respond response))]+ (handler request respond* raise))))))))diff --git a/src/metabase/server/middleware/route_template_carrier.clj b/src/metabase/server/middleware/route_template_carrier.cljnew file mode 100644index 00000000000..0c771d38e68--- /dev/null+++ b/src/metabase/server/middleware/route_template_carrier.clj@@ -0,0 +1,15 @@+(ns metabase.server.middleware.route-template-carrier+ (:require+ [metabase.api.macros :as api.macros]))++(defn wrap-route-template-carrier+ "Installs a fresh `volatile!` on every request under `api.macros/route-template-carrier-key`, so+ routing can record which route template matched (see [[api.macros/route-template-carrier-key]])+ for any middleware to read at respond time, not just `metabase.server.middleware.log/log-api-call`+ — which used to install this carrier itself, conditionally, only for API-key requests. Installing it+ unconditionally here costs one `volatile!` and one `assoc` per request, and lets a middleware that+ runs outside `log-api-call` (e.g. `metabase.server.middleware.trace/wrap-trace`, wanting the matched+ route as a span attribute) read the same carrier without touching routing itself."+ [handler]+ (fn [request respond raise]+ (handler (assoc request api.macros/route-template-carrier-key (volatile! nil)) respond raise)))diff --git a/src/metabase/testing_api/api.clj b/src/metabase/testing_api/api.cljindex dd1dbf80932..8e06ebea365 100644--- a/src/metabase/testing_api/api.clj+++ b/src/metabase/testing_api/api.clj@@ -8,6 +8,7 @@[java-time.clock][medley.core :as m][metabase.analytics.core :as analytics]+ [metabase.api-keys.usage :as api-keys.usage][metabase.api.common :as api][metabase.api.macros :as api.macros][metabase.app-db.core :as mdb]@@ -631,3 +632,32 @@:error-code error_code:error-message error_message}){:session_id session-id :tool_name tool-name}))++(api.macros/defendpoint :post "/api-keys/seed-usage"+ :- [:map [:inserted :int]]+ "Record one completed API-key-authenticated request so the API-key usage E2E page has a visible+ row, then force an immediate flush of the usage-log and last_used_at batches (both normally+ flushed on a scheduled interval) so the row is queryable without waiting. Routes through the+ production `metabase.api-keys.usage/record-api-key-usage!` path (rather than a hand-rolled insert)+ so the seeded row can't drift from real writes. Intended only for E2E tests."+ [_route-params+ _query-params+ {:keys [api_key_id user_id created_by_id route_template status duration_ms]}+ :- [:map {:closed true}+ [:api_key_id ms/PositiveInt]+ [:user_id ms/PositiveInt]+ [:created_by_id ms/PositiveInt]+ [:route_template {:optional true} [:maybe ms/NonBlankString]]+ [:status {:optional true} [:maybe :int]]+ [:duration_ms {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]]]+ (api-keys.usage/record-api-key-usage!+ {:api-key-id api_key_id+ :metabase-user-id user_id+ :api-key-creator-id created_by_id+ :request-method :get+ :headers {"user-agent" "curl/8.0.1"}}+ {:status (or status 200)}+ {:route-template (or route_template "/api/testing/api-keys/seed-usage")+ :duration-ms (or duration_ms 42)})+ (api-keys.usage/flush-pending-writes!)+ {:inserted 1})diff --git a/test/metabase/api/macros_test.clj b/test/metabase/api/macros_test.cljindex bed11aba410..165ec5afdbc 100644--- a/test/metabase/api/macros_test.clj+++ b/test/metabase/api/macros_test.clj@@ -209,3 +209,17 @@::lib.schema.parameter/parameter{:type :string/contains, :value ["A"], :options {:case-sensitive false, :lib/uuid "not-yours"}}{:type :string/contains, :value ["A"], :options {:case-sensitive false}})))++(deftest ^:parallel route-template-test+ (testing "the route template is the accumulated prefix plus the endpoint's declared path"+ (are [prefix path expected] (= expected+ (#'api.macros/route-template prefix path))+ "/api/card" "/:id" "/api/card/:id"+ "/api/card" "/:id/query/:export-format" "/api/card/:id/query/:export-format"+ ;; a `"/"` endpoint is the prefix itself -- no meaningless trailing slash+ "/api/card" "/" "/api/card"+ ;; no prefix at all (an endpoint handler used on its own)+ nil "/:id" "/:id"+ "" "/:id" "/:id"+ nil "/" "/"+ "" "/" "/")))diff --git a/test/metabase/api/util/handlers_test.clj b/test/metabase/api/util/handlers_test.cljnew file mode 100644index 00000000000..670cbc53237--- /dev/null+++ b/test/metabase/api/util/handlers_test.clj@@ -0,0 +1,221 @@+(ns metabase.api.util.handlers-test+ "Tests for route-template reconstruction: as a request descends the routing tree, each level records the route+ pattern it consumed on the request's `:route-prefix`, and the endpoint that finally matches gets stamped with a+ `:route-template` — the full template, e.g. `\"/api/card/:id\"`.++ The endpoints below exist only to echo that `:route-template` back so tests can assert on it."+ (:require+ [clojure.test :refer :all]+ [metabase.api.common :as api]+ [metabase.api.macros :as api.macros]+ [metabase.api.util.handlers :as handlers]+ [metabase.initialization-status.core :as init-status]+ [metabase.server.routes :as server.routes]+ [metabase.test.util.dynamic-redefs :as dynamic-redefs]+ [metabase.util :as u]))++(set! *warn-on-reflection* true)++;;;; ------------------------------------------------- endpoints --------------------------------------------------++(defn- echo-route-template [request]+ {:status 200+ :body {:route-template (:route-template request)}})++(api.macros/defendpoint :get "/"+ "Root route."+ [_route-params _query-params _body request]+ (echo-route-template request))++(api.macros/defendpoint :get "/:id"+ "Single route param."+ [_route-params _query-params _body request]+ (echo-route-template request))++(api.macros/defendpoint :get ["/uuid/:uuid" :uuid u/uuid-regex]+ "Route param constrained by an explicit regex. The template must name the param, not the regex."+ [_route-params _query-params _body request]+ (echo-route-template request))++(api.macros/defendpoint :get ["/:id/query/:export-format" :id #"[0-9]+" :export-format #"csv|json"]+ "Several segments, two of them params."+ [_route-params _query-params _body request]+ (echo-route-template request))++(api.macros/defendpoint :get "/:id/boom"+ "An endpoint that throws rather than responding, the way most Metabase error responses are produced."+ [_route-params _query-params _body _request]+ (api/check-404 nil))++(def ^:private endpoints-handler+ (delay (api.macros/ns-handler 'metabase.api.util.handlers-test)))++;;;; ------------------------------------------------ test helpers ------------------------------------------------++(defn- noop-handler+ "A no-op async Ring handler that always responds nil — used to fill the `:auth`, `:oauth`, and `:well-known` slots+ in [[server.routes/make-routes]] when tests only care about the `/api` path."+ [_request respond _raise]+ (respond nil))++(defn- make-test-routes+ "Wrap an API handler in the map that [[server.routes/make-routes]] expects."+ [api-handler]+ (server.routes/make-routes {:api api-handler+ :auth noop-handler+ :oauth noop-handler+ :well-known noop-handler}))++(defn- handle+ "Invoke the async Ring `handler` and return its response synchronously."+ [handler request]+ (let [result (promise)]+ (handler request #(deliver result %) #(deliver result %))+ (let [response (deref result 10000 ::timeout)]+ (when (instance? Throwable response)+ (throw response))+ response)))++(defn- route-template+ "`GET` `uri` through `handler` and return the `:route-template` the routing machinery stamped on the request, or+ `::no-match` if nothing matched."+ ([handler uri]+ (route-template handler uri nil))+ ([handler uri extra-request-keys]+ (->> (merge {:request-method :get, :uri uri, :headers {}} extra-request-keys)+ (handle handler)+ :body+ :route-template)))++(defn- api-route-template+ "Like [[route-template]], but goes through the real top-level Metabase handler with `route-map` mounted where the+ `/api` routes normally live — i.e. behind the `(context \"/api\" [] ...)`+ in [[metabase.server.routes/make-routes]]. This is what proves the `/api` segment, which Compojure's `context`+ consumes before our own routing code ever sees it, still makes it into the template."+ ([route-map uri]+ (api-route-template route-map uri nil))+ ([route-map uri extra-request-keys]+ (dynamic-redefs/with-dynamic-fn-redefs [init-status/complete? (constantly true)]+ (route-template (make-test-routes (handlers/route-map-handler route-map))+ uri+ extra-request-keys))))++(defn- carried-route-template+ "`GET` `uri` through the real `/api` routing stack with a route-template carrier installed on the request the way+ `metabase.server.middleware.log` installs one, and return what routing recorded into it. Tolerates a request that+ ends in `raise` — that is the case this mechanism exists for."+ [route-map uri]+ (let [carrier (volatile! nil)+ result (promise)]+ (dynamic-redefs/with-dynamic-fn-redefs [init-status/complete? (constantly true)]+ ((make-test-routes (handlers/route-map-handler route-map))+ {:request-method :get+ :uri uri+ :headers {}+ api.macros/route-template-carrier-key carrier}+ #(deliver result %)+ #(deliver result %)))+ (deref result 10000 ::timeout)+ @carrier))++(def ^:private api-route-map+ (delay {"/handlers-test" @endpoints-handler}))++;;;; --------------------------------------------------- tests ----------------------------------------------------++(deftest ^:parallel route-template-includes-compojure-context-test+ (testing "the `/api` prefix consumed by Compojure's `context` is part of the template"+ (is (= "/api/handlers-test/:id"+ (api-route-template @api-route-map "/api/handlers-test/123")))))++(deftest ^:parallel route-template-root-route-test+ (testing "a `\"/\"` endpoint is the prefix itself, with no trailing slash"+ (are [uri] (= "/api/handlers-test"+ (api-route-template @api-route-map uri))+ "/api/handlers-test"+ "/api/handlers-test/")))++(deftest ^:parallel route-template-regex-constrained-param-test+ (testing "an explicitly regex-constrained param appears as its placeholder name, never as the regex"+ (is (= "/api/handlers-test/uuid/:uuid"+ (api-route-template @api-route-map "/api/handlers-test/uuid/f7e9a4b8-0000-4000-8000-abcdefabcdef")))))++(deftest ^:parallel route-template-unmatched-route-test+ (testing "nothing is stamped when no endpoint matches"+ ;; deliberately not routed through [[api-route-template]]: an unmatched `/api/...` request falls all the way+ ;; through to the SPA catch-all, which needs a running app.+ (is (nil? (handle (handlers/route-map-handler @api-route-map)+ {:request-method :get+ :uri "/handlers-test/uuid/not-a-uuid"+ :headers {}})))))++(deftest ^:parallel route-template-multiple-params-test+ (is (= "/api/handlers-test/:id/query/:export-format"+ (api-route-template @api-route-map "/api/handlers-test/123/query/csv"))))++(deftest ^:parallel route-template-nested-route-maps-test+ (testing "every route-map level contributes the prefix it consumed"+ (is (= "/api/handlers-test/nested/deeper/:id"+ (api-route-template {"/handlers-test" {"/nested" {"/deeper" @endpoints-handler}}}+ "/api/handlers-test/nested/deeper/123")))))++(deftest ^:parallel route-template-excludes-query-string-test+ (testing "the template is built from route structure only — nothing from the query string leaks in"+ (are [extra] (= "/api/handlers-test/:id"+ (api-route-template @api-route-map "/api/handlers-test/123" extra))+ {:query-string "secret=hunter2&card_id=456"}+ {:query-params {"secret" "hunter2", "card_id" "456"}}+ {:query-string "secret=hunter2", :query-params {"secret" "hunter2"}})))++(deftest ^:parallel route-template-outside-api-context-test+ (testing "route maps not mounted under a Compojure context (e.g. the `/auth` routes) accumulate from the root"+ (let [handler (handlers/route-map-handler {"/auth" {"/handlers-test" @endpoints-handler}})]+ (is (= "/auth/handlers-test/:id"+ (route-template handler "/auth/handlers-test/123")))+ (is (= "/auth/handlers-test"+ (route-template handler "/auth/handlers-test"))))))++(deftest ^:parallel route-template-without-any-prefix-test+ (testing "an endpoint handler used on its own still gets its ns-relative template"+ (is (= "/:id"+ (route-template @endpoints-handler "/123")))+ (is (= "/"+ (route-template @endpoints-handler "/")))))++(deftest ^:parallel route-template-carrier-test+ (testing "routing reports the matched template back to middleware above it through the carrier"+ ;; routing hands the matched endpoint a *new* request map, so middleware sitting above the routing tree — which+ ;; closed over the pre-routing request — can never see `:route-template` on it.+ (is (= "/api/handlers-test/:id"+ (carried-route-template @api-route-map "/api/handlers-test/123")))+ (is (= "/api/handlers-test"+ (carried-route-template @api-route-map "/api/handlers-test")))))++(deftest ^:parallel route-template-carrier-covers-endpoints-that-throw-test+ (testing "an endpoint that throws still reports its template — the carrier is written before the handler runs"+ ;; this is why the template is not simply attached to the response: an exception's response is built by+ ;; `metabase.server.middleware.exceptions/catch-api-exceptions`, not by the endpoint.+ (is (= "/api/handlers-test/:id/boom"+ (carried-route-template @api-route-map "/api/handlers-test/123/boom")))))++(deftest ^:parallel route-template-carrier-stays-empty-when-nothing-matches-test+ (testing "nothing is recorded when no endpoint matches"+ ;; as in [[route-template-unmatched-route-test]], deliberately not routed through the real `/api` routes: an+ ;; unmatched `/api/...` request falls through to the SPA catch-all, which needs a running app.+ (let [carrier (volatile! nil)]+ (handle (handlers/route-map-handler @api-route-map)+ {:request-method :get+ :uri "/handlers-test/uuid/not-a-uuid"+ :headers {}+ api.macros/route-template-carrier-key carrier})+ (is (nil? @carrier)))))++(deftest ^:parallel route-prefix-is-accumulated-not-overwritten-test+ (testing "each level appends to `:route-prefix` rather than replacing it"+ (let [prefixes (atom [])+ spy (fn [request respond _raise]+ (swap! prefixes conj (:route-prefix request))+ (respond {:status 200, :body {}}))+ handler (handlers/route-map-handler {"/a" {"/b" {"/c" spy}}})]+ (handle handler {:request-method :get, :uri "/a/b/c/d", :headers {}})+ (is (= ["/a/b/c"] @prefixes)))))diff --git a/test/metabase/api_keys/api_test.clj b/test/metabase/api_keys/api_test.cljindex bd3355731e8..b5d3ffdb972 100644--- a/test/metabase/api_keys/api_test.clj+++ b/test/metabase/api_keys/api_test.clj@@ -19,7 +19,7 @@resp (mt/user-http-request :crowberto :post 200 "api-key"{:group_id group-id:name name})]- (is (= #{:name :group :unmasked_key :masked_key :id :created_at :updated_at :updated_by}+ (is (= #{:name :group :unmasked_key :masked_key :id :created_at :updated_at :updated_by :last_used_at}(-> resp keys set)))(is (= (select-keys (mt/fetch-user :crowberto) [:id :common_name])(:updated_by resp)))@@ -31,7 +31,7 @@(testing "Trying to create another API key with the same name fails"(let [key-name (str (random-uuid))];; works once...- (is (= #{:unmasked_key :masked_key :group :name :id :created_at :updated_at :updated_by}+ (is (= #{:unmasked_key :masked_key :group :name :id :created_at :updated_at :updated_by :last_used_at}(set (keys (mt/user-http-request :crowberto :post 200 "api-key"{:group_id group-id:name key-name})))))@@ -204,7 +204,7 @@{:name name-2})(is (= name-2 (:common_name (t2/select-one :model/User api-user-id)))))(testing "the shape of the response is correct"- (is (= #{:created_at :updated_at :updated_by :id :group :name :masked_key}+ (is (= #{:created_at :updated_at :updated_by :id :group :name :masked_key :last_used_at}(set (keys (mt/user-http-request :crowberto :put 200 (str "api-key/" id){:name name-1}))))))))))diff --git a/test/metabase/api_keys/db_test.clj b/test/metabase/api_keys/db_test.cljnew file mode 100644index 00000000000..e5713827069--- /dev/null+++ b/test/metabase/api_keys/db_test.clj@@ -0,0 +1,53 @@+(ns metabase.api-keys.db-test+ (:require+ [clojure.test :refer [deftest is testing]]+ [java-time.api :as t]+ [metabase.api-keys.core :as-alias api-keys]+ [metabase.api-keys.db :as api-keys.db]+ [metabase.test :as mt]+ [toucan2.core :as t2]))++(defn- last-used-at [api-key-id]+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))++(defn- temp-key-opts []+ {::api-keys/unhashed-key (str "mb_" (mt/random-name))+ :name (mt/random-name)+ :user_id (mt/user->id :crowberto)+ :creator_id (mt/user->id :crowberto)+ :updated_by_id (mt/user->id :crowberto)})++(defn- now+ "Truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds."+ []+ (-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0))))++(deftest update-api-keys-last-used-at!-updates-available-keys-test+ (testing "nothing is skipped, and every key updates, when nothing else holds the rows"+ (mt/with-temp [:model/ApiKey {id-1 :id} (temp-key-opts)+ :model/ApiKey {id-2 :id} (temp-key-opts)]+ (let [ts (now)+ skipped (api-keys.db/update-api-keys-last-used-at! {id-1 ts, id-2 ts})]+ (is (= {} skipped))+ (is (= ts (last-used-at id-1)))+ (is (= ts (last-used-at id-2)))))))++(deftest update-api-keys-last-used-at!-skips-busy-keys-test+ (testing "a key the lock step excludes is skipped and returned to the caller; unrelated keys still update"+ (mt/with-temp [:model/ApiKey {available :id} (temp-key-opts)+ :model/ApiKey {busy :id} (temp-key-opts)]+ (let [ts (now)]+ (mt/with-dynamic-fn-redefs [api-keys.db/lock-available-key-ids (fn [ids] (remove #{busy} ids))]+ (let [skipped (api-keys.db/update-api-keys-last-used-at! {available ts, busy ts})]+ (is (= {busy ts} skipped))+ (is (= ts (last-used-at available)))+ (is (nil? (last-used-at busy)))))))))++(deftest update-api-keys-last-used-at!-drops-deleted-keys-test+ (testing "an id the lock step excludes because the key was deleted is dropped, not retried"+ (mt/with-temp [:model/ApiKey {available :id} (temp-key-opts)]+ (let [ts (now)+ deleted-id Integer/MAX_VALUE+ skipped (api-keys.db/update-api-keys-last-used-at! {available ts, deleted-id ts})]+ (is (= {} skipped) "the deleted id is dropped, not carried forward for another retry")+ (is (= ts (last-used-at available)))))))diff --git a/test/metabase/api_keys/usage_test.clj b/test/metabase/api_keys/usage_test.cljnew file mode 100644index 00000000000..b7f393b41cc--- /dev/null+++ b/test/metabase/api_keys/usage_test.clj@@ -0,0 +1,23 @@+(ns metabase.api-keys.usage-test+ (:require+ [clojure.test :refer :all]+ [metabase.api-keys.usage :as api-keys.usage]))++(deftest detect-client-test+ (testing "known clients are classified from their User-Agent"+ (are [user-agent expected] (= expected (api-keys.usage/detect-client user-agent))+ "metabase-cli/1.2.3" "metabase-cli"+ "curl/8.4.0" "curl"+ "PostmanRuntime/7.36.0" "postman"+ "python-requests/2.31.0" "python-requests"+ "libcurl/8.0.1 r-curl/5.1.0 httr/1.4.7" "r"+ "got (https://github.com/sindresorhus/got)" "node"))+ (testing "an unrecognized or absent User-Agent is \"other\""+ (are [user-agent] (= "other" (api-keys.usage/detect-client user-agent))+ "Mozilla/5.0 (some browser)"+ ""+ nil))+ (testing "matching is case-insensitive"+ (is (= "curl" (api-keys.usage/detect-client "CURL/8.4.0"))))+ (testing "r-curl is classified as r, not curl, despite containing \"curl\""+ (is (= "r" (api-keys.usage/detect-client "r-curl/5.1.0")))))diff --git a/test/metabase/cmd/copy_test.clj b/test/metabase/cmd/copy_test.cljindex 7c7f0cec9fb..9eb39099f0f 100644--- a/test/metabase/cmd/copy_test.clj+++ b/test/metabase/cmd/copy_test.clj@@ -82,6 +82,7 @@:model/AnalysisFinding:model/AnalysisFindingError:model/ApiKey+ :model/ApiKeyUsageLog:model/CacheConfig:model/CardFavorite:model/CloudMigrationdiff --git a/test/metabase/server/middleware/log_test.clj b/test/metabase/server/middleware/log_test.cljindex 314eab1ddd4..3cbcedfe506 100644--- a/test/metabase/server/middleware/log_test.clj+++ b/test/metabase/server/middleware/log_test.clj@@ -1,7 +1,10 @@(ns metabase.server.middleware.log-test(:require[clojure.test :refer :all]+ [metabase.api-keys.usage :as api-keys.usage]+ [metabase.api.macros :as api.macros][metabase.server.middleware.log :as mw.log]+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier][metabase.test :as mt][metabase.test.fixtures :as fixtures]))@@ -33,6 +36,114 @@(is (not (#'mw.log/should-log-request? {:uri "/livez"})))(is (not (#'mw.log/should-log-request? {:uri "/readyz"}))))))+;;; ------------------------------------------- API key usage analytics -------------------------------------------++(def ^:private api-key-request+ {:request-method :get+ :uri "/api/card/1"+ :headers {"user-agent" "metabase-cli/1.2.3", "x-metabase-client" "embedding-sdk-react"+ "x-metabase-embed-referrer" "https://example.com/app"}+ :remote-addr "203.0.113.7"+ :embedding/auth-method "api-key"+ :api-key-id 7+ :metabase-user-id 3})++(defn- run-log-api-call!+ "Send `request` through [[mw.route-template-carrier/wrap-route-template-carrier]] wrapping+ [[mw.log/log-api-call]] — mirroring their order in the real middleware stack — with a downstream+ handler that stands in for routing — recording `route-template` into the carrier the outer+ middleware installed, the way `metabase.api.macros` does — and then responds with `response`.+ Returns what the API-key usage recorder was called with (`::not-called` if it wasn't) plus the+ final response.++ The recorder now takes the raw `request`/`response` plus a small `extra-info` map — see+ `metabase-enterprise.api-keys.usage/record-api-key-usage!`. Header/field extraction from `request` is the+ recorder's job, not this middleware's, so it's exercised in `metabase-enterprise.api-keys.usage-test`, not here."+ [request route-template response]+ (let [recorded (atom ::not-called)+ final-response (atom ::no-response)+ handler (fn [request respond _raise]+ (some-> (get request api.macros/route-template-carrier-key)+ (vreset! route-template))+ (respond response))]+ (mt/with-dynamic-fn-redefs [api-keys.usage/record-api-key-usage!+ (fn [request response extra-info]+ (reset! recorded {:request request, :response response, :extra-info extra-info}))]+ ((mw.route-template-carrier/wrap-route-template-carrier (mw.log/log-api-call handler))+ request+ #(reset! final-response %)+ identity))+ {:recorded @recorded, :response @final-response}))++(deftest log-api-call-records-api-key-usage-test+ (testing "an API-key-authenticated request records one usage event"+ (let [{:keys [recorded]}+ (run-log-api-call! api-key-request "/api/card/:id" {:status 200, :body "ok"})]+ (testing "the raw request and response are forwarded unchanged"+ (is (=? api-key-request (:request recorded)))+ (is (= {:status 200, :body "ok"} (:response recorded))))+ (testing "extra-info carries only what the middleware alone can supply"+ (is (= "/api/card/:id" (:route-template (:extra-info recorded))))+ (is (int? (:duration-ms (:extra-info recorded))))+ (is (instance? java.time.OffsetDateTime (:occurred-at (:extra-info recorded))))+ (is (= #{:route-template :duration-ms :occurred-at}+ (set (keys (:extra-info recorded)))))))))++(deftest log-api-call-records-api-key-usage-even-when-console-logging-is-suppressed-test+ (testing "usage recording and console-log suppression are independent eligibility checks"+ (let [{:keys [recorded response]}+ (run-log-api-call! (assoc api-key-request :uri "/api/logger/logs")+ "/api/logger/logs" {:status 200, :body "ok"})]+ (testing "/api/logger/logs is always excluded from the console log, but usage still recorded"+ (is (not= ::not-called recorded))+ (is (= "/api/logger/logs" (:route-template (:extra-info recorded)))))+ (testing "the response passes through unaffected"+ (is (= {:status 200, :body "ok"} response))))))++(deftest log-api-call-records-nothing-for-other-auth-methods-test+ (testing "session-authenticated requests are untouched"+ (let [{:keys [recorded]}+ (run-log-api-call! (-> api-key-request+ (assoc :embedding/auth-method "session")+ (dissoc :api-key-id))+ "/api/card/:id" {:status 200, :body "ok"})]+ (is (= ::not-called recorded))))+ (testing "so are unauthenticated ones"+ (let [{:keys [recorded]}+ (run-log-api-call! (dissoc api-key-request :embedding/auth-method :api-key-id)+ nil {:status 401, :body "Unauthenticated"})]+ (is (= ::not-called recorded)))))++(deftest log-api-call-records-api-key-usage-on-embedding-and-agent-routes-test+ (testing "an API-key-authenticated request still records usage when the route stamps a different+ embedding/auth-method (agent-api, metabot, public, guest — #EMB-2154 feedback)"+ (doseq [embedding-auth-method ["agent-api" "metabot" "public" "guest"]]+ (let [{:keys [recorded]}+ (run-log-api-call! (assoc api-key-request :embedding/auth-method embedding-auth-method)+ "/api/card/:id" {:status 200, :body "ok"})]+ (is (not= ::not-called recorded) (str "auth-method " embedding-auth-method))))))++(deftest log-api-call-records-api-key-usage-without-a-route-template-test+ (testing "a request that matched no endpoint still records the event, with a nil route-template. Whether the+ usage-log row gets dropped downstream because route_template is NOT NULL, and whether last_used_at+ still gets stamped regardless, are decisions the recorder makes — see+ metabase-enterprise.api-keys.usage-test."+ (let [{:keys [recorded]}+ (run-log-api-call! api-key-request nil {:status 404, :body "Not found."})]+ (is (= 7 (:api-key-id (:request recorded))))+ (is (nil? (:route-template (:extra-info recorded))))+ (is (= 404 (:status (:response recorded)))))))++(deftest log-api-call-api-key-usage-is-best-effort-test+ (testing "a recorder that throws never breaks the response"+ (mt/with-dynamic-fn-redefs [api-keys.usage/record-api-key-usage! (fn [& _] (throw (ex-info "boom" {})))]+ (let [response (atom ::no-response)]+ ((mw.log/log-api-call (fn [_request respond _raise] (respond {:status 200, :body "ok"})))+ api-key-request+ #(reset! response %)+ identity)+ (is (= {:status 200, :body "ok"} @response))))))+(deftest log-api-call-captures-user-id-from-response-metadata-test(testing "log-api-call reads :metabase-user-id from response metadata (#74017)"(let [logged-user-id (promise)diff --git a/test/metabase/server/middleware/route_template_carrier_test.clj b/test/metabase/server/middleware/route_template_carrier_test.cljnew file mode 100644index 00000000000..09b6880904a--- /dev/null+++ b/test/metabase/server/middleware/route_template_carrier_test.clj@@ -0,0 +1,28 @@+(ns metabase.server.middleware.route-template-carrier-test+ (:require+ [clojure.test :refer :all]+ [metabase.api.macros :as api.macros]+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier]))++(deftest wrap-route-template-carrier-installs-a-fresh-volatile-test+ (testing "every request gets its own carrier, regardless of auth method"+ (doseq [request [{} {:embedding/auth-method "api-key"} {:embedding/auth-method "session"}]]+ (let [seen (atom ::not-called)]+ ((mw.route-template-carrier/wrap-route-template-carrier+ (fn [request respond _raise]+ (reset! seen (get request api.macros/route-template-carrier-key))+ (respond {:status 200})))+ request identity identity)+ (is (instance? clojure.lang.Volatile @seen))+ (is (nil? (deref @seen)))))))++(deftest wrap-route-template-carrier-readable-downstream-test+ (testing "a value routing records into the carrier is visible after the inner handler returns"+ (let [carrier (atom nil)]+ ((mw.route-template-carrier/wrap-route-template-carrier+ (fn [request respond _raise]+ (vreset! (get request api.macros/route-template-carrier-key) "/api/card/:id")+ (reset! carrier (get request api.macros/route-template-carrier-key))+ (respond {:status 200})))+ {} identity identity)+ (is (= "/api/card/:id" (deref @carrier))))))diff --git a/test/metabase/server/middleware/session_test.clj b/test/metabase/server/middleware/session_test.cljindex 91d8792e29e..0cfaa78c75a 100644--- a/test/metabase/server/middleware/session_test.clj+++ b/test/metabase/server/middleware/session_test.clj@@ -250,16 +250,21 @@(is (nil? (:metabase-user-id request'))))))(deftest current-user-info-for-api-key-test- (mt/with-temp [:model/ApiKey _ {:name "An API Key"- :user_id (mt/user->id :lucky)- :creator_id (mt/user->id :lucky)- :updated_by_id (mt/user->id :lucky)- ::api-key/unhashed-key (u.secret/secret "mb_foobar123")}]+ (mt/with-temp [:model/ApiKey {api-key-id :id} {:name "An API Key"+ :user_id (mt/user->id :lucky)+ :creator_id (mt/user->id :lucky)+ :updated_by_id (mt/user->id :lucky)+ ::api-key/unhashed-key (u.secret/secret "mb_foobar123")}](testing "A valid API key works, and user info is added to the request"+ ;; `:api-key-id` and `:api-key-creator-id` are resolved for API-key auth only — the usage+ ;; analytics hook in `metabase.server.middleware.log` reads both off the request rather than+ ;; looking them up again.(let [req {:headers {"x-api-key" "mb_foobar123"}}](testing "No premium features, do not include :is-group-manager?"(mt/with-premium-features #{}- (is (= (merge req {:metabase-user-id (mt/user->id :lucky)+ (is (= (merge req {:api-key-id api-key-id+ :api-key-creator-id (mt/user->id :lucky)+ :metabase-user-id (mt/user->id :lucky):is-superuser? false:is-data-analyst? false:user-locale nil@@ -268,7 +273,9 @@(testing "Include :is-group-manager? if we have EE + :advanced-permissions "(when config/ee-available?(mt/with-premium-features #{:advanced-permissions}- (is (= (merge req {:metabase-user-id (mt/user->id :lucky)+ (is (= (merge req {:api-key-id api-key-id+ :api-key-creator-id (mt/user->id :lucky)+ :metabase-user-id (mt/user->id :lucky):is-superuser? false:is-data-analyst? false:is-group-manager? false