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

  1. Create a Data Science & Engineering cluster with the Single user cluster security mode. See Create a cluster that can access Unity Catalog.

  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 you wish to store the audit tables (catalog must already exist). Make sure that you have USAGE 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 USAGE and CREATE privileges on it.

    • log_bucket: The S3 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.

  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

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