Audit and monitor data sharing using Delta Sharing (for providers)

This article describes how data providers can use Databricks audit logs to monitor Delta Sharing events, including:

When someone creates, modifies, updates, or deletes a share or a recipient
When a recipient accesses an activation link and downloads the credential
When a recipient accesses shares.
When a recipient accesses data in shared tables.
When a recipient’s credential is rotated or expires.

For information about how data recipients can audit Delta Sharing events to understand who is accessing which data, see Audit and monitor data access using Delta Sharing (for recipients).

Requirements

An account admin must set up audit logging for your Databricks account. See Enable audit logging and Configure audit logging.

View Delta Sharing provider-related events in the audit log

To view audit logs for your account, you need to know the bucket and path where the logs are delivered. For information about delivery options, see Audit delivery details and format.

Events for Delta Sharing are logged with serviceName set to unityCatalog. The requestParams section of each event includes a delta_sharing prefix.

For example, the following audit event shows an update to the recipient token lifetime. In this example, redacted values are replaced with <redacted>.

{
    "version":"2.0",
    "auditLevel":"ACCOUNT_LEVEL",
    "timestamp":1629775584891,
    "orgId":"3049059095686970",
    "shardName":"example-workspace",
    "accountId":"<redacted>",
    "sourceIPAddress":"<redacted>",
    "userAgent":"curl/7.64.1",
    "sessionId":"<redacted>",
    "userIdentity":{
        "email":"<redacted>",
        "subjectName":null
    },
    "serviceName":"unityCatalog",
    "actionName":"updateMetastore",
    "requestId":"<redacted>",
    "requestParams":{
        "id":"<redacted>",
        "delta_sharing_scope":"INTERNAL_AND_EXTERNAL"
        "delta_sharing_recipient_token_lifetime_in_seconds": 31536000
    },
    "response":{
        "statusCode":200,
        "errorMessage":null,
        "result":null
    },
    "MAX_LOG_MESSAGE_LENGTH":16384
}

The following table lists audited Delta Sharing events that are delivered to data provider logs.

In addition to the events and parameters included in the table, the following are also logged:

The following parameters are always present in the audit log for each event:
- userIdentity.email: The ID of the user who initiated the activity.
- requestParams.id: the Unity Catalog metastore that manages the shared data.
Catalog, schema, and table access are audited the same way as for Unity Catalog. See Audit Unity Catalog events.

