Gravar registros de tarefas

Este documento descreve como gravar registros de tarefas e como criar e executar um job em lote com registros de tarefas.

Quando o registro está ativado para um job, os registros de tarefas são gerados a partir de mensagens que os executáveis do job imprimem durante a execução. Ao configurar os runnables para gravar logs de tarefas, você pode mostrar informações personalizadas no Cloud Logging, o que pode facilitar a análise e a solução de problemas. Para saber mais sobre registros, consulte Analisar um job usando registros.

Antes de começar

  1. Se você nunca usou o Batch, consulte Começar a usar o Batch e ative o Batch concluindo os pré-requisitos para projetos e usuários.

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

Criar e executar um job com registros de tarefas

Para criar e executar um job que você quer que tenha registros de tarefas, faça o seguinte ao criar o job:

  1. Ative os registros para o job. Isso permite que todos os registros escritos para o job sejam gerados.

  2. Para cada registro de tarefa que você quer que o job tenha, adicione um comando que grava um registro de tarefa 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 de erro padrão (stderr) durante a execução. Por exemplo, é possível gravar logs de tarefas usando o comando echo. A estrutura do registro de tarefas resultante varia de acordo com a formatação do conteúdo impresso. Especifique que você pode gravar cada registro de tarefa usando uma das seguintes opções:

Gravar um registro não estruturado imprimindo uma string

Os 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 sem formatação, 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 resume a finalidade do registro de tarefas. Por exemplo, The summary for a task log..
  • PROJECT_ID: o ID do projeto do seu projeto.

É possível imprimir uma string usando vários métodos, como incluir o comando echo a seguir em um executável:

echo MESSAGE

Para conferir exemplos completos 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 imprimindo um objeto JSON

Com os registros estruturados, você pode definir qualquer um dos seguintes:

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 você 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 abaixo, que define uma mensagem, a gravidade e dois campos personalizados.

{
  "message": "MESSAGE"
  "severity": "SEVERITY"
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
}

A impressão desse 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 resume 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 acessar os registros de um job. A gravidade precisa ser um dos enumerações LogSeverity convertidos em uma string com apenas a primeira letra em maiúsculo. Por exemplo, para o tipo enumerado ERROR, especifique Error.
  • CUSTOM_FIELD_1 e CUSTOM_FIELD_2: os nomes de campos personalizados para o registro de tarefas, por exemplo, custom_field_1 e custom_field_2.
  • CUSTOM_VALUE_1 e CUSTOM_VALUE_2: os valores dos campos personalizados do registro de tarefas, que podem ser vários tipos de dados e podem precisar de aspas, por exemplo, "the first custom field" e 2.
  • PROJECT_ID: o ID do projeto do seu projeto.

É possível imprimir esse exemplo de objeto JSON usando vários métodos. Por exemplo, os exemplos a seguir demonstram alguns dos métodos possíveis para imprimir o objeto JSON de exemplo:

  • Imprima uma string equivalente usando o comando echo.

  • Imprima um dicionário equivalente usando Python.

comando de eco

Para imprimir o objeto JSON de exemplo usando o comando echo e uma string equivalente, inclua o comando a seguir 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 é semelhante ao seguinte:

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 objeto JSON de exemplo usando Python e um dicionário equivalente, inclua o seguinte exemplo 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 é semelhante ao seguinte:

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