Analisar um job usando registros

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

É possível usar registros para receber informações úteis para analisar seus jobs. Por exemplo, os registros podem ajudar a depurar jobs com falha.

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, consulte os eventos de status em vez disso.

Antes de começar

  1. Se você nunca usou o Batch, consulte Introdução ao Batch e ative o Batch concluindo os pré-requisitos para projetos e usuários.

  2. Para receber 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 com papéis personalizados ou outros papéis predefinidos.

Ativar a geração de registros para um job

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

  • Se você criar um job usando o Google Cloud console, os registros do Cloud Logging sempre serão ativados.

  • 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 a seguinte configuração para o campo logsPolicy ao criar o job:

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

Gravar e gerar registros para um job

Quando os registros do Cloud Logging estão ativados para um job, o Cloud Logging gera automaticamente todos os registros gravados para o job. Especificamente, os jobs do Batch podem ter os seguintes tipos de registro:

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

    O Batch grava automaticamente registros de agente para cada job que tem a geração de registros ativada.

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

    Você pode, opcionalmente, gravar registros de tarefas para cada job que tem a geração de registros ativada.

Ver registros de um job

É possível visualizar os registros de um job usando o Google Cloud console, a CLI gcloud, a API Logging, Go, Java, Python ou C++.

Console

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

  1. No Google Cloud console, 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 será aberta.

  3. Clique na guia Registros. O Batch mostra todos os registros associados ao job.

  4. Opcional: para filtrar os registros, faça o seguinte:

gcloud

Para visualizar registros usando a CLI gcloud, use o gcloud logging read comando:

gcloud logging read "QUERY"

em que QUERY é uma consulta para registros do Batch que contém parâmetros de filtro do Batch.

API

Para visualizar registros usando a API Logging, use o entries.list método:

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

Substitua:

Ir

Go

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

Para autenticar no Batch, configure o Application Default Credentials. Se quiser 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 Java Batch documentação de referência.

Para autenticar no Batch, configure o Application Default Credentials. Se quiser 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 APIPython Batch.

Para autenticar no Batch, configure o Application Default Credentials. Se quiser 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 C++Batch.

Para autenticar no Batch, configure o Application Default Credentials. Se quiser 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 do Batch escrevendo uma consulta que inclua um ou mais dos seguintes parâmetros de filtro e zero ou mais operadores booleanos (AND, OR e NOT).

  • Para filtrar 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, consulte os detalhes do job.

  • Para filtrar um tipo específico de registros do Batch, especifique o tipo de registro:

    logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE

    Substitua:

    • PROJECT_ID: o ID do projeto para o qual você quer visualizar os registros.
    • BATCH_LOG_TYPE: o tipo de registros do Batch que você quer visualizar, batch_task_logs para registros de tarefas ou batch_agent_logs para registros de agente.

  • 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 a 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