actionName	requestParams
`deltaSharingListShares`	`options`: The pagination options provided with this request. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingGetShare`	`share`: The name of the share. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingListSchemas`	`share`: The name of the share. `options`: The pagination options provided with this request. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingListAllTables`	`share`: The name of the share. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingListTables`	`share`: The name of the share. `options`: The pagination options provided with this request. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingGetTableMetadata`	`share`: The name of the share. `schema`: The name of the schema. `name`: The name of the table. `predicateHints`: The predicates included in the query. `limitHints`: The maximum number of rows to return. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingGetTableVersion`	`share`: The name of the share. `schema`: The name of the schema. `name`: The name of the table. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingQueryTable`	`share`: The name of the share. `schema`: The name of the schema. `name`: The name of the table. `predicateHints`: The predicates included in the query. `limitHint`: The maximum number of rows to return. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingQueryTableChanges`	`share`: The name of the share. `schema`: The name of the schema. `name`: The name of the table. `cdf_options`: Change data feed options. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingQueriedTable`	`recipient_name`: The name of the recipient that queried the table. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`deltaSharingQueriedTableChanges`	`recipient_name`: The name of the recipient that queried the table. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`updateMetastore`	`delta_sharing_scope`: values can be “INTERNAL” or “INTERNAL_AND_EXTERNAL” `delta_sharing_recipient_token_lifetime_in_seconds`: If present, indicates that the recipient token lifetime was updated.
`createRecipient`	`name`: The name of the recipient. `comment`: The comment for the recipient. `ip_access_list.allowed_ip_addresses`: Recipient IP address allowlist.
`deleteRecipient`	`name`: The name of the recipient.
`getRecipient`	`name`: The name of the recipient.
`listRecipients`	none
`rotateRecipientToken`	`name`: The name of the recipient. `comment`: The comment given in the rotation command.
`updateRecipient`	`name`: The name of the recipient. `updates`: A JSON representation of recipient attributes that were added or removed from the share. Each item includes `action` (add or remove) and can include `name` (the new recipient name), `owner` (new owner), `comment`, and `ip_access_list.allowed_ip_addresses` (recipient IP address allowlist).
`createShare`	`name`: The name of the share. `comment`: The comment for the share.
`deleteShare`	`name`: The name of the share.
`getShare`	`name`: The name of the share. `include_shared_objects`: Whether the share’s table names were included in the request.
`updateShare`	`name`: The name of the share. `updates`: A JSON representation of tables that were added or removed from the share. Each item includes `action` (add or remove), `name` (the actual name of the table), `shared_as` (the name the schema and table were shared as, if different from `name`), and `partition_specification` (if a partition specification was provided).
`listShares`	none
`getSharePermissions`	`name`: The name of the share.
`updateSharePermissions`	`name`: The name of the share. `changes`: A JSON representation of the updated permissions. Each change includes `principal` (the user or group to whom permission is granted or revoked), `add` (the list of permissions that were granted), `remove` (the list of permissions that were revoked).
`getRecipientSharePermissions`	`name`: The name of the share.
`getActivationUrlInfo`	`recipient_name`: The name of the recipient who opened the activation URL. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.
`retrieveRecipientToken`	`recipient_name`: The name of the recipient who downloaded the token. `is_ip_access_denied`: None if there is no IP access list configured. Otherwise, `true` if the request was denied and `false` if the request was not denied. `sourceIPaddress` is the recipient IP address.

Logged errors

Delta Sharing logs the following errors for data providers. Items between < and > characters represent placeholder text.

Delta Sharing is not enabled on the selected metastore.

DatabricksServiceException: FEATURE_DISABLED:
Delta Sharing is not enabled

An operation was attempted on a catalog that does not exist.

DatabricksServiceException: CATALOG_DOES_NOT_EXIST:
Catalog ‘<catalog>’ does not exist.

A user who is not an account admin or metastore admin attempted to perform a privileged operation.

DatabricksServiceException: PERMISSION_DENIED:
Only administrators can <operation_name> <operation_target>

An operation was attempted on a metastore from a workspace to which the metastore is not assigned.

DatabricksServiceException: INVALID_STATE:
Workspace <workspace_name> is no longer assigned to this metastore

A request was missing the recipient name or share name.

DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare Missing required field: <recipient_name>/<share_name>

A request included an invalid recipient name or share name.

DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare <recipient_name>/<share_name> is not a valid name

A user attempted to share a table that is not in a Unity Catalog metastore.

DatabricksServiceException: INVALID_PARAMETER_VALUE: Only managed or external table on Unity Catalog can be added to a share

A user attempted to rotate a recipient that was already in a rotated state and whose previous token had not yet expired.

DatabricksServiceException: INVALID_PARAMETER_VALUE: There are already two active tokens for recipient <recipient_name>

A user attempted to create a new recipient or share with the same name as an existing one.

DatabricksServiceException: RECIPIENT_ALREADY_EXISTS/SHARE_ALREADY_EXISTS: Recipient/Share <name> already exists`

A user attempted to perform an operation on a recipient or share that does not exist.

DatabricksServiceException: RECIPIENT_DOES_NOT_EXIST/SHARE_DOES_NOT_EXIST: Recipient/Share '<name>' does not exist

A user attempted to add a table to a share, but the table had already been added.

DatabricksServiceException: RESOURCE_ALREADY_EXISTS: Shared Table '<name>' already exists

A user attempted to perform an operation that referenced a table that does not exist.

DatabricksServiceException: TABLE_DOES_NOT_EXIST: Table '<name>' does not exist

A user attempted to perform an operation that referenced a schema that did not exist.

DatabricksServiceException: SCHEMA_DOES_NOT_EXIST: Schema '<name>' does not exist

For a list of auditable events and errors logged for data recipients, see Audit and monitor data access using Delta Sharing (for recipients).