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 keys usage page docs (#84610)
Robert Kosara985fd71872ad
diff --git a/docs/monitor/api-key-usage.md b/docs/monitor/api-key-usage.mdnew file mode 100644index 00000000000..edd32b984fb--- /dev/null+++ b/docs/monitor/api-key-usage.md@@ -0,0 +1,86 @@+---+title: API key usage+summary: See which API keys are still in use, which routes they call, and which tools call them.+---++# API key usage++{% include plans-blockquote.html feature="API key usage" %}++_Monitor > API key usage_++The API key usage page lets admins see how [API keys](../people-and-groups/api-keys.md) are used. Metabase records one row for every API request authenticated with an API key. Tabs on the page include:++- [**Usage**](#usage): Charts and a table that summarize API key activity over the date range you pick.+- [**Events**](#events): One row per request, to see individual API calls.++## Usage++The Usage tab shows a dashboard summarizing the calls that match your filters. Click on any column heading to sort the table, click again to reverse the sort order.++- **Key activity**: Every API key that matches your filters, its group and when it was last used. Keys with the most recent activity show up first by default.+- **Calls over time**: A line chart of daily call volume.+- **Calls by client**: A pie chart broken down by which tools make the calls, like curl or the Metabase CLI. See [How Metabase identifies clients](#how-metabase-identifies-clients).+- **Calls by route**: A bar chart of which API endpoints get called most, like `/api/card/:id`. Less common routes are grouped together under **Other**.++## Events++The Events tab lists each API call:++- **ID**: An identifier for the record, unique to each call.+- **Occurred at**: When the call came in.+- **Route**: The API endpoint the call hit, like `/api/card/:id`. See [What the Route column records](#what-the-route-column-records).+- **Method**: The HTTP method, like `GET` or `POST`.+- **Status**: The HTTP status code of the response.+- **Duration (ms)**: How long the call took, in milliseconds.+- **API key**: The name of the key that authenticated the call.+- **Created by**: The person who created the API key. That's not necessarily whoever is making the calls: anyone with a copy of the key can use it.+- **Client**: The tool that made the call. See [How Metabase identifies clients](#how-metabase-identifies-clients).+- **Embedding client**: The value of the `X-Metabase-Client` header, if the caller sent one. Most API key traffic doesn't send this header, so this column is usually empty.+- **Embedding hostname**: The hostname of the page that embedded Metabase, if the caller sent one. Like **Embedding client**, this column is usually empty.+- **IP address**: Where the call came from. Only shows up if you [turn on PII retention](#turn-on-pii-retention-to-see-ip-addresses).++### What the Route column records++Metabase records the route template, not the full URL. A call to `/api/card/123` shows up as `/api/card/:id`, so calls to the same endpoint get counted together, no matter which item they asked for. Metabase never records query strings or IDs.++You might also see two special values:++- `(unmatched)`: The call went to an API path that doesn't exist, and Metabase returned a 404. Causes for this include typos, testing, and people probing for endpoints.+- `(no-template)`: The call reached Metabase, but not a regular API endpoint. This includes health checks and requests Metabase declined before they got to an endpoint.++## How Metabase identifies clients++Metabase reads the `User-Agent` header the caller sends, and sorts each call into one of these clients:++- **Metabase CLI**: The [Metabase CLI](../installation-and-operation/metabase-cli.md).+- **curl**: The `curl` command-line tool.+- **Postman**: The Postman API client.+- **Python**: Python scripts that use the `requests` library. Other Python HTTP libraries show up as **Other**.+- **R**: R scripts that use the `curl` package, or `httr`, which is built on it.+- **Node.js**: Node.js scripts that use the `got` library. Other Node.js HTTP libraries show up as **Other**.+- **Other**: Everything else, including callers that don't send a user agent.++Clients report their own user agent, so the Client column can only serve as a usage signal, not a security check. Metabase never uses the client to decide what a caller is allowed to do. An API key's permissions come from the [group](../people-and-groups/api-keys.md) assigned to the key.++## Logging is delayed and skipped under heavy load++Metabase saves API key usage in batches, so calls can take a few seconds to appear on the page.++API key usage is for spotting patterns, not for auditing every request. When an instance gets a lot of API key traffic in a short time, Metabase may skip recording some calls instead of slowing down the requests themselves. If that happens, Metabase writes a warning to its [logs](./application-logs.md).++## Turn on PII retention to see IP addresses++The IP address column stays hidden unless you turn on [`MB_ANALYTICS_PII_RETENTION_ENABLED`](../configuring-metabase/environment-variables.md#mb_analytics_pii_retention_enabled), which controls whether Metabase stores personally identifiable information alongside its analytics. PII retention is off by default.++## How long Metabase keeps API key usage data++Once a day, Metabase deletes call records older than [`MB_AI_USAGE_MAX_RETENTION_DAYS`](../configuring-metabase/environment-variables.md#mb_ai_usage_max_retention_days). The same setting controls retention for [AI usage auditing](../ai/usage-auditing.md) and [CLI analytics](./cli-analytics.md) data, so changing it affects all of them.++Deleting an API key doesn't delete its usage history. Calls from a deleted key still count in the charts and show up on the Events tab, but with a blank API key column, since Metabase only knows the name while the key exists.++## Further reading++- [API keys](../people-and-groups/api-keys.md)+- [CLI analytics](./cli-analytics.md)+- [Monitor overview](./start.md)diff --git a/docs/monitor/start.md b/docs/monitor/start.mdindex 157728f221e..74eef06aa3b 100644--- a/docs/monitor/start.md+++ b/docs/monitor/start.md@@ -35,6 +35,9 @@ Monitor contains three sections:- **[Application logs](./application-logs.md)**: View Metabase's logs, and configure how much information Metabase logs.- **[Model persistence log](./model-persistence-log.md)**: View the status of persisted models and refresh their cached results.- **[Session management](./session-management.md)**\*: View and revoke specific sessions or all sessions.+- **[API key usage](./api-key-usage.md)**\*: See which [API keys](../people-and-groups/api-keys.md) are still in use, which routes they call, and which tools call them.++\* Available on [Pro and Enterprise plans](https://www.metabase.com/pricing). On other plans, these tabs show an upgrade page.### AI auditing@@ -51,6 +54,6 @@ Who can see each Monitor page depends on their group:- **Admin group** can view every page.- **[Data Analysts](../people-and-groups/managing.md#data-analysts) group** can view Dependency diagnostics.\*-- **Groups with [Monitoring access](../permissions/application.md#monitoring-access)** can view every page except Dependency diagnostics and Alerts management.\*+- **Groups with [Monitoring access](../permissions/application.md#monitoring-access)** can view every page except Dependency diagnostics, Alerts management, and API key usage.\*\* On OSS, only admins can view Monitor. The Data Analysts group and the Monitoring access permission are only available on [Pro and Enterprise plans](https://www.metabase.com/pricing).diff --git a/docs/people-and-groups/api-keys.md b/docs/people-and-groups/api-keys.mdindex e3a3907621c..1a1b334c662 100644--- a/docs/people-and-groups/api-keys.md+++ b/docs/people-and-groups/api-keys.md@@ -41,6 +41,10 @@ To view and manage existing API keys:4. Click on the **Authentication** tab on the left menu.5. Scroll to **API Keys** and click **Manage**.+### See how your API keys get used++See [API key usage](../monitor/api-key-usage.md) in Monitor.+### Editing API keysTo edit an API key, scroll to the key you want to edit and click on the **pencil** icon. Metabase will pop up an **Edit API Key** modal where you can edit:@@ -116,4 +120,5 @@ getGroups().then((groups) => console.log("Groups in your Metabase:", groups));## Further reading- [Metabase API reference](../api.html).+- [API key usage](../monitor/api-key-usage.md).- [Working with the Metabase API](https://www.metabase.com/learn/metabase-basics/administration/administration-and-operation/metabase-api).diff --git a/docs/permissions/application.md b/docs/permissions/application.mdindex 14af32d804c..9fad92dada1 100644--- a/docs/permissions/application.md+++ b/docs/permissions/application.md@@ -46,6 +46,7 @@ The following Monitor pages aren't included in Monitoring access:- [Dependency diagnostics](../monitor/dependency-diagnostics.md): Available to admins and people in the [Data Analysts](../people-and-groups/managing.md#data-analysts) group- [Alerts management](../monitor/alerts-management.md): Available to admins only+- [API key usage](../monitor/api-key-usage.md): Available to admins only## Subscriptions and alertsdiff --git a/docs/util/data/nav.yml b/docs/util/data/nav.ymlindex 540cd83e3f9..5ed093dc3e9 100644--- a/docs/util/data/nav.yml+++ b/docs/util/data/nav.yml@@ -473,7 +473,7 @@ categories:- name: "Development instances"url: "installation-and-operation/development-instance"- name: "Monitoring your Metabase"- url: "troubleshooting-guide/profiling-metabase"+ url: "monitor/start"- name: "Observability with Prometheus"url: "installation-and-operation/observability-with-prometheus"- name: "Serialization"@@ -486,6 +486,8 @@ categories:url: "installation-and-operation/metabase-cli"- name: "Usage analytics"url: "usage-and-performance-tools/usage-analytics"+ - name: "API key usage"+ url: "monitor/api-key-usage"- name: "Admin tools"url: "monitor/erroring-questions"- name: "Panopticon"