Gravar registros de tarefas

Este documento descreve como gravar registros de tarefas e como criar e executar um job do Batch que tenha registros de tarefas.

Quando o registro em um job é ativado, os registros de tarefas são gerados com base nas mensagens que os executáveis do job imprimem durante a execução. Ao configurar os executáveis para gravar registros de tarefas, é possível mostrar informações personalizadas no Cloud Logging, o que facilita 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

  1. Se você nunca usou o Batch, leia Começar a usar o Batch e ative o serviço 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 tenha registros de tarefas, faça o seguinte ao criar o job:

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

  2. Para cada registro de tarefa que você quer que o job tenha, adicione um comando que grave um registro de tarefa em um executável. Quando o job é executado, um registro de tarefa é gerado sempre que um comando para gravar um registro de tarefa é executado.

    Para saber como gravar registros de tarefas, consulte Gravar registros de tarefas neste documento.

Gravar registros de tarefas

Um registro de tarefa é gravado para qualquer conteúdo que os executáveis de um job imprimam no stream de saída padrão (stdout) ou de erro padrão (stderr) durante o tempo 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 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 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 tarefa semelhante a este:

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

Escrever um registro estruturado imprimindo um objeto JSON

Com os registros estruturados, é possível definir qualquer uma das seguintes opções:

Para gravar um registro estruturado, imprima um objeto JSON. As seções a seguir mostram como definir um registro com alguns dos campos padrão e personalizados. Se quiser saber como definir um log 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
}

A impressão desse objeto JSON resulta em um registro de tarefas semelhante a este:

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 visualizar os registros de um job. A gravidade precisa ser uma das enumerações LogSeverity convertidas em uma string com apenas a primeira letra maiúscula. Por exemplo, para a enumeração ERROR, especifique Error.
  • CUSTOM_FIELD_1 e CUSTOM_FIELD_2: os nomes dos 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 para o registro de tarefas, que podem ser vários tipos de dados e talvez precisem de aspas. Por exemplo, "the first custom field" e 2.
  • PROJECT_ID: o ID do projeto do seu projeto.

Você pode imprimir este exemplo de objeto JSON usando vários métodos. Por exemplo, as amostras 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 echo

Para imprimir o objeto JSON de exemplo 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 tarefa resultante é 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 objeto JSON de exemplo 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 tarefa resultante é 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