使用日志分析作业

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

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

请注意，只有在作业开始运行且为作业启用日志记录的情况下，系统才会生成日志。如果您需要分析不含日志的作业，请改为查看状态事件。

准备工作

如果您之前未使用过 Batch，请查看 Batch 使用入门，并在满足项目和用户的前提条件以启用 Batch。
如需获取使用日志分析作业所需的权限，请让管理员授予您以下 IAM 角色：
- 如需创建任务，请执行以下操作：
  - 项目的 Batch Job Editor (roles/batch.jobsEditor)
  - 对作业的服务帐号拥有的 Service Account User (roles/iam.serviceAccountUser)，默认为默认的 Compute Engine 服务帐号
- 如需查看日志，请执行以下操作：针对项目的日志查看器 (roles/logging.viewer)
如需详细了解如何授予角色，请参阅管理访问权限。

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

为作业启用日志记录功能

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

如果您使用 Google Cloud 控制台创建作业，来自 Cloud Logging 的日志将始终处于启用状态。
如果您使用 gcloud CLI 或 Batch API 创建作业，则 Cloud Logging 的日志默认处于停用状态。如需启用来自 Cloud Logging 的日志，请在创建作业时为 logsPolicy 字段添加以下配置：
```
{
    ...
    "logsPolicy": {
        "destination": "CLOUD_LOGGING"
    }
    ...
}
```

为作业写入和生成日志

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

代理日志 (batch_agent_logs)：Batch 服务代理中活动的日志。

Batch 会自动为每个启用了日志记录功能的作业写入代理日志。
任务日志 (batch_task_logs)：您已配置作业的可运行对象以写入标准输出 (stdout) 流或标准错误 (stderr) 流的任何数据的日志。

您可以选择为启用了日志记录的每个作业写入任务日志。

查看作业的日志

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

控制台

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

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

转到“作业”列表
在作业名称列中，点击作业的名称。系统会打开作业详情页面。
点击日志标签页。Batch 会显示与作业关联的所有日志。
可选：如需过滤日志，请执行以下任一操作：
- 在 过滤条件字段中输入过滤条件。
- 在 Severity（严重程度）列表中，选择一个 severity。
- 点击 在 Logs Explorer 中查看，使用批量过滤条件参数在 Logs Explorer 中构建查询。

gcloud

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

gcloud logging read "QUERY"

其中，QUERY 是针对包含批量过滤器参数的批处理日志的查询。

API

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

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

替换以下内容：

PROJECT_ID：您的项目 ID。
QUERY：包含批量过滤器参数的批处理日志的查询。

Go

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

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

import (
	"context"
	"fmt"
	"io"

	batch "cloud.google.com/go/batch/apiv1"
	"cloud.google.com/go/logging"
	"cloud.google.com/go/logging/logadmin"
	"google.golang.org/api/iterator"
	batchpb "google.golang.org/genproto/googleapis/cloud/batch/v1"
)

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

如需了解详情，请参阅 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

如需了解详情，请参阅 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++

如需了解详情，请参阅 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_task_logs 表示任务日志，batch_agent_logs 表示代理日志。
如需过滤包含自定义状态事件的日志，请指定日志必须定义 jsonPayload.batch/custom/event 字段：
```
jsonPayload.batch"/"custom"/"event!=NULL_VALUE
```
如需过滤一个或多个特定严重程度的日志，请指定以下比较项：
```
severityCOMPARISON_OPERATORSEVERITY_ENUM
```
替换以下内容：
- COMPARISON_OPERATOR：比较运算符，例如 >=。
- SEVERITY_ENUM：LogSeverity 枚举，用于描述日志的严重程度，例如 ERROR。

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

后续步骤

不妨详细了解问题排查。
详细了解 Cloud Logging。
了解如何写入任务日志。
了解如何删除和导出作业。