本文档介绍如何使用开源 OpenTelemetry 框架修改 Java 应用以收集跟踪记录和指标数据,以及如何将结构化 JSON 日志写入标准输出。本文档还提供了您可以安装和运行的示例 Java Spring Boot 应用的相关信息。应用已配置为生成指标、跟踪记录和日志。无论您是否使用 Spring Boot 框架,步骤都是相同的。
如需详细了解插桩,请参阅以下文档:
手动和自动插桩简介
本文档中所述的插桩依赖 OpenTelemetry 自动插桩将遥测数据发送到您的 Google Cloud 项目。对于 Java,自动插桩是指将字节码动态注入库和框架以捕获遥测的做法。自动插桩可以收集入站和出站 HTTP 调用等的遥测数据。如需了解详情,请参阅 Java 自动插桩。
OpenTelemetry 还提供了一个 API,用于向您自己的代码添加自定义插桩。OpenTelemetry 将其称为手动插桩。本文档不介绍手动插桩。如需查看有关该主题的示例和信息,请参阅手动插桩。
准备工作
启用 Cloud Logging, Cloud Monitoring, and Cloud Trace API。
对应用进行插桩处理以收集跟踪记录、指标和日志
如需对应用进行插桩处理以收集跟踪记录和指标数据,并将结构化 JSON 写入标准输出,请执行以下步骤,如本文档后续部分所述:
将您的应用配置为使用 OpenTelemetry Java 代理
如需将应用配置为写入结构化日志并使用 OpenTelemetry 收集指标和轨迹数据,请更新应用的调用以使用 OpenTelemetry Java 代理。这种应用插桩方法称为自动插桩,因为它不需要修改应用代码。
以下代码示例演示了一个 Dockerfile,用于下载 OpenTelemetry Java 代理 JAR 文件并更新命令行调用以传递 -javaagent
标志。
如需查看完整示例,请点击 more_vert 更多,然后选择在 GitHub 上查看。
或者,您还可以在 JAVA_TOOL_OPTIONS
环境变量中设置 -javaagent
标志:
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
配置 OpenTelemetry
OpenTelemetry Java 代理的默认配置使用 OTLP 协议导出跟踪记录和指标。此外,它还会将 OpenTelemetry 配置为使用 W3C 跟踪上下文格式来传播跟踪上下文。此配置可确保 span 在跟踪记录中具有正确的父子关系。
如需了解详情和配置选项,请参阅 OpenTelemetry Java 自动插桩。
配置结构化日志记录
如需在写入标准输出的 JSON 格式日志中包含跟踪记录信息,请将应用配置为输出 JSON 格式的结构化日志。我们建议您使用 Log4j2 作为日志记录实现。以下代码示例展示了配置为使用 JSON 模板布局输出 JSON 结构化日志的 log4j2.xml
文件:
上述配置会从 SLF4J 的映射诊断上下文中提取有关活跃 span 的信息,并将该信息作为属性添加到日志中。然后,您可以使用这些属性将日志与跟踪记录相关联:
logging.googleapis.com/trace
:与日志条目关联的跟踪记录的资源名称。logging.googleapis.com/spanId
:与日志条目关联的跟踪记录的 span ID。logging.googleapis.com/trace_sampled
:此字段的值必须是true
或false
。
如需详细了解这些字段,请参阅 LogEntry
结构。
写入结构化日志
如需写入链接到跟踪记录的结构化日志,请使用 SLF4J Logging API。例如,以下语句展示了如何调用 Logger.info()
方法:
logger.info("handle /multi request with subRequests={}", subRequests);
OpenTelemetry Java 代理使用 OpenTelemetry 上下文中当前活跃 span 的 span 上下文自动填充 SLF4J 的映射诊断上下文。然后,映射的诊断上下文将包含到 JSON 日志中,如配置结构化日志记录中所述。
运行配置为收集遥测数据的示例应用
示例应用使用不受制于供应商的格式,包括 JSON(用于日志)和 OTLP(用于指标和跟踪记录)以及 Spring Boot 框架。为了将遥测数据路由到 Google Cloud,此示例使用配置了 Google 导出器的 OpenTelemetry Collector
。该应用有两个端点:
/multi
端点由handleMulti
函数处理。该应用中的负载生成器会向/multi
端点发出请求。此端点收到请求时,它会向本地服务器上的/single
端点发送 3 到 7 个请求。/single
端点由handleSingle
函数处理。当此端点收到请求时,它会休眠一小段延迟时间,然后以字符串进行响应。
下载并部署应用
如需运行示例,请执行以下操作:
-
在 Google Cloud 控制台中,激活 Cloud Shell。
Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动,并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
克隆代码库:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
转到示例目录:
cd opentelemetry-operations-java/examples/instrumentation-quickstart
构建并运行示例:
docker compose up --abort-on-container-exit
如果您未在 Cloud Shell 上运行,请使用指向凭据文件的
GOOGLE_APPLICATION_CREDENTIALS
环境变量运行应用。应用默认凭据提供了一个凭据文件 ($HOME/.config/gcloud/application_default_credentials.json
)。# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
查看指标
示例应用中的 OpenTelemetry 插桩生成 Prometheus 指标,您可以使用 Metrics Explorer 查看这些指标:
Prometheus/http_server_duration_milliseconds/histogram
会记录服务器请求的持续时间,并将结果存储在直方图中。Prometheus/http_client_duration_milliseconds/histogram
会记录客户端请求的持续时间,并将结果存储在直方图中。
-
在 Google Cloud 控制台中,转到 leaderboard Metrics Explorer 页面:
如果您使用搜索栏查找此页面,请选择子标题为监控的结果。
- 在指标元素中,展开选择指标菜单,在过滤栏中输入
http_server
,然后使用子菜单选择一个特定资源类型和指标:- 在活跃资源菜单中,选择 Prometheus 目标。
- 在活跃指标类别菜单中,选择 HTTP。
- 在活跃指标菜单中,选择指标。
- 点击应用。
- 配置数据的查看方式。
如果指标的测量结果是累积的,则 Metrics Explorer 会自动按校准时间段对测量数据进行归一化,从而使图表显示速率。如需了解详情,请参阅种类、类型和转换。
测量整数或双精度值时(例如使用两个
counter
指标),Metrics Explorer 会自动对所有时序求和。如需查看/multi
和/single
HTTP 路由的数据,请将聚合条目的第一个菜单设置为无。如需详细了解如何配置图表,请参阅使用 Metrics Explorer 时选择指标。
查看跟踪记录
如需查看跟踪记录数据,请执行以下操作:
-
在 Google Cloud 控制台中,转到 Trace 探索器页面:
您也可以使用搜索栏查找此页面。
- 在散点图中,选择 URI 为
/multi
的跟踪记录。 在跟踪记录详情面板的甘特图中,选择标记为
/multi
的 span。此时会打开一个面板,其中显示 HTTP 请求的相关信息。这些详细信息包括方法、状态代码、字节数以及调用方的用户代理。
如需查看与此跟踪记录关联的日志,请选择日志和事件标签页。
该标签页会显示各个日志。如需查看日志条目的详细信息,请展开日志条目。您还可以点击查看日志,并使用 Logs Explorer 查看日志。
如需详细了解如何使用 Cloud Trace 探索器,请参阅查找和探索跟踪记录。
查看日志
在 Logs Explorer 中,您可以检查日志,还可以查看关联的跟踪记录(如果存在)。
-
在 Google Cloud 控制台中,转到 Logs Explorer 页面。
如果您使用搜索栏查找此页面,请选择子标题为 Logging 的结果。
找到具有
handle /multi request
说明的日志。如需查看日志的详细信息,请展开日志条目。
点击包含“处理/多请求”消息的日志条目中的 跟踪记录,然后选择查看跟踪记录详情。
跟踪记录详情面板随即会打开并显示所选跟踪记录。
如需详细了解如何使用 Logs Explorer,请参阅使用 Logs Explorer 查看日志。