Gravar registros de tarefas

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

Quando o registro é 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 executáveis para gravar registros de tarefas, você pode mostrar 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

  1. Se você nunca usou o Batch, consulte Introdução ao Batch e ative-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 usando personalizados papéis ou outros predefinidos papéis.

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 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 fluxo de saída padrão (stdout) ou no fluxo de erro padrão (stderr) durante a execução. Por exemplo, é possível gravar registros de tarefas usando o echo comando. A estrutura do registro de tarefa 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:

Grave 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 tarefa que contenha a seguinte string:

MESSAGE

A impressão dessa string de exemplo resulta em um registro de tarefa 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 tarefa. Por exemplo, The summary for a task log..
  • PROJECT_ID: o ID do projeto.

É possível imprimir uma string usando vários métodos, como incluir 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.

Grave um registro estruturado imprimindo um objeto JSON

Os registros estruturados permitem 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 tarefa 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 tarefa 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 tarefa. Por exemplo, The summary for a task log..
  • SEVERITY: a gravidade do registro, que você pode usar como um filtro ao visualizar registros de um job. A gravidade precisa ser um dos LogSeverity enums convertidos em uma string com apenas a primeira letra maiúscula. Por exemplo, para o enum ERROR, especifique Error.
  • CUSTOM_FIELD_1 e CUSTOM_FIELD_2: os nomes dos campos personalizados para o registro de tarefa. 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 tarefa, 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.

É possível imprimir esse objeto JSON de exemplo 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:

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

Em seguida, o registro de tarefa 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))"
}

Em seguida, o registro de tarefa 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