Analisar um job usando registros

Este documento descreve como ativar, gerar e exibir registros do Cloud Logging para um job em lote.

É possível usar registros para conseguir informações úteis a análise dos seus trabalhos. Por exemplo, os registros podem ajudar a depurar jobs com falhas.

Os registros só são gerados depois que um job começa a ser executado e somente se a geração de registros estiver ativada para o job. Se você precisar analisar um job sem registros, confira os eventos de status.

Antes de começar

  1. Se você nunca usou o Batch antes, revise Introdução ao Batch e ativar o Batch. Para isso, conclua pré-requisitos para projetos e usuários.

  2. Para ter as permissões necessárias para analisar um job usando 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.

Como ativar a geração de registros para um job

Para permitir que registros sejam gerados para um job, ative os registros de Cloud Logging ao criar o job:

  • Se você criar um job usando o console do Google Cloud, os registros o Cloud Logging está sempre ativado.

  • Se você criar um job usando a CLI gcloud ou a API Batch, os registros do Cloud Logging serão desativados por padrão. Para ativar os registros do Cloud Logging, inclua o seguinte: no campo logsPolicy ao criar o job:

    {
    ...
    "logsPolicy": {
        "destination": "CLOUD_LOGGING"
    }
    ...
}

Gravar e gerar registros de um job

Quando os registros do Cloud Logging são ativados para um job, o Cloud Logging gera automaticamente qualquer um dos registros gravados para o job. Especificamente, os jobs em lote podem ter os seguintes tipos de registro:

  • registros do agente (batch_agent_logs): registros de atividades do agente de serviço do Batch.

    O lote grava automaticamente os registros do agente para todos os jobs que ativaram o registro.

  • registros de tarefas (batch_task_logs): registros de todos os dados que você configurou um aos executáveis do job para gravar stream de saída padrão (stdout) ou stream de erro padrão (stderr).

    É possível gravar registros de tarefas para cada job que tenha ativado a geração de registros.

Ver registros de um job

Para acessar os registros de um job, use o console do Google Cloud, a CLI gcloud, API Logging, Go, Java, Python ou C++.

Console

Para visualizar os registros de um job usando o console do Google Cloud, faça o seguinte:

  1. No console do Google Cloud, acesse a página Lista de jobs.

    Acessar a lista de jobs

  2. Na coluna Nome do job, clique no nome de um job. A página Detalhes do job é aberta.

  3. Clique na guia Registros. O Batch exibe todos os registros associados o job.

  4. Opcional: para filtrar os registros, siga um destes procedimentos:

gcloud

Para conferir os registros com a CLI gcloud, use o comando gcloud logging read:

gcloud logging read "QUERY"

em que QUERY é um para registros em lote que contenham Parâmetros de filtro em lote.

API

Para exibir registros usando a API Logging, use o Método entries.list:

POST https://logging.googleapis.com/v2/entries:list
{
    "resourceNames": [
        "projects/PROJECT_ID"
    ],
    "filter": "QUERY"
    "orderBy": "timestamp desc"
}

Substitua:

Go

Go

Para mais informações, consulte a documentação de referência da API Batch Go.

Para autenticar no Batch, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

import (
	"context"
	"fmt"
	"io"

	batch "cloud.google.com/go/batch/apiv1"
	"cloud.google.com/go/batch/apiv1/batchpb"
	"cloud.google.com/go/logging"
	"cloud.google.com/go/logging/logadmin"
	"google.golang.org/api/iterator"
)

// Retrieve the logs written by the given job to Cloud Logging
func printJobLogs(w io.Writer, projectID string, job *batchpb.Job) error {
	// projectID := "your_project_id"

	ctx := context.Background()
	batchClient, err := batch.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer batchClient.Close()

	adminClient, err := logadmin.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("Failed to create logadmin client: %w", err)
	}
	defer adminClient.Close()

	const name = "batch_task_logs"

	iter := adminClient.Entries(ctx,
		// Only get entries from the "batch_task_logs" log for the job with the given UID
		logadmin.Filter(fmt.Sprintf(`logName = "projects/%s/logs/%s" AND labels.job_uid=%s`, projectID, name, job.Uid)),
	)

	var entries []*logging.Entry

	for {
		logEntry, err := iter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("unable to fetch log entry: %w", err)
		}
		entries = append(entries, logEntry)
		fmt.Fprintf(w, "%s\n", logEntry.Payload)
	}

	fmt.Fprintf(w, "Successfully fetched %d log entries\n", len(entries))

	return nil
}

