Analisar um job usando registros

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

É possível usar registros para ter informações úteis para analisar seus jobs. 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 foi ativada para ele. Se você precisar analisar um job sem registros, confira os eventos de status.

Antes de começar

  1. Se você nunca usou o Batch, consulte Começar a usar o 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 por meio de papéis personalizados ou de outros papéis predefinidos.

Ativar a geração de registros de 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 console do Google Cloud , os registros do Cloud Logging vão estar sempre 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 de um job

Quando os registros do Cloud Logging são ativados para um job, o Cloud Logging gera automaticamente todos os 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 para que os executáveis de um job sejam gravados no stream de saída padrão (stdout) ou de erro padrão (stderr).

    Você pode gravar registros de tarefas para cada job que ativou a geração de registros.

Ver registros de um job

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

Console

Para conferir 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 lote mostra todos os registros associados ao job.

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

gcloud

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

gcloud logging read "QUERY"

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

API

Para conferir os 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 documentação de referência da API Batch Java.

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 de lote

É possível filtrar os registros em lote escrevendo uma consulta que inclua um ou mais dos parâmetros de filtro a seguir 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 acessar o UID de um job, confira os detalhes dele.

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