Analyser une tâche à l'aide des journaux

Ce document explique comment activer, générer et afficher les journaux de Cloud Logging pour un job Batch.

Vous pouvez utiliser les journaux pour obtenir des informations utiles pour analyser vos jobs. Par exemple, les journaux peuvent vous aider à déboguer les tâches ayant échoué.

Notez que les journaux ne sont générés qu'après le démarrage d'une tâche et uniquement si la journalisation a été activée pour cette tâche. Si vous devez analyser un job sans journaux, affichez plutôt les événements d'état.

Avant de commencer

1. Si vous n'avez jamais utilisé Batch, consultez Premiers pas avec Batch et activez Batch en remplissant les conditions préalables pour les projets et les utilisateurs.

2. Pour obtenir les autorisations nécessaires pour analyser un job à l'aide des journaux, demandez à votre administrateur de vous accorder les rôles IAM suivants :

   • Pour créer un job :
     • Éditeur de tâches par lot (roles/batch.jobsEditor) sur le projet
     • Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service du job, qui est par défaut le compte de service Compute Engine par défaut
   • Pour afficher les journaux : Lecteur de journaux (roles/logging.viewer) sur le projet

   Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

   Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer la journalisation pour un job

Pour autoriser la génération de journaux pour un job, activez les journaux à partir de Cloud Logging lorsque vous créez le job :

• Si vous créez un job à l'aide de la console Google Cloud , les journaux de Cloud Logging sont toujours activés.

• Si vous créez un job à l'aide de gcloud CLI ou de l'API Batch, les journaux de Cloud Logging sont désactivés par défaut. Pour activer les journaux de Cloud Logging, incluez la configuration suivante pour le champ logsPolicy lors de la création du job :

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

Écrire et générer des journaux pour un job

Lorsque les journaux Cloud Logging sont activés pour un job, Cloud Logging génère automatiquement tous les journaux écrits pour le job. Plus précisément, les jobs par lot peuvent avoir les types de journaux suivants :

• Journaux de l'agent (batch_agent_logs) : journaux des activités de l'agent de service Batch.

  Batch écrit automatiquement les journaux d'agent pour chaque job dont la journalisation est activée.

• Journaux des tâches (batch_task_logs) : journaux de toutes les données pour lesquelles vous avez configuré les exécutables d'un job afin qu'ils écrivent dans le flux de sortie standard (stdout) ou le flux d'erreur standard (stderr).

  Vous pouvez éventuellement écrire des journaux de tâches pour chaque job pour lequel la journalisation est activée.

Afficher les journaux d'un job

Vous pouvez afficher les journaux d'un job à l'aide de la console Google Cloud , de gcloud CLI, de l'API Logging, de Go, de Java, de Python ou de C++.

gcloud logging read "QUERY"

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

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
}

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());
      }
    }
  }
}

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)

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

Filtrer les journaux de traitement par lot

Vous pouvez filtrer les journaux par lot en écrivant une requête qui inclut un ou plusieurs des paramètres de filtre suivants, ainsi que zéro ou plusieurs opérateurs booléens (AND, OR et NOT).

• Pour filtrer les journaux d'un job spécifique, indiquez son ID unique (UID) :

  labels.job_uid=JOB_UID
  

  où JOB_UID est l'UID du job. Pour obtenir l'UID d'un job, affichez ses détails.

• Pour filtrer un type spécifique de journaux par lots, spécifiez le type de journal :

  logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE
  

  Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet pour lequel vous souhaitez afficher les journaux.
  • BATCH_LOG_TYPE : type de journaux Batch que vous souhaitez afficher (batch_task_logs pour les journaux de tâches ou batch_agent_logs pour les journaux d'agent).

• Pour filtrer les journaux avec des événements d'état personnalisés, spécifiez que le journal doit définir le champ jsonPayload.batch/custom/event :

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

• Pour filtrer les journaux d'un ou de plusieurs niveaux de gravité spécifiques, spécifiez la comparaison suivante :

  severityCOMPARISON_OPERATORSEVERITY_ENUM
  

  Remplacez les éléments suivants :

  • COMPARISON_OPERATOR : opérateur de comparaison (par exemple, >=)
  • SEVERITY_ENUM : enum LogSeverity, qui décrit la gravité d'un journal (par exemple, ERROR).

Pour découvrir d'autres options de filtrage, consultez la documentation sur le langage de requête Cloud Logging.

Étapes suivantes

• En savoir plus sur le dépannage
• Apprenez-en plus sur Cloud Logging.
• Découvrez comment écrire des journaux de tâches.
• Découvrez comment exporter des informations sur les tâches.
• Découvrez comment supprimer des jobs.