Mengonfigurasi peristiwa status kustom untuk mendeskripsikan runnable

Dokumen ini menjelaskan cara mengonfigurasi peristiwa status kustom, yang menjelaskan fungsi perintah yang dapat dijalankan, saat Anda membuat dan menjalankan tugas Batch. Untuk mempelajari peristiwa status, baca Melihat histori tugas melalui peristiwa status.

Peristiwa status kustom memungkinkan Anda memberikan detail tambahan dalam histori tugas tentang progres runnable-nya, yang dapat membantu memudahkan analisis dan pemecahan masalah tugas. Misalnya, Anda dapat mengonfigurasi peristiwa status kustom yang menjelaskan kapan proses runnable dimulai, proses berakhir, batas runnable tercapai, atau peristiwa penting terjadi selama proses kode Anda.

Sebelum memulai

Jika belum pernah menggunakan Batch, baca Mulai menggunakan Batch dan aktifkan Batch dengan menyelesaikan prasyarat untuk project dan pengguna.
Untuk mendapatkan izin yang Anda perlukan guna membuat tugas, minta administrator untuk memberi Anda peran IAM berikut:
- Batch Job Editor (roles/batch.jobsEditor) pada project
- Service Account User (roles/iam.serviceAccountUser) pada akun layanan tugas, yang secara default merupakan akun layanan Compute Engine default
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengonfigurasi peristiwa status kustom

Konfigurasikan peristiwa status kustom menggunakan satu atau beberapa opsi berikut saat Anda membuat tugas:

Deskripsikan status runnable dengan menentukan nama tampilannya. Anda dapat melakukannya saat membuat tugas menggunakan gcloud CLI atau Batch API.
Tunjukkan peristiwa runtime yang penting dengan menulis log tugas terstruktur dengan kolom batch/custom/event untuk setiap peristiwa. Anda dapat melakukannya saat menggunakan metode apa pun untuk membuat tugas sebagai bagian dari definisi skrip dan container.

Menjelaskan status runnable

Anda dapat mengonfigurasi peristiwa status kustom yang mendeskripsikan status runnable dengan menentukan nama tampilan runnable (kolom displayName). Peristiwa status kustom yang dihasilkan sedikit berbeda untuk berbagai jenis runnable:

Jika Anda menentukan nama tampilan untuk container runnable atau skrip runnable, Batch akan otomatis menambahkan dua jenis peristiwa status kustom. Peristiwa status kustom pertama menunjukkan setiap kali tugas memulai yang dapat dijalankan ini. Peristiwa status kustom kedua menunjukkan setiap kali tugas menyelesaikan dapat dijalankan ini dan kode keluar yang sesuai.
Jika Anda menentukan nama tampilan untuk barrier runnable, Batch akan otomatis menambahkan peristiwa status kustom yang menunjukkan setiap kali tugas mencapai batasan ini.

Untuk membuat dan menjalankan tugas dengan peristiwa status kustom yang menjelaskan status runnable, tentukan kolom displayName untuk satu atau beberapa runnable menggunakan gcloud CLI atau Batch API.

...
"runnables": [
  {
    "displayName":DISPLAY_NAME,
    ...
  }
]
...

Misalnya, tugas dengan peristiwa status kustom yang mendeskripsikan setiap status runnable dapat memiliki file konfigurasi JSON yang mirip dengan berikut ini:

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "displayName":"DISPLAY_NAME1",
            "script": {
              "text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
            }
          },
          {
            "displayName":"DISPLAY_NAME2",
            "barrier": {}
          },
          {
            "displayName":"DISPLAY_NAME3",
            "script": {
              "text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
            }
          }
        ]
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

Ganti DISPLAY_NAME1, DISPLAY_NAME2, dan DISPLAY_NAME3 dengan nama runnable, yang harus unik dalam tugas—misalnya, script 1, barrier 1, dan script 2.

Setelah contoh tugas selesai berjalan, peristiwa status kustom yang dihasilkan untuk setiap tugas akan serupa dengan berikut ini:

statusEvents:
  ...
  - description: 'script at index #0 with display name [DISPLAY_NAME1] started.'
    eventTime: '...'
    type: RUNNABLE_EVENT
  - description: 'script at index #0 with display name [DISPLAY_NAME1] finished with exit
      code 0.'
    eventTime: '...'
    type: RUNNABLE_EVENT
  - description: 'barrier at index #2 with display name [DISPLAY_NAME2] reached.'
    eventTime: '...'
    type: BARRIER_REACHED_EVENT
  - description: 'script at index #2 with display name [DISPLAY_NAME3] started.'
    eventTime: '...'
    type: RUNNABLE_EVENT
  - description: 'script at index #2 with display name [DISPLAY_NAME3] finished with exit
      code 0.'
    eventTime: '...'
    type: RUNNABLE_EVENT
  ...

Menunjukkan peristiwa runtime yang penting

Anda dapat mengonfigurasi peristiwa status kustom yang menunjukkan kapan peristiwa penting terjadi saat runnable berjalan dengan mengonfigurasi runnable tersebut untuk menulis log tugas terstruktur yang menentukan string untuk kolom peristiwa status kustom Batch (batch/custom/event).

Jika container dapat dijalankan atau skrip dapat dijalankan menulis log tugas terstruktur yang menentukan kolom JSON batch/custom/event, container tersebut akan menghasilkan peristiwa status kustom pada saat itu. Meskipun Anda dapat mengonfigurasi log tugas terstruktur untuk menyertakan kolom tambahan, peristiwa status kustom hanya menyertakan string untuk kolom batch/custom/event.

Untuk membuat dan menjalankan tugas dengan peristiwa status kustom yang menunjukkan kapan peristiwa penting terjadi, konfigurasikan satu atau beberapa runnable untuk menulis log terstruktur dengan mencetak JSON dan tentukan kolom batch/custom/event sebagai bagian dari log.

...
"runnables": [
  {
    ...
    "echo '{\"batch/custom/event\":\"EVENT_DESCRIPTION\"}'"
    ...
  }
]
...
"logsPolicy": {
  "destination": "CLOUD_LOGGING"
}
...

Misalnya, tugas dengan peristiwa status kustom yang menunjukkan kapan suatu peristiwa penting terjadi dapat memiliki file konfigurasi JSON yang mirip dengan berikut ini:

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "sleep 30; echo '{\"batch/custom/event\": \"EVENT_DESCRIPTION\"}'; sleep 30"
            }
          }
        ]
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

Ganti EVENT_DESCRIPTION dengan deskripsi untuk peristiwa status kustom—misalnya, halfway done.

Setelah contoh tugas selesai berjalan, peristiwa status kustom yang dihasilkan untuk setiap tugas akan serupa dengan berikut ini:

statusEvents:
  ...
  - description: EVENT_DESCRIPTION
    eventTime: '...'
    type: RUNNABLE_CUSTOM_EVENT
  ...

Langkah selanjutnya

Jika Anda mengalami masalah saat membuat atau menjalankan tugas, lihat Pemecahan masalah.
Pelajari cara melihat peristiwa status.
Pelajari cara menulis log tugas.
Pelajari opsi penciptaan pekerjaan lainnya.