设置 Java 版 Cloud Logging

您可以使用 Logback 附加器java.util.logging handler,或者直接使用 Java 版 Cloud Logging 库,从 Java 应用向 Cloud Logging 写入日志。

无需安装 Cloud Logging 代理即可使用 Java 版 Cloud Logging 库。

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. 在 Google Cloud Console 中的项目选择器页面上,选择或创建一个 Google Cloud 项目

    转到“项目选择器”

  3. 确保您的 Google Cloud 项目已启用结算功能

  4. 启用 Cloud Logging API。

    启用 API

  5. 在 Google Cloud Console 中的项目选择器页面上,选择或创建一个 Google Cloud 项目

    转到“项目选择器”

  6. 确保您的 Google Cloud 项目已启用结算功能

  7. 启用 Cloud Logging API。

    启用 API

适用于 Cloud Logging 的 Logback 附加器

借助 Logback 附加器,您可以将 Cloud Logging 与 SLF4J 日志门面搭配使用。

安装依赖项

如果您使用的是 Maven,请将以下代码添加到您的 pom.xml 文件中。如需详细了解 BOM,请参阅 Google Cloud Platform 库 BOM

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.131.3-alpha</version>
</dependency>

如果您使用的是 Gradle,请将以下代码添加到您的依赖项中:

implementation 'com.google.cloud:google-cloud-logging-logback:0.131.3-alpha'

如果您使用的是 sbt,请将以下代码添加到您的依赖项中:

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.131.3-alpha"

Logback 配置

您可以通过编程方式或使用以 XML 或 Groovy 格式的脚本来配置 Logback。

您可以自定义最低严重级别阈值以及日志名称,也可以提供额外的增强器。以下是采用 XML 格式的 Logback 配置示例:

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
  </appender>

  <root level="info">
    <appender-ref ref="CLOUD" />
  </root>
</configuration>

示例

将 Logback 配置为使用 Cloud Logging Logback 附加器后,就可以使用 SLF4J 日志记录 API 重定向日志。如果您计划在本地或 Google Cloud 外部运行该示例,请提供 Google Cloud 配置。以下代码段展示如何在应用中使用 SLF4J 门面进行记录:


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Quickstart {
  private static final Logger logger = LoggerFactory.getLogger(Quickstart.class);

  public static void main(String[] args) {
    logger.info("Logging INFO with Logback");
    logger.error("Logging ERROR with Logback");
  }
}

java.util.logging 处理程序

您还可以借助默认的 Java Logging API 处理程序来使用 Cloud Logging API。

安装依赖项

如果您使用的是带有 BOM 的 Maven,请将以下代码添加到您的 pom.xml 文件中:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.34.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-logging</artifactId>
  </dependency>

  <!-- ...
</dependencies>

如果您使用的是不带 BOM 的 Maven,请将以下代码添加到您的依赖项中:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>3.16.1</version>
</dependency>

如果您使用的是 Gradle,请将以下代码添加到您的依赖项中:

implementation platform('com.google.cloud:libraries-bom:26.34.0')

implementation 'com.google.cloud:google-cloud-logging'

如果您使用的是 sbt,请将以下代码添加到您的依赖项中:

libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "3.16.1"

如果您使用的是 Visual Studio Code、IntelliJ 或 Eclipse,可以通过以下 IDE 插件将客户端库添加到您的项目中:

上述插件还提供其他功能,例如服务账号密钥管理。如需了解详情,请参阅各个插件相应的文档。

java.util.logging configuration

您可以通过编程方式或使用配置文件来添加日志记录处理程序。必须将配置文件路径作为系统属性提供给您的应用:-Djava.util.logging.config.file=/path/to/logging.properties

以下是一个配置文件示例:

# To use this configuration, add to system properties : -Djava.util.logging.config.file="/path/to/file"
#
.level = INFO

# it is recommended that io.grpc and sun.net logging level is kept at INFO level,
# as both these packages are used by Cloud internals and can result in verbose / initialization problems.
io.grpc.netty.level=INFO
sun.net.level=INFO

