Configura eventos de estado personalizados para describir ejecutables

En este documento, se explica cómo configurar eventos de estado personalizados, que describen los ejecutables de un trabajo, cuando creas y ejecutas un trabajo por lotes. Para obtener información sobre los eventos de estado, consulta Visualiza el historial de un trabajo a través de eventos de estado.

Los eventos de estado personalizados te permiten proporcionar detalles adicionales en el historial de una tarea sobre el progreso de sus ejecutables, lo que puede ayudar a que un trabajo sea más fácil de analizar y solucionar problemas. Por ejemplo, puedes configurar eventos de estado personalizados en los que se describa cuándo se inicia un ejecutable, finaliza un ejecutable, se alcanza una barrera ejecutable o cuando ocurre un evento importante durante el progreso del código.

Antes de comenzar

Si no has usado Batch antes, revisa Comienza a usar Batch y completa los requisitos previos para los proyectos y usuarios a fin de habilitar Batch.
Si quieres obtener los permisos que necesitas para crear un trabajo, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Editor de trabajos por lotes (roles/batch.jobsEditor) en el proyecto
- Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio del trabajo, que de forma predeterminada es la cuenta de servicio predeterminada de Compute Engine
Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios a través de los roles personalizados o de otros roles predefinidos.

Configura eventos de estado personalizados

Configura los eventos de estado personalizados con una o más de las siguientes opciones cuando crees un trabajo:

Para describe el estado de un ejecutable, define su nombre visible. Puedes hacerlo cuando creas un trabajo con gcloud CLI o la API de Batch.
Indica eventos importantes del entorno de ejecución escribiendo un registro de tareas estructurado con el campo batch/custom/event para cada evento. Puedes hacerlo cuando uses cualquier método para crear un trabajo como parte de las definiciones de ejecutables del contenedor y la secuencia de comandos.

Describe el estado de un ejecutable

Puedes configurar eventos de estado personalizados que describen el estado de un ejecutable si defines el nombre visible de este (campo displayName). Los eventos de estado personalizados resultantes varían un poco según los diferentes tipos de ejecutables:

Si defines un nombre visible para un contenedor ejecutable o ejecutable de una secuencia de comandos, Batch agrega automáticamente dos tipos de eventos de estado personalizados. El primer evento de estado personalizado indica cada vez que una tarea inicia este ejecutable. El segundo evento de estado personalizado indica cada vez que una tarea finaliza esta ejecutable y el código de salida correspondiente.
Si defines un nombre visible para una barrera ejecutable, Batch agrega automáticamente un evento de estado personalizado que indica cada vez que una tarea alcanza esta barrera.

Para crear y ejecutar un trabajo con eventos de estado personalizados que describan el estado de un ejecutable, define el campo displayName para uno o más ejecutables con gcloud CLI o la API de Batch.

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

Por ejemplo, un trabajo con eventos de estado personalizados que describe el estado de cada ejecutable puede tener un archivo de configuración JSON similar al siguiente:

{
  "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"
  }
}

Reemplaza DISPLAY_NAME1, DISPLAY_NAME2 y DISPLAY_NAME3 por el nombre del ejecutable, que debe ser único dentro del trabajo, por ejemplo, script 1, barrier 1 y script 2.

Una vez que termine de ejecutarse el trabajo de ejemplo, los eventos de estado personalizados resultantes para cada tarea serán similares a los siguientes:

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

Cómo indicar eventos importantes en el entorno de ejecución

Puedes configurar eventos de estado personalizados que indiquen cuándo sucede un evento importante mientras se ejecuta un ejecutable. Para ello, debes configurar ese ejecutable para que escriba un registro de tareas estructurado que defina una string para el campo de evento de estado personalizado de Batch (batch/custom/event).

Si un contenedor ejecutable o un ejecutable de secuencia de comandos escribe un registro de tareas estructurado que define el campo JSON batch/custom/event, produce un evento de estado personalizado en ese momento. Aunque puedes configurar el registro de tareas estructurado para que incluya campos adicionales, el evento de estado personalizado solo incluye la cadena para el campo batch/custom/event.

Para crear y ejecutar un trabajo con eventos de estado personalizados que indiquen cuándo ocurre un evento importante, configura uno o más ejecutables para que escriban un registro estructurado mediante la impresión de JSON y define el campo batch/custom/event como parte del registro.

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

Por ejemplo, un trabajo con eventos de estado personalizados que indican cuándo ocurre un evento importante puede tener un archivo de configuración JSON similar al siguiente:

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

Reemplaza EVENT_DESCRIPTION por una descripción para el evento de estado personalizado, por ejemplo, halfway done.

Una vez que el trabajo de ejemplo termine de ejecutarse, el evento de estado personalizado resultante para cada tarea será similar al siguiente:

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

¿Qué sigue?

Si tienes problemas para crear o ejecutar un trabajo, consulta Solución de problemas.
Obtén más información sobre cómo ver eventos de estado.
Aprende a escribir registros de tareas.
Obtén más información sobre las opciones de creación de trabajos.