Neste documento, descrevemos como gravar registros de tarefas e como criar e executar um job do Batch que tenha registros de tarefas.
Quando a geração de registros está ativada para um job, os registros de tarefas são gerados a partir de mensagens que os executáveis do job imprimem durante o tempo de execução. Ao configurar os executáveis para gravar registros de tarefas, é possível exibir informações personalizadas no Cloud Logging, o que pode facilitar a análise e a solução de problemas dos jobs. Para saber mais sobre registros, consulte Analisar um job usando registros.
Antes de começar
- Se você nunca usou o Batch, leia Primeiros passos com o Batch e ative-o concluindo os pré-requisitos para projetos e usuários.
-
Para receber as permissões necessárias para criar um job que grava registros, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Para criar um job, faça o seguinte:
-
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, por padrão, é a conta de serviço padrão do Compute Engine
-
Editor de jobs em lote (
-
Para acessar os registros:
Visualizador de registros (
roles/logging.viewer
) no projeto
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
-
Para criar um job, faça o seguinte:
Criar e executar um job que tenha registros de tarefas
Para criar e executar um job que você quer que tenha registros de tarefas, faça o seguinte quando estiver criando o job:
- Ative os registros para o job. Isso permite que todos os registros gravados para o job sejam gerados.
Para cada registro de tarefas que você quer que o job tenha, adicione um comando que grava um registro de tarefas em um executável. Quando o job é executado, um registro de tarefas é gerado sempre que um comando para gravar um registro de tarefas é executado.
Para saber como gravar registros de tarefas, consulte Gravar registros de tarefas neste documento.
Gravar registros de tarefas
Um registro de tarefas é gravado para qualquer conteúdo que os executáveis de um job imprimem no
stream de saída padrão (stdout
) ou no stream de erro padrão (stderr
)
durante o ambiente de execução. Por exemplo, é possível gravar registros de tarefas usando o
comando echo
.
A estrutura do registro de tarefas resultante varia de acordo com a formatação do
conteúdo impresso. Especificamente, é possível gravar cada registro de tarefas usando uma das
seguintes opções:
Gravar um registro não estruturado exibindo uma string. Registros não estruturados são simples e só permitem definir o campo
textPayload
do registro.Gravar um registro estruturado imprimindo JSON. Os registros estruturados exigem formatação JSON, que permite definir vários campos, incluindo alguns campos de registro padrão, campos personalizados e eventos de status personalizados.
Por exemplo, é possível usar registros de tarefas estruturados para definir a gravidade do registro, que pode ser usado como um filtro ao visualizar registros de um job.
Gravar um registro não estruturado gerando uma string
Registros não estruturados permitem definir uma mensagem, que é uma string que aparece no
campo textPayload
do registro.
Para gravar um registro não estruturado, imprima uma string não formatada, conforme demonstrado nas seções a seguir.
Exemplo de registro não estruturado
Por exemplo, suponha que você queira um registro de tarefas que contenha a seguinte string:
MESSAGE
A impressão dessa string de exemplo resulta em um registro de tarefas semelhante ao seguinte:
insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...
Substitua:
MESSAGE
: a mensagem, que é uma string que resumia a finalidade do registro de tarefas, por exemplo,The summary for a task log.
.PROJECT_ID
: o ID do projeto (link em inglês).
Imprimir uma string
É possível imprimir uma string usando vários métodos, por exemplo, incluindo o
seguinte comando echo
em um executável:
echo MESSAGE
Para exemplos abrangentes de jobs que usam o comando echo
para gravar
registros de tarefas não estruturados, consulte
Criar e executar um job básico.
Gravar um registro estruturado gerando um objeto JSON
Com os registros estruturados, é possível definir o seguinte:
- Campos padrão aceitos pelo agente do Cloud Logging
- Campos personalizados
- Eventos de status personalizados
Para gravar um registro estruturado, imprima um objeto JSON. As seções a seguir demonstram como definir um registro com alguns dos campos padrão e personalizados. Se quiser saber como definir um registro com eventos de status personalizados, consulte também Configurar eventos de status personalizados.
Exemplo de registro estruturado
Por exemplo, suponha que você queira um registro de tarefas que contenha as informações no objeto JSON a seguir, que define uma mensagem, gravidade e dois campos personalizados.
{
"message": "MESSAGE"
"severity": "SEVERITY"
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
}
Imprimir esse objeto JSON resulta em um registro de tarefas semelhante ao seguinte:
insertId: ...
jsonPayload:
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...
Substitua:
MESSAGE
: a mensagem, que é uma string que resumia a finalidade do registro de tarefas, por exemplo,The summary for a task log.
.SEVERITY
: a gravidade do registro, que pode ser usada como filtro ao visualizar os registros de um job. A gravidade precisa ser um dos tipos enumeradosLogSeverity
convertidos em uma string com apenas a primeira letra em maiúscula. Por exemplo, para o tipo enumeradoERROR
, especifiqueError
.CUSTOM_FIELD_1
eCUSTOM_FIELD_2
: os nomes dos campos personalizados do registro de tarefas, por exemplo,custom_field_1
ecustom_field_2
.CUSTOM_VALUE_1
eCUSTOM_VALUE_2
: os valores dos campos personalizados para o registro de tarefas, que podem ser vários tipos de dados e podem precisar de aspas. Por exemplo,"the first custom field"
e2
.PROJECT_ID
: o ID do projeto (link em inglês).
Imprimir um objeto JSON
É possível imprimir esse exemplo de objeto JSON usando vários métodos. Os exemplos a seguir demonstram alguns dos métodos possíveis para imprimir o objeto JSON de exemplo:
- Mostre uma string equivalente usando o comando
echo
. Gere um dicionário equivalente usando Python.
Comando echo
Para mostrar o exemplo de objeto JSON usando o comando echo
e uma
string equivalente, inclua o seguinte comando em um executável:
echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'
Por exemplo, suponha que você crie e execute um job com o seguinte executável:
"script": {
"text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}
O registro de tarefas resultante será semelhante a este:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
Python
Para imprimir o exemplo de objeto JSON usando Python e um dicionário equivalente, inclua o exemplo a seguir em um executável:
#!/usr/bin/env python3
import json
entry = dict(
severity="SEVERITY",
message="MESSAGE",
CUSTOM_FIELD_1=CUSTOM_VALUE_1,
CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))
Por exemplo, suponha que você crie e execute um job com o seguinte executável:
"script": {
"text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}
O registro de tarefas resultante será semelhante a este:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
A seguir
- Para mais informações sobre a formatação de registros, consulte Geração de registros estruturada na documentação do Cloud Logging.
- Saiba como escrever registros de tarefas estruturados que incluem eventos de status personalizados.
- Saiba como visualizar os registros de tarefas de um job.
- Saiba mais sobre mais opções de criação de jobs.