Google Cloud 可为 Java 应用提供强大的监控、日志记录和诊断功能。
Java 客户端库经过插桩处理，可发出跟踪记录、指标和日志记录数据。插桩是选择性加入的，您需要明确启用它。本文档介绍了可用的信号以及如何启用这些信号。
可用信号
黄金信号包括以下遥测数据，这些数据遵循 OpenTelemetry 语义惯例：
- 跟踪记录： 低级别 HTTP/gRPC 跟踪记录，表示客户端库发出的网络请求。
- 指标： 客户端请求指标，用于跟踪延迟时间和请求速率。主要指标是
gcp.client.request.duration。 - 日志：
DEBUG级别的可操作错误日志，提供传输层中失败请求的详细信息，即使这些请求最终重试成功也是如此。
这些信号包括标准 OpenTelemetry 属性（例如
http.response.status_code 和 rpc.system.name）以及 Google Cloud特定于
的自定义属性，这些属性可能包括以下属性和类似属性：
gcp.client.service：服务名称（例如pubsub或storage）。gcp.client.repo：客户端库代码库（例如googleapis/google-cloud-java）。gcp.client.version：客户端库版本。gcp.client.artifact：特定模块路径（例如com.google.cloud:google-cloud-secretmanager）。gcp.resource.destination.id：正在操作的资源的 ID。gcp.errors.domain：可操作错误日志的错误网域。gcp.errors.metadata.<key>：失败请求的其他错误元数据键（扁平化）。
如需查看标准属性的完整列表，请参阅 OpenTelemetry HTTP 和 gRPC 语义惯例。
启用遥测
为保护敏感数据，遥测信号默认处于停用状态。您必须明确选择启用这些信号。
跟踪记录和指标
在生成的 Java 客户端库中，您必须以编程方式启用跟踪记录和指标，方法是在初始化期间向客户端的设置提供适当的跟踪器工厂：
- 跟踪记录： 使用
OpenTelemetryTracingFactory配置客户端。 - 指标： 使用
OpenTelemetryMetricsFactory配置客户端。 - 两者： 如果您想同时启用跟踪记录和指标，请使用封装这两个工厂的
CompositeTracerFactory配置客户端。
日志记录
可操作错误日志直接集成到核心 ApiTracer 框架中。如需在 Google Cloud
客户端库中全局启用可操作错误日志，请使用以下环境变量：
export GOOGLE_SDK_JAVA_LOGGING=true
跟踪上下文传播
Java 客户端库中的跟踪上下文传播需要明确启用跟踪记录。
启用跟踪记录生成（例如，通过配置 OpenTelemetryTracingFactory）后，如果您的应用在调用客户端库方法时在当前上下文中具有活跃的 OpenTelemetry span，则该库会使用它为出站请求提供跟踪上下文。这可确保您的应用级跟踪记录可以与后端服务日志和行为相关联。
导出遥测数据
在客户端库中启用遥测后，您必须将应用配置为收集此数据并将其导出到可观测性后端。
跟踪记录和指标
如需导出 Java 客户端库生成的跟踪记录和指标，请使用您首选的导出器（例如 OTLP）初始化 OpenTelemetry SDK，并在应用中设置全局文本映射传播器。
如需详细了解如何收集 OpenTelemetry 数据并将其导出到 Cloud Monitoring 或 Cloud Trace，请参阅选择插桩 方法。
日志记录
Java 客户端库使用标准日志记录框架，例如 SLF4J 和 java.util.logging。设置 GOOGLE_SDK_JAVA_LOGGING=true 后，系统会在 DEBUG 级别发出可操作错误日志。
如需将这些结构化日志路由到 Cloud Logging，请将日志记录框架（例如 Logback）配置为将 JSON 写入标准输出 (stdout)。如果您要部署到 Google Kubernetes Engine 或 Cloud Run 等环境，内置代理会自动抓取这些日志。
如需详细了解如何配置 Logback 或 java.util.logging 以
输出与 Cloud Logging 兼容的 JSON（包括跟踪记录关联），请参阅
为
Java 配置结构化日志记录。