Skip to content

Databricks: model usage traces

Optional. Set this up only if you want foundation model and custom serving endpoint usage in Trust3 usage summaries.

When it applies

Both of these must be true:

  • Trace collection is on for the collector.
  • The collector's Enable model usage collection toggle is on — it is on by default.

Turn the toggle off and you can skip this page entirely.

The collector then reads these system tables through a SQL warehouse:

System table What Trust3 collects
system.ai_gateway.usage Pay-per-token foundation model calls (ai_query on databricks-* endpoints)
system.serving.endpoint_usage Custom serving endpoint invocations (non-databricks-* endpoints)
system.serving.served_entities Join metadata for endpoint names (read with endpoint_usage)

Step 1 — Pick a SQL warehouse and copy its HTTP path

  1. In the workspace, click SQL Warehouses.
  2. Click the warehouse for the collector to use, or create a small Serverless one. Auto-stop is fine — Databricks starts it when a query arrives.
  3. Open Connection details.
  4. Copy the full HTTP path, for example /sql/1.0/warehouses/eead5eea05a19b3e, and paste it into the collector's SQL warehouse HTTP path field.
  5. On the same warehouse, open Permissions and give the collector identity Can Use.

If the HTTP path is missing or unreadable, the collector logs a warning and skips these queries.

Step 2 — Grant access to the system catalog

Workspace entitlements are not Unity Catalog privileges. Even with Admin access, the identity needs these grants or the model usage and serving endpoint usage collectors return no rows.

  • Run them as a metastore admin or account admin.
  • Replace the principal with the identity the collector authenticates as.
SQL
1
2
3
4
5
6
7
8
9
-- Catalog / schema access
GRANT USE CATALOG ON CATALOG system TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.ai_gateway TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.serving TO `<collector-principal>`;

-- Table SELECT (model usage collectors)
GRANT SELECT ON TABLE system.ai_gateway.usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.endpoint_usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.served_entities TO `<collector-principal>`;

You also need a SQL warehouse for these queries:

  • Grant Can Use on it: SQL Warehouses → your warehouse → Permissions.
  • Copy its HTTP path from Connection details and enter it in the collector's SQL warehouse HTTP path field.

The principal is the collector identity — see Who to grant to.

Read more