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 what 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.

  {
    "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":"ephemeral-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.

Create a Data Science & Engineering cluster with the Single user cluster security mode. See Create a cluster that can access Unity Catalog.
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
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 you wish 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) you wish 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 logging. 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.
Run the notebook to create the audit report.
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

The following table includes the auditable events in Unity Catalog. The actionName property identifies an audit event in an audit log record. The action’s request parameters are listed under requestParams.

actionName	requestParams
createMetastore	[“name”, “storage_root”]
getMetastore	[“id”]
getMetastoreSummary
listMetastores
updateMetastores	[“id”, “name”, “storage_root”, “default_data_access_config_id”, “delta_sharing_enabled”, “owner”]
deleteMetastore	[“id”, “force”]
createMetastore	[“workspace_id”, “metastore_id”, “default_catalog_name”]
updateMetastoreAssignment	[“workspace_id”, “metastore_id”, “default_catalog_name”]
createExternalLocation
getExternalLocation
listExternalLocations
updateExternalLocation
deleteExternalLocation
createCatalog	[“name”]
deleteCatalog	[“name_arg”]
getCatalog	[“name_arg”]
updateCatalog	[“name_arg”, “name”, “owner”, “comment”]
listCatalog
createSchema	[“name”, “catalog_name”]
deleteSchema	[“full_name_arg”]
getSchema	[“full_name_arg”]
listSchema	[“catalog_name”]
updateSchema	[“full_name_arg”, “name”, “owner”, “comment”]
createStagingTable	[“name”, “catalog_name”, “schema_name”]
createTable	[“name”, “catalog_name”, “schema_name”, “table_type”, “data_source_format”, “column_infos”, “storage_location”, “sql_path”, “view_definition”, “comment”]
deleteTable	[“full_name_arg”]
getTable	[“full_name_arg”]
privilegedGetTable	[“full_name_arg”]
listTables	[“catalog_name”, “schema_name”]
listTablesSummaries
updateTables	[“name”, “table_type”, “data_source_format”, “column_infos”, “storage_location”, “sql_path”, “view_definition”, “owner”, “comment”]
createStorageCredentials
listStorageCredentials
getStorageCredentials
updateStorageCredentials
deleteStorageCredentials
createCredentials	[“data_access_configuration_id”, “table_id”, “operation”]
generateTemporaryTableCredential
generateTemporaryPathCredential
getPermissions	[“securable_type”, “securable_full_name”, “principal”]
updatePermissions	[“securable_type”, “securable_full_name”, “changes”]
createRecipient	[“name”, “comment”]
deleteRecipient	[“name”]
getRecipient	[“name”]
listRecipient
createShare	[“name”, “comment”]
deleteShare	[“name”]
getShare	[“name”]
updateShare	[“name”, “updates”]
listShares
getSharesPermissions	[“name”]
updateSharePermissions	[“name”, “changes”]
getRecipientSharePermissions	[“name”]
createProvider
updateProvider
deleteProvider
getProvider
listProvider
listProviderShares
rotateRecipientToken
privilagedGetAllPermissions	[“securables”]
getActivationUrInfo	[“recipient_name”]
retrieveRecipientToken	[“recipient_name”]
metadataSnapshot
metadataAndPermissionsSnapshot
getInformationSchema