Java

Java

Para mais informações, consulte a API Batch Java documentação de referência.

Para autenticar no Batch, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

import com.google.cloud.batch.v1.Job;
import com.google.cloud.logging.v2.LoggingClient;
import com.google.logging.v2.ListLogEntriesRequest;
import com.google.logging.v2.LogEntry;
import java.io.IOException;

public class ReadJobLogs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project hosting the job.
    String projectId = "YOUR_PROJECT_ID";

    // The job which logs you want to print.
    Job job = Job.newBuilder().build();

    readJobLogs(projectId, job);
  }

  // Prints the log messages created by given job.
  public static void readJobLogs(String projectId, Job job) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `loggingClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (LoggingClient loggingClient = LoggingClient.create()) {

      ListLogEntriesRequest request = ListLogEntriesRequest.newBuilder()
          .addResourceNames(String.format("projects/%s", projectId))
          .setFilter(String.format("labels.job_uid=%s", job.getUid()))
          .build();

      for (LogEntry logEntry : loggingClient.listLogEntries(request).iterateAll()) {
        System.out.println(logEntry.getTextPayload());
      }
    }
  }
}

Python

Python

Para mais informações, consulte a documentação de referência da API Batch Python.

Para autenticar no Batch, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from __future__ import annotations

from typing import NoReturn

from google.cloud import batch_v1
from google.cloud import logging


def print_job_logs(project_id: str, job: batch_v1.Job) -> NoReturn:
    """
    Prints the log messages created by given job.

    Args:
        project_id: name of the project hosting the job.
        job: the job which logs you want to print.
    """
    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    log_client = logging.Client(project=project_id)
    logger = log_client.logger("batch_task_logs")

    for log_entry in logger.list_entries(filter_=f"labels.job_uid={job.uid}"):
        print(log_entry.payload)

C++

C++

Para mais informações, consulte a documentação de referência da API Batch C++.

Para autenticar no Batch, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

#include "google/cloud/batch/v1/batch_client.h"
#include "google/cloud/logging/v2/logging_service_v2_client.h"
#include "google/cloud/location.h"
#include "google/cloud/project.h"

  [](std::string const& project_id, std::string const& location_id,
     std::string const& job_id) {
    auto const project = google::cloud::Project(project_id);
    auto const location = google::cloud::Location(project, location_id);
    auto const name = location.FullName() + "/jobs/" + job_id;
    auto batch = google::cloud::batch_v1::BatchServiceClient(
        google::cloud::batch_v1::MakeBatchServiceConnection());
    auto job = batch.GetJob(name);
    if (!job) throw std::move(job).status();

    auto logging = google::cloud::logging_v2::LoggingServiceV2Client(
        google::cloud::logging_v2::MakeLoggingServiceV2Connection());
    auto const log_name = project.FullName() + "/logs/batch_task_logs";
    google::logging::v2::ListLogEntriesRequest request;
    request.mutable_resource_names()->Add(project.FullName());
    request.set_filter("logName=\"" + log_name +
                       "\" labels.job_uid=" + job->uid());
    for (auto l : logging.ListLogEntries(request)) {
      if (!l) throw std::move(l).status();
      std::cout << l->text_payload() << "\n";
    }
  }

Filtrar registros do Batch

É possível filtrar registros em lote escrevendo uma consulta inclua um ou mais dos seguintes parâmetros de filtro e zero ou mais operadores booleanos (AND, OR e NOT).

  • Para filtrar os registros de um job específico, especifique o ID exclusivo (UID) do job:

    labels.job_uid=JOB_UID

    em que JOB_UID é o UID do job. Para receber o UID de um job, ver os detalhes do job.

  • Para filtrar um tipo específico de registros em lote, especifique o tipo de registro:

    logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE

    Substitua:

    • PROJECT_ID: o ID do projeto do projeto em que você quer conferir os registros.
    • BATCH_LOG_TYPE: o tipo de registros em lote que você quer consultar, batch_task_logs para registros de tarefas ou batch_agent_logs para registros de agentes.

  • Para filtrar registros com eventos de status personalizados, especifique que o registro precisa definir o campo jsonPayload.batch/custom/event:

    jsonPayload.batch"/"custom"/"event!=NULL_VALUE

  • Para filtrar registros de uma ou mais gravidades específicas, especifique o seguinte: comparação:

    severityCOMPARISON_OPERATORSEVERITY_ENUM

    Substitua:

Para mais opções de filtro, consulte a documentação da Linguagem de consulta do Cloud Logging.

A seguir