Instrumenting

为了使系统可观察(observable)，必须对其进行仪表化(Instrumenting)。也就是说，代码必须发出traces, metrics,和 logs.。OpenTelemetry通过提供自动或手动检测应用程序的方法，方便了应用程序的检测。

OpenTelemetry的确切的安装机制因您所使用的开发语言而有所不同，但在下面的章节中也有一些相似之处。

Automatic Instrumentation(自动检测)

Add dependencies

为了启用自动检测，需要添加一个或多个依赖项。如何添加依赖项取决于语言。至少，这些依赖项将添加OpenTelemetry API和SDK功能。某些语言还需要每个检测依赖项。还可能需要导出器依赖项。有关OpenTelemetry API和SDK的更多信息，see the specification.

Configure OpenTelemetry Instrumentation

可以通过环境变量和可能的语言特定方式（如Java中的系统属性）进行配置。至少必须配置一个服务名称来标识要检测的服务。多种其他可用的配置选项，可能包括：

Data source specific configuration
Exporter configuration
Propagator configuration
Resource configuration

Manual Instrumentation

Import the OpenTelemetry API and SDK

您首先需要将OpenTelemetry引入到您的服务代码。如果您正在开发一个库或其他组件，该组件将由可运行的二进制文件使用，那么您只需要依赖API。如果您的工件是一个独立的过程或服务，那么您将依赖于API和SDK。有关OpenTelemetry API和SDK的更多信息，see the specification.

Configure the OpenTelemetry API

为了创建traces或者metrics，您需要首先创建跟踪程序和/或仪表提供程序。通常，我们建议SDK为这些对象提供一个默认提供程序。然后，您将从该提供程序获取一个跟踪程序或仪表实例，并为其提供名称和版本。您在这里选择的名称应该能准确地识别所检测的内容——例如，如果您正在编写一个库，那么您应该以您的库（即com.legalimatebusiness.myLibrary或其他唯一标识符）来命名它，因为这个名称将命名所产生的所有spans或metric events。还建议您提供与库或服务的当前版本相对应的版本字符串。

Configure the OpenTelemetry SDK

如果要构建服务流程，还需要为SDK配置适当的选项，以便将telemetry数据导出到某个分析后端。我们建议通过配置文件或其他机制以编程方式处理此配置。您还可以利用每种语言的调整选项。

Create Telemetry Data

一旦配置了API和SDK，您就可以通过从提供程序获得的跟踪(tracer)程序和仪表对象(meter objects)创建跟踪(traces)和度量事件(metric events)。您还可以利用插件或集成来为您创建跟踪和度量事件 —— 查看 registry 或您语言的存储库以了解有关这些的更多信息。

Export Data

一旦你创建了遥测(telemetry)数据，你就会想把它发送到某个地方。OpenTelemetry支持两种将数据从进程导出到分析后端的主要方法，可以直接从进程导出，也可以通过OpenTelemetry Collector进行代理。

进程中导出需要引入一个或多个导出器(exporters)，这些导出器是将OpenTelemetry的内存中的span和metric objects转换为Jaeger或Prometheus等遥测(telemetry)分析工具的适当格式的库。此外，OpenTelemetry支持称为OTLP的有线协议，所有OpenTelemetry SDK都支持该协议。此协议可用于将数据发送到OpenTelemetry Collector，这是一个独立的二进制进程，可以作为服务实例的代理或sidecar运行，也可以在单独的主机上运行。然后可以将收集器(Collector)配置为将这些数据转发并导出到您选择的分析工具。

除了Jaeger或Prometheus等开源工具外，越来越多的公司支持从OpenTelemetry获取遥测数据。Please see this page for more details.

Last modified November 16, 2022: Update first paragraph of Instrumenting page (#2023) (7e7b05a)

logo