Using instrumentation libraries

Ao desenvolver uma aplicação, é possível utilizar bibliotecas e frameworks de terceiros para acelerar seu trabalho. Caso você instrumente sua aplicação utilizando OpenTelemetry, talvez queira evitar gastar tempo adicional para adicionar manualmente rastros, logs e métricas às bibliotecas e frameworks de terceiros que utiliza.

Muitas bibliotecas e frameworks já oferecem suporte ao OpenTelemetry ou são compatíveis por meio da instrumentação, permitindo gerar dados de telemetria que podem ser exportados para um backend de observabilidade.

Caso você esteja instrumentando uma aplicação ou serviço que utilize bibliotecas ou frameworks de terceiros, siga estas instruções para aprender como usar bibliotecas instrumentadas nativamente e bibliotecas de instrumentação para as dependências do seu projeto.

Usar bibliotecas com instrumentação nativa

Se uma biblioteca oferece suporte ao OpenTelemetry por padrão, é possível obter rastros, métricas e logs emitidos por essa biblioteca ao adicionar e configurar o SDK do OpenTelemetry na sua aplicação.

A biblioteca pode exigir alguma configuração adicional para sua instrumentação. Consulte a documentação dessa biblioteca para saber mais.

• Elasticsearch Ruby Client

Use Instrumentation Libraries

If a library does not come with OpenTelemetry out of the box, you can use instrumentation libraries in order to generate telemetry data for a library or framework.

For example, if you are using Rails and enable opentelemetry-instrumentation-rails, your running Rails app will automatically generate telemetry data for inbound requests to your controllers.

Configuring all instrumentation libraries

OpenTelemetry Ruby provides the metapackage opentelemetry-instrumentation-all that bundles all ruby-based instrumentation libraries into a single package. It’s a convenient way to add telemetry for all your libraries with minimal effort:

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

and configure it early in your application lifecycle. See the example below using a Rails initializer:

# 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

This will install all instrumentation libraries and enable the ones that match up to libraries you’re using in your app.

Overriding configuration for specific instrumentation libraries

If you are enabling all instrumentation but want to override the configuration for a specific one, call use_all with a configuration map parameter, where the key represents the library, and the value is its specific configuration parameter.

For example, here’s how you can install all instrumentations except the Redis instrumentation into your app:

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

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

To override more instrumentation, add another entry in the config map.

Overriding configuration for specific instrumentation libraries with environment variables

You can also disable specific instrumentation libraries using environment variables. An instrumentation disabled by an environment variable takes precedence over local config. The convention for environment variable names is the library name, upcased with :: replaced by underscores, OPENTELEMETRY shortened to OTEL_LANG, and _ENABLED appended.

For example, the environment variable name for OpenTelemetry::Instrumentation::Sinatra is OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED.

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false

Configuring specific instrumentation libraries

If you prefer more selectively installing and using only specific instrumentation libraries, you can do that too. For example, here’s how to use only Sinatra and Faraday, with Faraday being configured with an additional configuration parameter.

First, install the specific instrumentation libraries you know you want to use:

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

Then configure them:

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

Configuring specific instrumentation libraries with environment variables

You can also define the option for specific instrumentation libraries using environment variables. By convention, the environment variable will be the name of the instrumentation, upcased with :: replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG}, and _CONFIG_OPTS appended.

For example, the environment variable name for OpenTelemetry::Instrumentation::Faraday is OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS. A value of peer_service=new_service;span_kind=client overrides the options set from previous section for Faraday.

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

The following table lists the acceptable format for values according to the option data type:

Next steps

Instrumentation libraries are the easiest way to generate lots of useful telemetry data about your Ruby apps. But they don’t generate data specific to your application’s logic! To do that, you’ll need to enrich the instrumentation from instrumentation libraries with your own instrumentation code.