Skip to main content
Last updated on

Deliver serverless logs to Unity Catalog volumes

Serverless log delivery writes application logs from serverless jobs to a Unity Catalog volume. Workspace admins configure a destination for the workspace so that teams can retain logs and process them with their observability tools. Logs are delivered asynchronously after job completion. Delivery can take several minutes and varies with processing and upload time.

Beta

This feature is in Beta. To use it, a workspace admin must turn on Serverless log delivery to Unity Catalog volumes from the Previews page. See Manage Databricks previews.

Requirements​

  • A workspace with serverless compute and Unity Catalog enabled.
  • Serverless environment version 5 or later.
  • The workspace admin role to configure log delivery. See Assign the workspace admin role to a user.
  • The Serverless log delivery to Unity Catalog volumes preview enabled for the workspace. It might already be enabled. If it is disabled, a workspace admin can enable it on the Previews page. Enabling the preview makes the configuration available; it does not start delivery.
  • A destination volume. The admin configuring delivery needs USE CATALOG on its catalog, USE SCHEMA on its schema, and READ VOLUME and WRITE VOLUME on the volume. See Privileges for Unity Catalog volumes.
note

Configure delivery only to a trusted volume with restricted access. Delivered logs can contain sensitive information, including user emails, storage paths, stack traces, internal identifiers, and temporary signed URLs. Logs are not guaranteed to be free of secrets.

Users with access to the destination can read the delivered logs, including logs from other users' jobs. Restrict access to the volume accordingly.

Enable log delivery​

A workspace admin must enable log delivery for the workspace.

  1. Open Settings from your user menu.
  2. Under Workspace admin, click Compute.
  3. In the Log delivery section, turn on Serverless log delivery.
  4. In Configure log delivery, enter a Volume path, such as /Volumes/observability/production/serverless_logs, or click the folder icon to browse volumes.
  5. Click Save. Saving the destination enables delivery.

The setting applies at the workspace level. You do not need to configure each job separately.

Read delivered logs​

Application output includes standard output and standard error from user code, including user-defined functions (UDFs). Use Catalog Explorer to browse the destination volume and inspect delivered files. See Work with files in Unity Catalog volumes.

Log delivery does not provide cluster metrics or query profiles. Use the job run page to investigate run status and performance alongside the application logs. See Monitor Lakeflow Jobs.

Query delivered logs with SQL​

Use read_files to query the delivered text files. Replace the volume path in this example with your destination. To read the logs, you need USE CATALOG on the catalog, USE SCHEMA on the schema, and READ VOLUME on the volume.

Create a temporary view that extracts job and run identifiers from the file path and keeps each line of log output:

SQL
CREATE OR REPLACE TEMPORARY VIEW serverless_job_logs AS
SELECT
  regexp_extract(_metadata.file_path, '/job_id=([^/]+)/', 1) AS job_id,
  regexp_extract(_metadata.file_path, '/job_run_id=([^/]+)/', 1) AS job_run_id,
  regexp_extract(_metadata.file_path, '/task_run_id=([^/]+)/', 1) AS task_run_id,
  _metadata.file_name AS file_name,
  value AS log_line
FROM read_files(
  '/Volumes/observability/production/serverless_logs/',
  format => 'text'
);

Find lines containing errors across job runs:

SQL
SELECT job_id, job_run_id, task_run_id, file_name, log_line
FROM serverless_job_logs
WHERE log_line LIKE '%ERROR%';

Identify jobs with the most error lines:

SQL
SELECT
  job_id,
  count(*) AS error_lines,
  count(DISTINCT job_run_id) AS affected_runs
FROM serverless_job_logs
WHERE log_line LIKE '%ERROR%'
GROUP BY job_id
ORDER BY error_lines DESC;

These queries search for the literal text ERROR. Adjust the filter to match your application's logging format. See read_files table-valued function.

Change the destination or disable delivery​

To change the destination, open Settings > Compute > Log delivery, click the pencil icon beside the volume name, enter or browse to a new path, and click Save. Saving a destination enables delivery, including when delivery was disabled.

To disable delivery, open Settings > Compute > Log delivery and turn off Serverless log delivery. The setting retains the destination so you can enable delivery again without selecting another volume. Disabling delivery does not remove files already written to the volume. Manage access and retention for those files separately.

Troubleshoot missing logs​

If logs do not appear after job completion:

  1. Check that Serverless log delivery is enabled under Settings > Compute > Log delivery. Enabling the preview alone does not start delivery.
  2. Check that the configured volume exists and that the admin who configured delivery retains the required permissions.
  3. Confirm that the job uses serverless compute and produces application output. Allow several minutes after job completion for asynchronous delivery. Processing and upload time can delay delivery.

For classic compute log delivery, see Compute log delivery.

On this page