Este documento explica como configurar eventos de status personalizados, que descrevem os executáveis de um job, ao criar e executar um job em lote. Para saber mais sobre eventos de status, consulte Conferir o histórico de um job por eventos de status.
Os eventos de status personalizados permitem que você forneça mais detalhes no histórico de uma tarefa sobre o progresso dos executáveis, o que pode ajudar a tornar um job mais fáceis de analisar e solucionar. Por exemplo, é possível configurar eventos de status personalizados que descrevem quando um executável começa, um executável termina, uma barreira executável é atingido ou um evento importante acontece durante a progressão de seu código.
Antes de começar
- Se você nunca usou o Batch antes, revise Introdução ao Batch e ativar o Batch. pré-requisitos para projetos e usuários.
-
Para ter as permissões necessárias para criar um job, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Editor de jobs em lote (
roles/batch.jobsEditor
) no projeto -
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço do job, que é a conta de serviço padrão do Compute Engine
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
-
Editor de jobs em lote (
Configurar eventos de status personalizados
Configure eventos de status personalizados usando um ou mais dos seguintes ao criar um job:
Descrever o estado de um executável definindo seu nome de exibição. É possível fazer isso ao criar um job usando a CLI gcloud ou a API Batch.
Indique eventos importantes de execução gravando um registro de tarefas estruturado com o campo
batch/custom/event
para cada evento. É possível fazer isso ao usar qualquer método para criar um job como parte das definições dos executáveis de script e contêiner.
Descrever o estado de um executável
Para configurar eventos de status personalizados que descrevem o estado de um executável,
definir o nome de exibição de um executável;
(campo displayName
).
Os eventos de status personalizados resultantes variam um pouco para diferentes tipos de
runnables:
Se você definir um nome de exibição para um script ou contêiner executável, o lote vai adicionar automaticamente dois tipos de eventos de status personalizados. O primeiro evento de status personalizado indica quando uma tarefa inicia esse executável. O segundo evento de status personalizado indica sempre que uma tarefa é concluída esse executável e os código de saída.
Se você definir um nome de exibição barreira executável o Batch adiciona automaticamente um evento de status personalizado que indica sempre que uma tarefa atinge essa barreira.
Para criar e executar um trabalho com eventos de status personalizados que descrevem uma
executável, defina o campo displayName
para um ou mais
executáveis usando a CLI gcloud, a API Batch ou
biblioteca.
gcloud
Use a CLI do Google Cloud para
criar um job que
inclua o campo displayName
em uma ou mais definições de runnables
no arquivo JSON:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Por exemplo, um job com eventos de status personalizados que descrevem 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
.
API
Use a API REST para
criar um job que
inclua o campo displayName
em uma ou mais definições de runnables
no arquivo JSON:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Por exemplo, um job com eventos de status personalizados que descrevem 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
.
Go
Java
Node.js
Python
Após a conclusão da execução do job de exemplo, os eventos de status personalizados resultantes para cada tarefa são semelhantes a estes:
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 no momento da 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 o executável para gravar um
registro de tarefas estruturado que define uma string para o campo do evento de status personalizado
do lote (batch/custom/event
).
Se um contêiner ou script executável gravar um registro de tarefas estruturado
que define o campo JSON batch/custom/event
, ele produzirá um
evento de status personalizado naquele momento. É possível configurar o modelo
o registro de tarefas inclua campos adicionais, o evento de status personalizado incluirá
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 a este:
{
"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 da
evento de status personalizado, por exemplo, halfway done
.
Depois que o job de exemplo terminar a execução, o evento de status personalizado resultante para cada tarefa será semelhante ao seguinte:
statusEvents:
...
- description: EVENT_DESCRIPTION
eventTime: '...'
type: RUNNABLE_CUSTOM_EVENT
...
A seguir
- Se você tiver problemas para criar ou executar um job, consulte Solução de problemas.
- Saiba como visualizar eventos de status.
- Saiba como gravar registros de tarefas.
- Saiba mais sobre as opções de criação de jobs.