com.example.logging.jul.Quickstart.handlers=com.google.cloud.logging.LoggingHandler
# default : java.log
com.google.cloud.logging.LoggingHandler.log=custom_log

# default : INFO
com.google.cloud.logging.LoggingHandler.level=FINE

# default : ERROR
com.google.cloud.logging.LoggingHandler.flushLevel=ERROR

# default : auto-detected, fallback "global"
com.google.cloud.logging.LoggingHandler.resourceType=container

# custom formatter
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s

#optional enhancers (to add additional fields, labels)
com.google.cloud.logging.LoggingHandler.enhancers=com.example.logging.jul.enhancers.ExampleEnhancer

示例

如果您计划在本地或 Google Cloud 外部运行该示例,请提供 Google Cloud 配置。以下代码段展示如何使用 java.util.logging 记录日志:


import java.util.logging.Logger;

public class Quickstart {
  private static final Logger logger = Logger.getLogger(Quickstart.class.getName());

  public static void main(String[] args) {
    logger.info("Logging INFO with java.util.logging");
    logger.severe("Logging ERROR with java.util.logging");
  }
}

通用配置

以下各部分介绍 java.util.logging 处理程序和适用于 Cloud Logging 的 Logback 附加器的通用配置。

默认值

Logback 附加器和 java.util.logging 处理程序使用以下默认值来实例化 Cloud Logging 客户端:

  • 日志名称:java.log

  • 需要记录的最低阈值:INFO

  • Flush 严重级别:ERROR

Java 版 Cloud Logging 库会按大小和距上次写入的时间对消息进行批处理。系统会立即写出日志记录请求为 flush 严重级别或更高级别的批次。

受监控的资源检测

通过 Cloud Logging 库发送的所有日志均需要一个受监控的资源类型来标识您的应用。

Logback 附加器和 java.util.logging 处理程序会自动检测您的 App Engine、Compute Engine 和 Google Kubernetes Engine 应用的资源类型。

在其他环境中,一个受监控的 global 资源用作默认资源类型。

您可以将受监控的资源类型替换为 Logback 附加器配置java.util.logging 处理程序配置中的有效类型

其他字段和标签

借助 Logback 附加器和 java.util.logging 处理程序,您可以使用 LoggingEnhancer 实例添加或更新 LogEntry 对象的字段。

您必须按照 Logback 附加器配置java.util.logging 处理程序配置中的示例配置这些增强器:


import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.LoggingEnhancer;

// Add / update additional fields to the log entry
public class ExampleEnhancer implements LoggingEnhancer {

  @Override
  public void enhanceLogEntry(LogEntry.Builder logEntry) {
    // add additional labels
    logEntry.addLabel("test-label-1", "test-value-1");
  }
}

您的配置可能不支持使用自定义标签。例如,Dataflow 日志不包含这些标签。

如需详细了解如何安装,请参阅 Java 版 Cloud Logging 库的文档。您还可以使用问题跟踪器来报告问题。

使用 Cloud Logging 客户端库写入日志

如需了解如何直接使用 Java 版 Cloud Logging 客户端库,请参阅 Cloud Logging 客户端库

在 Google Cloud 上运行

如需让应用使用 Java 版 Cloud Logging 库写入日志,底层资源的服务帐号必须具有 Logs Writer (roles/logging.logWriter) IAM 角色。大多数 Google Cloud 环境都会自动将默认服务帐号配置为具有此角色。

App Engine

系统会自动为 App Engine 启用 Cloud Logging,并且应用的默认服务账号默认拥有 IAM 权限以写入日志条目。

App Engine 标准环境默认使用 java.util.logging.Logger API;这样可直接写入 Cloud Logging,并且易于配置。

如需了解详情,请参阅有关读取和编写应用日志的 App Engine 文档。

App Engine 柔性环境

App Engine 柔性环境中,java.util.logging 默认使用 ConsoleHandler,并且会将日志发送到 stdoutstderr

