使用仪器库

在开发应用程序时，您可能会使用第三方库和框架来加速您的工作。如果您随后使用 OpenTelemetry instrumentation 您的应用程序，您可能希望避免花费额外的时间手动为您使用的第三方库和框架添加 traces、logs 和 metrics。

许多库和框架已经支持 OpenTelemetry，或者通过 OpenTelemetry instrumentation 进行支持，因此它们可以生成您可以导出到可观测性后端的 telemetry。

如果您正在 instrumentation 使用第三方库或框架的应用程序或服务，请遵循以下说明，了解如何为您的依赖项使用原生 instrumented 库和 instrumentation 库。

使用原生 instrumented 库

如果一个库默认包含 OpenTelemetry 支持，您可以通过在您的应用程序中添加和设置 OpenTelemetry SDK 来获取该库发出的 traces、metrics 和 logs。

该库可能需要一些额外的配置来进行 instrumentation。请参阅该库的文档以了解更多信息。

• Elasticsearch Ruby 客户端

使用检测库

如果某个库默认不包含 OpenTelemetry，您可以使用 检测库 来为某个库或框架生成遥测数据。

例如，如果您正在使用Rails并启用了opentelemetry-instrumentation-rails，您的Rails应用程序将自动为进入您控制器的请求生成遥测数据。

配置所有Instrumentation库

OpenTelemetry Ruby 提供了元软件包 opentelemetry-instrumentation-all，它将所有基于Ruby的Instrumentation库捆绑到一个单一的包中。这是以最小的努力为您的所有库添加遥测数据的便捷方式。

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

并在应用程序生命周期的早期对其进行配置。请参阅下面的使用Rails初始化器的示例

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.use_all() # enables all instrumentation!
end

这将安装所有Instrumentation库，并启用与您在应用程序中使用的库相匹配的库。

为特定的Instrumentation库覆盖配置

如果您启用了所有Instrumentation但想覆盖特定Instrumentation的配置，请在use_all中传递一个配置映射参数，其中键代表库，值是其特定的配置参数。

例如，以下是如何在应用程序中安装所有Instrumentation，但排除RedisInstrumentation的方法

require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  config = {'OpenTelemetry::Instrumentation::Redis' => { enabled: false }}
  c.use_all(config)
end

要覆盖更多Instrumentation，请在config映射中添加另一个条目。

使用环境变量为特定的Instrumentation库覆盖配置

您还可以使用环境变量禁用特定的Instrumentation库。由环境变量禁用的Instrumentation将优先于本地配置。环境变量的命名约定是库名，大写，其中::被替换为下划线，OPENTELEMETRY缩短为OTEL_LANG，并在末尾附加_ENABLED。

例如，OpenTelemetry::Instrumentation::Sinatra的环境变量名称是OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED。

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false

配置特定的Instrumentation库

如果您更喜欢有选择地安装和使用特定的Instrumentation库，也可以这样做。例如，以下是如何仅使用Sinatra和Faraday，并将Faraday配置为附加的配置参数。

首先，安装您想使用的特定Instrumentation库

gem install opentelemetry-instrumentation-sinatra
gem install opentelemetry-instrumentation-faraday

然后进行配置

require 'opentelemetry/sdk'

# install all compatible instrumentation with default configuration
OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::Sinatra'
  c.use 'OpenTelemetry::Instrumentation::Faraday', { opt: 'value' }
end

使用环境变量配置特定的Instrumentation库

您还可以使用环境变量为特定的Instrumentation库定义选项。按照约定，环境变量将是Instrumentation的名称，大写，其中::被替换为下划线，OPENTELEMETRY缩短为OTEL_{LANG}，并在末尾附加_CONFIG_OPTS。

例如，OpenTelemetry::Instrumentation::Faraday的环境变量名称是OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS。值为peer_service=new_service;span_kind=client将覆盖前面部分为Faraday设置的选项。

export OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS="peer_service=new_service;span_kind=client"

下表列出了根据选项数据类型可接受的值格式

下一步

Instrumentation库是生成大量关于您的Ruby应用程序的有用遥测数据的最简单方法。但它们不会生成特定于您应用程序逻辑的数据！要做到这一点，您需要用您自己的Instrumentation代码来丰富Instrumentation库中的Instrumentation。