Gravar registros de tarefas

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

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:

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

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

É 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:

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 enumerados LogSeverity convertidos em uma string com apenas a primeira letra em maiúscula. Por exemplo, para o tipo enumerado ERROR, especifique Error.
  • CUSTOM_FIELD_1 e CUSTOM_FIELD_2: os nomes dos campos personalizados do 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 podem precisar de aspas. Por exemplo, "the first custom field" e 2.
  • PROJECT_ID: o ID do projeto (link em inglês).

É 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