Jetty 运行时与 Java 版 Cloud Logging 库捆绑在一起。

通过在 app.yaml 中提供 logging.properties(如下所示),java.util.logging 处理程序可用于将日志直接记录到 Cloud Logging:

    env_variables:
      JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties

如果您使用的是 java.util.logging 处理程序或 Logback 附加器,则可以在 Jetty 运行时上使用跟踪 ID 日志记录功能。

在 App Engine 柔性环境中运行时,TraceLoggingEnhancer 实例会使用标签 trace_id 向每个日志条目添加线程安全的跟踪 ID。

Google Kubernetes Engine (GKE)

GKE 会自动向默认服务帐号授予 Logs Writer (roles/logging.logWriter) IAM 角色。如果您将 Workload Identity 与此默认服务帐号搭配使用,以便工作负载访问特定的 Google Cloud API,则无需进行其他配置。但是,如果您将 Workload Identity 与自定义 IAM 服务帐号搭配使用,请确保自定义服务帐号具有 Logs Writer (roles/logging.logWriter) 角色。

如果需要,您还可以在创建集群时使用以下命令添加 logging.write 访问权限范围:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

使用 Compute Engine 虚拟机实例时,请为每个实例添加 cloud-platform 访问权限范围。通过 Google Cloud 控制台创建新实例时,您可以在创建实例面板的身份和 API 访问权限部分执行此操作。请使用 Compute Engine 默认服务账号或您选用的其他服务账号,并在身份和 API 访问权限部分勾选允许所有 Cloud APIs 的全面访问权限。无论您选择哪个服务帐号,都请确保已在 Google Cloud 控制台的 IAM 和管理部分中向该服务帐号授予 Logs Writer 角色

在本地和其他位置运行

如需在 Google Cloud 之外使用 Java 版 Cloud Logging 库(包括在您自己的工作站、您数据中心的计算机或另一家云提供商的虚拟机实例上运行该库),您必须直接向 Java 版 Cloud Logging 库提供您的 Google Cloud 项目 ID 和相应的服务帐号凭据。

对于现有服务帐号,请执行以下操作:

  1. 向服务帐号授予 IAM Logs Writer (roles/logging.logWriter) IAM 角色。如需详细了解 IAM 角色,请参阅访问权限控制

  2. 设置应用默认凭据

如果您没有服务帐号,请创建一个。如需了解此过程,请参阅创建服务帐号

如需了解有关可用于身份验证的方法的一般信息,请参阅术语:服务帐号

查看日志

在 Google Cloud 控制台的导航面板中,选择 Logging,然后选择 Logs Explorer

前往 Logs Explorer

在日志浏览器中,您必须指定一个或多个资源,但资源的选择并不那么显而易见。以下是帮助您上手的一些提示:

  • 如果您将把应用部署到 App Engine 或者您使用的是 App Engine 专用的库,请将资源设置为 GAE 应用

  • 如果您将在 Compute Engine 上部署应用,请将资源设置为 GCE 虚拟机实例

  • 如果您要在 Google Kubernetes Engine 上部署应用,则集群的日志记录配置将确定日志条目的资源类型。如需详细了解旧版 Google Cloud Observability 和 Google Cloud Observability Kubernetes Monitoring 解决方案,以及这些选项如何影响资源类型,请参阅迁移到 Google Cloud Observability Kubernetes Monitoring

  • 如果您的应用直接使用 Cloud Logging API,则资源取决于该 API 和您的配置。例如,在您的应用中,您可以指定资源或使用默认资源。

  • 如果您在日志浏览器中没有看到任何日志,若要查看所有日志条目,请切换到高级查询模式并使用空查询。

    1. 如需切换到高级查询模式,请点击日志浏览器顶部的菜单 (&blacktriangledown;),然后选择转换为高级过滤条件
    2. 清除过滤条件框中显示的内容。
    3. 点击提交过滤条件

    您可以检查各个条目以找出您的资源。

如需了解详情,请参阅使用 Logs Explorer