Analizzare un job utilizzando i log

Questo documento descrive come attivare, generare e visualizzare log da Cloud Logging per un job batch.

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

È importante notare che i log vengono generati solo dopo l'avvio di un job e solo se il logging è stato attivato per il job. Se devi analizzare un job senza log, visualizza gli eventi di stato.

Prima di iniziare

  1. Se non hai mai utilizzato Batch, consulta la guida introduttiva all'utilizzo di Batch e attivalo 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 saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Abilita il logging per un job

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

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

  • Se crei un job utilizzando l'interfaccia a riga di comando gcloud o l'API Batch, i log di Cloud Logging sono disattivati per impostazione predefinita. Per attivare 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 attivati per un job, Cloud Logging genera automaticamente tutti i log scritti per il job. Nello specifico, i job batch possono avere i seguenti tipi di log:

Visualizzare i log di un job

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

Console

Per visualizzare i log di un job utilizzando la console Google Cloud, segui questi passaggi:

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

    Vai all'elenco di 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:

gcloud

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

gcloud logging read "QUERY"

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

API

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

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

Sostituisci quanto segue:

Vai

Go

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Batch Go.

Per autenticarti a Batch, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 ulteriori informazioni, consulta la documentazione di riferimento dell'API Batch Java.

Per autenticarti a Batch, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 ulteriori informazioni, consulta la documentazione di riferimento dell'API Batch Python.

Per autenticarti a Batch, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 ulteriori informazioni, consulta la documentazione di riferimento dell'API Batch C++.

Per autenticarti a Batch, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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";
    }
  }

Filtra 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 recuperare l'UID di un job, visualizza i dettagli del job.

  • Per filtrare in base a un tipo specifico di log batch, specifica il tipo di log:

    logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE

    Sostituisci quanto segue:

    • PROJECT_ID: il ID progetto del progetto per cui 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 degli agenti.

  • 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 valore enumerato LogSeverity che descrive la gravità di un log, ad esempio ERROR.

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

Passaggi successivi