Escrever registos de tarefas

Este documento descreve como escrever registos de tarefas e como criar e executar uma tarefa em lote que tenha registos de tarefas.

Quando o registo está ativado para uma tarefa, são gerados registos de tarefas a partir de mensagens que os executáveis da tarefa imprimem durante o tempo de execução. Ao configurar os seus executáveis para escrever registos de tarefas, pode apresentar informações personalizadas no Cloud Logging, o que pode ajudar a tornar os seus trabalhos mais fáceis de analisar e resolver problemas. Para saber mais sobre os registos, consulte o artigo Analise uma tarefa através de registos.

Antes de começar

  1. Se nunca usou o Batch, reveja o artigo Comece a usar o Batch e ative o Batch concluindo os pré-requisitos para projetos e utilizadores.

  2. Para receber as autorizações de que precisa para criar uma tarefa que escreve registos, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Crie e execute uma tarefa que tenha registos de tarefas

Para criar e executar uma tarefa cujos registos quer ter, faça o seguinte quando criar a tarefa:

  1. Ative os registos para a tarefa. Isto permite que sejam gerados quaisquer registos escritos para a tarefa.

  2. Para cada registo de tarefas que quer que a tarefa tenha, adicione um comando que escreva um registo de tarefas num executável. Quando a tarefa é executada, é gerado um registo de tarefas sempre que um comando para escrever um registo de tarefas é executado.

    Para saber como escrever registos de tarefas, consulte a secção Escreva registos de tarefas neste documento.

Escrever registos de tarefas

É escrito um registo de tarefas para qualquer conteúdo que os executáveis de uma tarefa imprimam na stream de saída padrão (stdout) ou na stream de erro padrão (stderr) durante o tempo de execução. Por exemplo, pode escrever registos de tarefas usando o comando echo. A estrutura do registo de tarefas resultante varia consoante a forma como formatou o conteúdo impresso. Em concreto, pode escrever cada registo de tarefas através de uma das seguintes opções:

Escreva um registo não estruturado imprimindo uma string

Os registos não estruturados permitem-lhe definir uma mensagem, que é uma string apresentada no campo textPayload do registo.

Para escrever um registo não estruturado, imprima uma string não formatada, conforme demonstrado nas secções seguintes.

Exemplo de registo não estruturado

Por exemplo, suponha que quer um registo de tarefas que contenha a seguinte string:

MESSAGE

A impressão desta string de exemplo resulta num registo de tarefas semelhante ao seguinte:

insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...

Substitua o seguinte:

  • MESSAGE: a mensagem, que é uma string que resume a finalidade do registo de tarefas. Por exemplo, The summary for a task log..
  • PROJECT_ID: o ID do projeto do seu projeto.

Pode imprimir uma string através de vários métodos, como incluir o seguinte comando echo num ficheiro executável:

echo MESSAGE

Para ver exemplos abrangentes de tarefas que usam o comando echo para escrever registos de tarefas não estruturados, consulte o artigo Crie e execute uma tarefa básica.

Escreva um registo estruturado imprimindo um objeto JSON

Os registos estruturados permitem-lhe definir qualquer um dos seguintes elementos:

Para escrever um registo estruturado, imprima um objeto JSON. As secções seguintes demonstram como definir um registo com alguns dos campos padrão e campos personalizados. Se quiser saber como definir um registo com eventos de estado personalizados, consulte também o artigo Configure eventos de estado personalizados.

Exemplo de registo estruturado

Por exemplo, suponhamos que quer um registo de tarefas que contenha as informações no objeto JSON seguinte, 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 deste objeto JSON resulta num registo 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 o seguinte:

  • MESSAGE: a mensagem, que é uma string que resume a finalidade do registo de tarefas. Por exemplo, The summary for a task log..
  • SEVERITY: a gravidade do registo, que pode usar como filtro quando visualiza os registos de uma tarefa. A gravidade tem de ser uma das enumerações LogSeverity convertidas numa string com apenas a primeira letra em 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 registo 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 registo 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.

Pode imprimir este exemplo de objeto JSON através de vários métodos. Por exemplo, os seguintes exemplos demonstram alguns dos métodos possíveis para imprimir o objeto JSON de exemplo:

  • Imprima uma string equivalente através do comando echo.

  • Imprima um dicionário equivalente através do Python.

comando echo

Para imprimir o objeto JSON de exemplo através do comando echo e de uma string equivalente, inclua o seguinte comando num ficheiro executável:

echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'

Por exemplo, suponhamos que cria e executa uma tarefa 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 registo 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 com Python e um dicionário equivalente, inclua o seguinte exemplo num ficheiro 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, suponhamos que cria e executa uma tarefa 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 registo 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: ...

O que se segue?