Analizzare un job utilizzando i log

Questo documento descrive come abilitare, generare e visualizzare i log da Cloud Logging per un job Batch.

Puoi utilizzare i log per ottenere informazioni utili per l'analisi dei job. Ad esempio, i log possono aiutarti a eseguire il debug dei job non riusciti.

Importante: non puoi visualizzare i log di Cloud Logging dopo che sono stati eliminati, operazione che avviene automaticamente dopo il periodo di conservazione. Scopri di più sui periodi di conservazione dei log nella documentazione di Cloud Logging.

In particolare, i log vengono generati solo dopo l'avvio di un job e solo se il logging è stato abilitato per il job. Se devi analizzare un job senza log, visualizza gli eventi di stato invece.

Prima di iniziare

1. Se non hai mai utilizzato Batch, consulta la pagina Inizia a utilizzare Batch e abilita Batch completando i prerequisiti per progetti e utenti.

2. Per ottenere le autorizzazioni necessarie per analizzare un job utilizzando i log, chiedi all'amministratore di concederti i seguenti ruoli IAM:

   • Per creare un job:
     • Batch Job Editor (roles/batch.jobsEditor) sul progetto
     • Utente service account (roles/iam.serviceAccountUser) sul service account del job, che per impostazione predefinita è il service account predefinito di Compute Engine
   • Per visualizzare i log: Logs Viewer (roles/logging.viewer) sul progetto

   Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

   Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilitare il logging per un job

Per consentire la generazione dei log per un job, abilita i log di Cloud Logging quando crei il job:

• Se crei un job utilizzando la Google Cloud console, i log di Cloud Logging sono sempre abilitati.

• Se crei un job utilizzando gcloud CLI o l'API Batch, i log di Cloud Logging sono disabilitati per impostazione predefinita. Per abilitare i log di Cloud Logging, includi la seguente configurazione per il campo logsPolicy durante la creazione del job:

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

Scrivere e generare log per un job

Quando i log di Cloud Logging sono abilitati per un job, Cloud Logging genera automaticamente tutti i log scritti per il job. In particolare, i job Batch possono avere i seguenti tipi di log:

• Log dell'agente (batch_agent_logs): log delle attività del service agent Batch.

  Batch scrive automaticamente i log dell'agente per ogni job per cui è stato abilitato il logging.

• Log delle attività (batch_task_logs): log di tutti i dati che hai configurato per la scrittura degli eseguibili di un job nel flusso di output standard (stdout) o nel flusso di errore standard (stderr).

  Puoi scrivere facoltativamente i log delle attività per ogni job per cui è stato abilitato il logging.

Visualizzare i log di un job

Puoi visualizzare i log di un job utilizzando la Google Cloud console, gcloud CLI, l'API Logging, Go, Java, Python o C++.

Console

Per visualizzare i log di un job utilizzando la Google Cloud console:

1. Nella Google Cloud console, vai alla pagina Elenco job.

   Vai all'elenco dei job

2. Nella colonna Nome job, fai clic sul nome di un job. Viene visualizzata la pagina Dettagli job.

3. Fai clic sulla scheda Log. Batch mostra tutti i log associati al job.

4. (Facoltativo) Per filtrare i log, esegui una delle seguenti operazioni:

   • Inserisci un filtro nel  campo Filtro.

   • Nell'elenco Gravità, seleziona una gravità.

   • Fai clic su  Visualizza in Esplora log per creare una query in Esplora log utilizzando i parametri di filtro Batch.

gcloud

Per visualizzare i log utilizzando gcloud CLI, utilizza il gcloud logging read comando:

gcloud logging read "QUERY"

dove QUERY è una query per i log Batch che contiene i parametri di filtro Batch.

API

Per visualizzare i log utilizzando l'API Logging, utilizza il entries.list metodo:

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

Sostituisci quanto segue:

• PROJECT_ID: l' ID progetto del tuo progetto.
• QUERY: una query per i log Batch che contiene i parametri di filtro Batch.

Vai

Go

Per saperne di più, consulta la documentazione di riferimento dell'API GoBatch.

Per eseguire l'autenticazione in Batch, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Batch Java API.

Per eseguire l'autenticazione in Batch, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python Batch.

Per eseguire l'autenticazione in Batch, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell'C++ API Batch.

Per eseguire l'autenticazione in Batch, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

#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";
    }
  }

Filtrare i log Batch

Puoi filtrare i log Batch scrivendo una query che includa uno o più dei seguenti parametri di filtro e zero o più operatori booleani (AND, OR e NOT).

• Per filtrare i log di un job specifico, specifica l'ID univoco (UID) del job:

  labels.job_uid=JOB_UID
  

  dove JOB_UID è l'UID del job. Per ottenere l'UID di un job, visualizzane i dettagli.

• Per filtrare un tipo specifico di log Batch, specifica il tipo di log:

  logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE
  

  Sostituisci quanto segue:

  • PROJECT_ID: l' ID progetto del progetto per il quale vuoi visualizzare i log.
  • BATCH_LOG_TYPE: il tipo di log Batch che vuoi visualizzare, batch_task_logs per i log delle attività o batch_agent_logs per i log dell'agente.

• Per filtrare i log con eventi di stato personalizzati, specifica che il log deve definire il campo jsonPayload.batch/custom/event:

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

• Per filtrare i log di una o più gravità specifiche, specifica il seguente confronto:

  severityCOMPARISON_OPERATORSEVERITY_ENUM
  

  Sostituisci quanto segue:

  • COMPARISON_OPERATOR: un operatore di confronto, ad esempio >=.
  • SEVERITY_ENUM: un' LogSeverity enum, che descrive la gravità di un log, ad esempio ERROR.

Per ulteriori opzioni di filtro, consulta la documentazione del linguaggio di query di Cloud Logging.

Passaggi successivi

• Scopri di più sulla risoluzione dei problemi.
• Scopri di più su Cloud Logging.
• Scopri come scrivere i log delle attività.
• Scopri come esportare le informazioni sui job.
• Scopri come eliminare i job.