Configurar eventos de status personalizados para descrever executáveis

Neste documento, explicamos como configurar eventos de status personalizados, que descrevem os executáveis de um job, ao criar e executar um job no Batch. Para saber mais sobre eventos de status, consulte Visualizar o histórico de um job por meio de eventos de status.

Os eventos de status personalizados permitem fornecer mais detalhes no histórico de uma tarefa sobre o progresso dos executáveis, o que pode ajudar a facilitar a análise e a solução de problemas de um job. Por exemplo, é possível configurar eventos de status personalizados que descrevem quando um executável é iniciado, um executável termina, uma barreira executável é alcançada ou um evento importante acontece durante a progressão do código.

Antes de começar

Configurar eventos de status personalizados

Configure eventos de status personalizados usando uma ou mais das seguintes opções ao criar um job:

Descrever o estado de um executável

É possível configurar eventos de status personalizados que descrevem o estado de um executável definindo o nome de exibição dele (campo displayName). Os eventos de status personalizado resultantes variam um pouco para diferentes tipos de executáveis:

  • Se você definir um nome de exibição para um contêiner executável ou script executável, o Batch adicionará automaticamente dois tipos de eventos de status personalizados. O primeiro evento de status personalizado indica sempre que uma tarefa inicia esse executável. O segundo evento de status personalizado indica sempre que uma tarefa conclui esse executável e o código de saída correspondente.

  • Se você definir um nome de exibição para uma barreira executável, o Batch adicionará automaticamente um evento de status personalizado que indica sempre que uma tarefa atinge essa barreira.

Para criar e executar um job com eventos de status personalizados que descrevam o estado de um executável, defina o campo displayName para um ou mais executáveis usando a CLI gcloud ou a API Batch.

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

Por exemplo, um job com eventos de status personalizados que descreve o estado de cada executável pode ter um arquivo de configuração JSON semelhante ao seguinte:

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

Substitua DISPLAY_NAME1, DISPLAY_NAME2 e DISPLAY_NAME3 pelo nome do executável, que precisa ser exclusivo no job. Por exemplo, script 1, barrier 1 e script 2.

Quando a execução do job de exemplo terminar, os eventos de status personalizados resultantes de cada tarefa serão semelhantes aos seguintes:

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

Indicar eventos importantes do tempo de execução

É possível configurar eventos de status personalizados que indicam quando um evento importante acontece enquanto um executável está em execução. Para isso, configure esse executável para gravar um registro de tarefas estruturada que define uma string para o campo Evento de status personalizado em lote (batch/custom/event).

Se um contêiner executável ou um script executável gravar um registro de tarefa estruturado que defina o campo JSON batch/custom/event, ele vai produzir um evento de status personalizado nesse momento. Embora você possa configurar o registro de tarefas estruturada para incluir outros campos, o evento de status personalizado inclui apenas a string do campo batch/custom/event.

Para criar e executar um job com eventos de status personalizados que indicam quando um evento importante acontece, configure um ou mais executáveis para gravar um registro estruturado imprimindo JSON e defina o campo batch/custom/event como parte do registro.

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

Por exemplo, um job com eventos de status personalizados que indicam quando um evento importante acontece pode ter um arquivo de configuração JSON semelhante ao seguinte:

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

Substitua EVENT_DESCRIPTION por uma descrição do evento de status personalizado, por exemplo, halfway done.

Após a execução do job de exemplo, o evento de status personalizado resultante para cada tarefa será semelhante ao seguinte:

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

A seguir