Audit Unity Catalog events

This article contains audit log information for Unity Catalog events. Unity Catalog captures an audit log of actions performed against the metastore. This enables admins to access fine-grained details about who accessed a given dataset and the actions they performed.

Configure audit logs

To access audit logs for Unity Catalog events, you must enable and configure audit logs for your account.

important

Unity Catalog activity is logged at the level of the account. Do not enter a value into workspace_ids_filter.

Audit logs for each workspace and account-level activities are delivered to your account. Logs are delivered to the S3 bucket that you configure.

Audit log format

In Databricks, audit logs output events in a JSON format. The following example is for a createMetastoreAssignment event.

JSON

{
  "version": "2.0",
  "auditLevel": "ACCOUNT_LEVEL",
  "timestamp": 1629775584891,
  "orgId": "3049056262456431186970",
  "shardName": "test-shard",
  "accountId": "77636e6d-ac57-484f-9302-f7922285b9a5",
  "sourceIPAddress": "10.2.91.100",
  "userAgent": "curl/7.64.1",
  "sessionId": "f836a03a-d360-4792-b081-baba525324312",
  "userIdentity": {
    "email": "crampton.rods@email.com",
    "subjectName": null
  },
  "serviceName": "unityCatalog",
  "actionName": "createMetastoreAssignment",
  "requestId": "ServiceMain-da7fa5878f40002",
  "requestParams": {
    "workspace_id": "30490590956351435170",
    "metastore_id": "abc123456-8398-4c25-91bb-b000b08739c7",
    "default_catalog_name": "main"
  },
  "response": {
    "statusCode": 200,
    "errorMessage": null,
    "result": null
  },
  "MAX_LOG_MESSAGE_LENGTH": 16384
}

Audit log analysis example

The following steps and notebook create a dashboard you can use to analyze your account's audit log data.

1. Create a cluster with the Dedicated access mode. See Access modes.

2. Import the following example notebook into your workspace and attach it to the cluster you just created. See Import a notebook.

   Audit log analysis notebook

   Open notebook in new tab

3. A series of widgets appear at the top of the page. Enter a value for checkpoint and optionally enter values for the remaining fields.

   • checkpoint: The path where streaming checkpoints are stored, either in DBFS or S3.

   • catalog: Name of the catalog where you want to store the audit tables (catalog must already exist). Make sure that you have USE CATALOG and CREATE privileges on it.

   • database: Name of the database (schema) where you want to store the audit tables (will be created if doesn't already exist). If it does already exist, make sure that you have USE SCHEMA and CREATE privileges on it.

   • log_bucket: The path to the storage location where your audit logs reside. This should be in the following format:

     <bucket-name>/<delivery-path-prefix>/workspaceId=0/

     For information about configuring audit logs, see Configure audit log delivery. Append workspaceId=0 to the path to get the account-level audit logs, including Unity Catalog events.

   • start_date: Filter events by start date.

     Values for <bucket-name> and <delivery-path> are automatically filled from the notebook widgets.

4. Run the notebook to create the audit report.

5. To modify the report or to return activities for a given user, see commands 23 and 24 in the notebook.

Unity Catalog audit log events

For a list of auditable events in Unity Catalog, see Unity Catalog events.