设置 Java 版 Stackdriver Logging

通过使用 Logback 附加器java.util.logging 处理程序,或者直接使用 Java 版 Stackdriver Logging 库,您可以从 Java 应用向 Stackdriver Logging 写入日志。

使用 Java 版 Stackdriver Logging 库无需安装 Stackdriver Logging 代理。

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 选择或创建 Google Cloud Platform 项目。

    转到“管理资源”页面

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

    了解如何启用结算功能

  4. 启用 Stackdriver Logging API。

    启用 API

适用于 Stackdriver Logging 的 Logback appender

借助 Logback 附加器,您可以将 Stackdriver Logging 与 SLF4J 日志记录表层搭配使用。

安装依赖项

如果您使用的是 Maven,请将以下代码添加到您的 pom.xml 文件中:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.79.0-alpha</version>
</dependency>
如果您使用的是 Gradle,请将以下代码添加到您的依赖项中:
compile 'com.google.cloud:google-cloud-logging-logback:0.79.0-alpha'
如果您使用的是 SBT,请将以下代码添加到您的依赖项中:
libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.79.0-alpha"

Logback 配置

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

您可以自定义最低严重级别阈值以及日志名称,也可以提供额外的 enhancer。以下是采用 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 配置为使用 Stackdriver Logging Logback appender 后,就可以使用 SLF4J 日志记录 API 重定向日志。下面这段代码展示如何在应用内使用 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 处理程序来使用 Stackdriver Logging API。

安装依赖项

如果您使用的是 Maven,请将以下代码添加到您的 pom.xml 文件中:
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>1.61.0</version>
</dependency>
如果您使用的是 Gradle,请将以下代码添加到您的依赖项中:
compile 'com.google.cloud:google-cloud-logging:1.61.0'
如果您使用的是 SBT,请将以下代码添加到您的依赖项中:
libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "1.61.0"

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

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

java.util.logging 配置

您可以通过编程方式或使用配置文件来添加日志记录处理程序。必须将配置文件路径作为系统属性提供给您的应用:-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 Stackdriver 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

示例

以下代码段展示如何使用 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 处理程序和适用于 Stackdriver Logging 的 Logback appender 的通用配置。

默认值

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

  • 日志名称:java.log

  • 要记录的最小阈值:INFO

  • Flush 严重级别:ERROR

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

受监控的资源检测

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

Logback appender 和 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");
  }
}

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

直接使用 Cloud 客户端库

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

在 Google Cloud Platform 上运行

要使用 Java 版 Stackdriver Logging 库,您需要具有 GCP 的 Cloud IAM Logs Writer 角色。大多数 GCP 环境默认提供此角色。

App Engine

App Engine 默认授予 Logs Writer 角色

无需明确提供凭据即可使用 Java 版 Stackdriver Logging 库。

系统会自动为 App Engine 应用启用 Stackdriver Logging。无需进行额外设置。

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

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

App Engine 柔性环境

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

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

通过在 app.yaml 中提供 logging.properties(如下所示),java.util.logging 处理程序可用于将日志直接记录到 Stackdriver 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

Google Kubernetes Engine 上,您必须在创建集群时添加 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 Platform Console 创建新实例时,您可以在创建实例面板的身份和 API 访问权限部分中执行此操作。请使用 Compute Engine 默认服务帐号或所选的其他服务帐号,并在身份和 API 访问权限部分中勾选允许所有 Cloud API 的全面访问权限。无论您选择哪个服务帐号,都请确保已在 GCP Console 的 IAM 和管理部分中向该服务帐号授予 Logs Writer 角色

在本地和其他位置运行

要在 GCP 外部使用 Java 版 Stackdriver Logging 库,您必须直接向 Java 版 Stackdriver Logging 库提供 GCP 项目 ID 和适当的服务帐号凭据。这适用于在您自己的工作站、您的数据中心的计算机或其他云提供商的虚拟机实例上运行该代理的情况。如需了解详情,请参阅手动获取和提供服务帐号凭据

查看日志

部署后,您可以在 GCP Console 日志查看器中查看日志。

转到“日志查看器”

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

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

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

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

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

  • 如果您在“日志查看器”中没有看到任何日志,要查看所有日志条目,请切换到高级过滤条件模式并使用空过滤条件。

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

    您可以检查各个条目以识别您的资源。

如需了解其他信息,请参阅查看日志高级日志过滤条件

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Stackdriver Logging
需要帮助?请访问我们的支持页面