View a job's history through status events

This document explains how to view status events for Batch jobs and tasks. Status events provide a history that you can use to analyze jobs and often contain useful error messages that you can use for troubleshooting.

Each job and each of its tasks have status events that are automatically created by Batch while the job runs. Each of these status events describe a state change and details about why that state was reached. To learn about job and task states, see Job lifecycle. Optionally, you can also configure a job to have custom status events, which describe the progress of runnables. To learn more about custom status events, see Configure custom status events.

Before you begin

  1. If you haven't used Batch before, review Get started with Batch and enable Batch by completing the prerequisites for projects and users.

  2. To get the permissions that you need to view jobs and tasks, ask your administrator to grant you the Batch Job Viewer (roles/batch.jobsViewer) or Batch Job Editor (roles/batch.jobsEditor) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

    You might also be able to get the required permissions through custom roles or other predefined roles.

View status events

Different status events might appear at the job level (statusEvents[] field for the job) and task level (statusEvents[] field for each task).

The following instructions explain how to view status events using the Google Cloud console, gcloud CLI, and Batch API. To use a client-library language, follow the steps to view the details of a job or view the details of a task and then see the corresponding statusEvents[] field.

View the status events of a job

Console

To view the status events of a job in the current project using the Google Cloud console, follow these steps:

  1. In the Google Cloud console, go to the Job list page.

    Go to Job list

  2. In the Job name column, click the name of a job.

    The Job details page opens.

    The Details tab is open by default.

  3. Click the Events tab.

gcloud

To view the status events of a job using the gcloud CLI, use the gcloud batch jobs describe command, and then see the statusEvents[] field.

gcloud batch jobs describe JOB_NAME \
    --location=LOCATION

Replace the following:

  • JOB_NAME: the name of an existing job.

  • LOCATION: the location where the job exists.

API

To view the status events of a job using the Batch API, make a GET request to the jobs.get method, and then see the statusEvents[] field.

GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME

Replace the following:

  • PROJECT_ID: the project ID of the current project.

  • LOCATION: the location where the job exists.

  • JOB_NAME: the name of an existing job.

View the status events of a task

gcloud

To view the status events of a task using the gcloud CLI, use the gcloud batch tasks describe command, and then see the statusEvents[] field.

gcloud batch tasks describe TASK_INDEX \
  --location=LOCATION \
  --job=JOB_NAME \
  --task_group=TASK_GROUP_NAME

Replace the following:

  • TASK_INDEX: the index of the task that you want to view the details of. In a task group, the task index starts at 0 for the first task and increases by 1 with each additional task. For example, a task group that contains four tasks has the indexes 0, 1, 2, and 3.

  • JOB_NAME: the name of an existing job.

  • LOCATION: the location where the job exists.

  • TASK_GROUP_NAME: the name of the task group that contains the task that you want to view the details of. The value must be set to group0.

API

To view the status events of a task using the Batch API, make a GET request to the tasks.get method, and then see the statusEvents[] field.

GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME/taskGroups/TASK_GROUP_NAME/tasks/TASK_INDEX

Replace the following:

  • PROJECT_ID: the project ID of the current project.

  • LOCATION: the location where the job exists.

  • JOB_NAME: the name of an existing job.

  • TASK_GROUP_NAME: the name of the task group that contains the task that you want to view the details of. The value must be set to group0.

  • TASK_INDEX: the index of the task that you want to view the details of. In a task group, the task index starts at 0 for the first task and increases by 1 with each additional task. For example, a task group that contains four tasks has the indexes 0, 1, 2, and 3.

What's next