【翻译】了解OpenTelemetry第4部分：用OpenTelemetry对Java应用程序进行测量

作者：Jack Berg 2021年9月22日

特邀文章，原载于New Relic博客，作者是New Relic的工程师Jack Berg

这篇博文是Understand OpenTelemetry系列的一部分。

第一部分概述了OpenTelemetry，并讨论了为什么它是仪器的未来。
第二部分探讨了OpenTelemetry开源项目的核心组件。
第三部分重点介绍了OpenTelemetry的主要数据源：跟踪、指标和日志。

现在，你对OpenTelemetry和核心概念有了很好的理解，你可以开始工作了在第四部分中，你可以探索用OpenTelemetry工具化的工作样本Java应用程序。

OpenTelemetry Java是OpenTelemetry在Java中的一个特定语言的实现。像所有语言一样，它有一个应用编程接口（API）和一个软件开发工具包（SDK），你可以在opentelemetry-java项目中看到。图书馆和应用程序的作者使用API来测量代码。SDK定义了API的实现。应用程序对其进行配置，以描述如何处理和输出生成的仪器数据。

此外，OpenTelemetry还有一个Java代理（opentelemetry-java-instrumentation），它类似于New Relic Java代理。当连接到一个应用程序时，它修改各种流行的库和框架的字节码以捕获遥测数据。这种更自动的仪表，通常被称为 "自动仪表 "选项，很受欢迎，因为只需稍作配置，就可以获得很多关于应用程序的有用信息。在自动仪表缺乏或不适合你的需求的情况下，你可以使用OpenTelemetry APIs来手动添加自定义仪表。

在这篇博文中，我们将介绍如何用OpenTelemetry Java项目（配置API和SDK）手动测量一个应用程序，以及如何用Java代理使用自动测量。我们将参考newrelic-opentelemetry-examplesGitHub仓库中的例子的源代码，其中包括与OpenTelemetry和New Relic相关的各种例子。

OpenTelemetry实例视频

下面的视频介绍了一个简单应用的例子，其中加入了一些使用OpenTelemetry Java API和SDK的定制。

今天就开始吧

• 查看OpenTelemetry快速入门指南。
• 查看New Relic的OpenTelemetry实例。
• 注册New Relic的本地OTLP摄取端点。

手动仪表

sdk-nr-config例子演示了通过OpenTelemetry API对OpenTelemetry Java进行手动检测，并通过OpenTelemetry SDK进行配置。Gradle用于构建，由于有多个例子在项目中共享代码，所以它是一个多项目构建。为了了解完整的情况，仔细看看:sdk-nr-config模块和根模块中的build.gradle文件。

根模块中的build.gradle文件对所有子项目的OpenTelemetry物料清单（BOM）采取平台依赖。BOM提供了一个方便的方法来保持OpenTelemetry组件的版本同步，允许你省略特定依赖的版本。

追踪API

通过为你正在检测的库建立一个跟踪器来设置自定义跟踪。从追踪器中，你可以建立跨度，并设置跨度上下文。设置跨度上下文可以确保在代码路径上设置的后续跨度有一个正确的父子关系。

一定要看一下跟踪语义约定，确保自定义跟踪工具遵循适用操作的既定约定。语义约定允许像New Relic这样的观察性平台以更有意义的方式解释数据，并提供更好的体验。

请参阅OpenTelemetry Java跟踪文档，了解概念的解释和更多实例。

衡量标准API

通过为被检测的库建立一个仪表来设置自定义指标。从一个仪表，你可以创建仪器。使用仪器来记录数据，并可选择关联描述数据记录环境的关键维度的属性。

像traces一样，有一组度量衡语义约定，描述了如何为常见的操作添加度量衡工具。请确保在适用的地方遵循这些规定。

参见OpenTelemetry Java Metrics文档，以获得对概念的解释和更多的例子。OpenTelemetry Metrics仍在进行中，所以这个例子的细节在未来几个月会有变化。

下面的视频介绍了如何设置OpenTelemetry跟踪器和计量器。

配置OpenTelemetry SDK

默认情况下，OpenTelemetry API会返回无操作实现的类，这意味着所有记录的数据都被简单地丢弃。配置OpenTelemetry SDK可以使数据以有用的方式被处理和输出。

请注意，OpenTelemetry APIs为初始化跟踪和度量仪器暴露了静态方法。正因为如此，你要在应用程序的生命周期中尽早配置SDK。否则，你就有可能在SDK实现之前初始化仪器。

更多信息请参见OpenTelemetry Java SDK配置文档。

下面的视频解释了为什么你需要在发送数据前配置Java SDK，并介绍了如何进行配置。

追踪配置

在配置OpenTelemetry SDK进行追踪时，请考虑以下信息。

• 资源定义了跟踪数据所关联的软件实体。
• 跨度限制可用于对与跨度相关的数据进行限制，包括属性、事件和链接的最大数量。
• 上下文传播（Context propagation）描述了对于分布式跟踪来说，跟踪状态是如何跨应用边界传播的。
• 采样决定了在追踪所有东西不现实的情况下如何决定捕获哪些追踪。
• 跨度处理器提供了一种钩住跨度开始和结束并执行任意逻辑的方法。
• 输出定义了如何将跟踪数据从应用程序中输出。

公制配置

当配置OpenTelemetry SDK的度量时，请考虑以下信息。

• 资源定义了度量数据所关联的软件实体。
• 视图允许你自定义度量数据的聚集方式，包括聚集类型（摘要、计数器、直方图）、聚集时间性（累积或三角洲）以及保留的属性。
• 导出定义了如何将指标数据从应用程序中导出。

由于OpenTelemetry Metrics仍然是一项正在进行中的工作，指标SDK配置的细节将在未来几个月内改变。

自动测量

agent-nr-config例子演示了通过OpenTelemetry Java代理进行的自动仪表。请看支持的库和框架的列表：Libraries / Frameworks。

要使用该代理，你通常使用以下工作流程。

1. 下载代理JAR文件。
2. 设置环境变量或系统属性以配置代理如何使用OpenTelemetry SDK。
3. 运行应用程序，在-javaagentJVM参数中引用代理jar的路径。

该示例项目通过Gradle构建中定义的任务来执行这些步骤。你需要调整它们以适应你的应用程序的构建和环境。

下面的视频展示了如何用Java代理运行OpenTelemetry。

现在你已经掌握了如何使用手动和自动仪表来检测你的Java应用程序，请关注我们的下一篇博客，在那里你将学习如何在本地设置一个收集器并将数据发送到后端平台进行可视化和分析。

接下来的步骤

• 查看OpenTelemetry快速入门指南。
• 查看New Relic的OpenTelemetry实例。
• 注册New Relic的免费层。
• 注册New Relic的本地OTLP摄取端点。
• 查看该系列的第五部分，将OpenTelemetry数据发送到您的后端平台。