使用日志分析作业

本文档介绍了如何为批量作业启用、生成和查看 Cloud Logging中的日志 。

您可以使用日志获取有助于分析作业的信息。例如，日志可以帮助您调试失败的作业。

值得注意的是，日志仅在作业开始运行后生成，并且仅当为作业启用了日志记录时才会生成。 如果您需要在没有日志的情况下分析作业， 请改为查看状态事件。

准备工作

  1. 如果您之前未使用过 Batch，请查看 Batch 使用入门 ，并完成 项目和用户的前提条件以启用 Batch。

  2. 如需获得使用日志分析作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

为作业启用日志记录

如需允许为作业生成日志，请在创建作业时启用 Cloud Logging 中的日志：

  • 如果您使用 Google Cloud 控制台创建作业，则系统始终会启用 Cloud Logging 中的日志。

  • 如果您使用 gcloud CLI 或 Batch API 创建作业，则系统默认会停用 Cloud Logging 中的日志。如需启用 Cloud Logging 中的日志，请在创建作业时为 logsPolicy 字段添加以下配置：

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

为作业写入和生成日志

为作业启用 Cloud Logging 中的日志后，Cloud Logging 会自动生成为作业写入的任何日志。 具体而言，Batch 作业可以具有以下日志类型：

查看作业的日志

您可以使用 Google Cloud 控制台、 gcloud CLI、Logging API、Go、Java、Python 或 C++ 查看作业的日志。

控制台

如需使用 Google Cloud 控制台查看作业的日志，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往作业列表页面。

    前往作业列表

  2. 在作业名称 列中，点击作业的名称。 作业详情 页面随即打开。

  3. 点击日志 标签页。Batch 会显示与作业关联的所有日志。

  4. 可选：如需过滤日志，请执行以下任一操作：

gcloud

如需使用 gcloud CLI 查看日志，请使用 gcloud logging read 命令：

gcloud logging read "QUERY"

其中，QUERY 是包含 Batch 过滤条件参数的 Batch 日志查询。

API

如需使用 Logging API 查看日志，请使用 entries.list 方法：

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

替换以下内容：

Go

Go

如需了解详情，请参阅 Batch Go API 参考文档。

如需向 Batch 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅 为本地开发环境设置身份验证。 

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

如需了解详情，请参阅 Batch Java API 参考文档。

如需向 Batch 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅 为本地开发环境设置身份验证。 

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

如需了解详情，请参阅 Batch Python API 参考文档。

如需向 Batch 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅 为本地开发环境设置身份验证。 

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

如需了解详情，请参阅 Batch C++ API 参考文档。

如需向 Batch 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅 为本地开发环境设置身份验证。 

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

过滤 Batch 日志

您可以编写包含以下一个或多个过滤条件参数以及零个或多个 布尔运算符（AND、OR 和 NOT）的查询 ，以过滤 Batch 日志。

  • 如需过滤特定作业的日志，请指定作业的唯一 ID (UID)：

    labels.job_uid=JOB_UID

    其中，JOB_UID 是作业的 UID。如需获取作业的 UID，请查看作业的详细信息。

  • 如需过滤特定类型的 Batch 日志，请指定日志类型：

    logName=projects/PROJECT_ID/logs/BATCH_LOG_TYPE

    替换以下内容：

    • PROJECT_ID：您要查看日志的项目的 项目 ID 。
    • BATCH_LOG_TYPE：您要查看的 Batch 日志的类型，可以是任务日志的 batch_task_logs，也可以是代理日志的 batch_agent_logs。

  • 如需过滤具有 自定义状态事件的日志，请指定日志必须定义 jsonPayload.batch/custom/event 字段：

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

  • 如需过滤一个或多个特定严重程度的日志，请指定以下 比较：

    severityCOMPARISON_OPERATORSEVERITY_ENUM

    替换以下内容：

如需了解更多过滤条件选项，请参阅 Cloud Logging 查询语言文档。

后续步骤