diff --git a/website_docs/configuring_automatic_instrumentation.md b/website_docs/configuring_automatic_instrumentation.md new file mode 100644 index 0000000000..de52df4f16 --- /dev/null +++ b/website_docs/configuring_automatic_instrumentation.md @@ -0,0 +1,79 @@ +--- +title: Configuring automatic instrumentation +weight: 5 +--- + +Automatic instrumentation in ruby is done via instrumentation packages, and most commonly, the `opentelemetry-instrumentation-all` package. These are called Instrumentation Libraries. + +For example, if you are using Rails and enable instrumentation, your running Rails app will automatically generate telemetry data for inbound requests to your controllers. + +### Configuring all instrumentation libraries + +The recommended way to use instrumentation libraries is to use the `opentelemetry-instrumentation-all` package: + +```console +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: + +```ruby +# config/initializers/opentelemetry.rb +require 'opentelemetry/sdk' +require 'opentelemetry/exporter/otlp' +require 'opentelemetry/instrumentation/all' +OpenTelemetry::SDK.configure do |c| + c.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: + +```ruby +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. + +### 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 `Farady` being configured with an additional configuration parameter. + +First, install the specific instrumentation libraries you know you want to use: + +```console +gem install opentelemetry-instrumentation-sinatra +gem install opentelemetry-instrumentation-faraday +``` + +The configure them: + + +```ruby +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 +``` + +### 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 automatic instrumentation from instrumentation libraries with [manual instrumentation](manual_instrumentation). diff --git a/website_docs/getting_started.md b/website_docs/getting_started.md index a90fef63cc..6483a50ccc 100644 --- a/website_docs/getting_started.md +++ b/website_docs/getting_started.md @@ -25,7 +25,7 @@ gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-instrumentation-all' ``` -The inclusion of `opentelemetry-instrumentation-all` in the above list provides instrumentations for several frameworks such as Rails and Sinatra as well as database drivers and HTTP [libraries][auto-instrumentation]. +The inclusion of `opentelemetry-instrumentation-all` provides [instrumentations](auto-instrumentation) for Rails, Sinatra, several HTTP libraries, and more. ### Initialization @@ -46,6 +46,8 @@ OpenTelemetry::SDK.configure do |c| end ``` +The call `c.use_all()` enables all instrumentations in the `instrumentation/all` package. If you have more advanced configuration needs, see [configuring specific instrumentation libraries](configure-specific-libraries). + Now that you have setup your application to perform tracing, you'll need to configure the SDK to export the traces somewhere. Our example loaded the `OTLP` exporter, which the SDK tries to use by default. Next, we'll use the OpenTelemetry Collector to receive these traces and visualize them using Jaeger and Zipkin! ### Exporting Traces @@ -83,9 +85,13 @@ Adding tracing to a single service is a great first step and although auto-instr [Manual Instrumentation][manual-instrumentation] will give provide you the ability to enrich your traces with domain specific data. +[Automatic Instrumentation][auto-instrumentation] + + [repository]: https://github.com/open-telemetry/opentelemetry-ruby [auto-instrumentation]: https://github.com/open-telemetry/opentelemetry-ruby#instrumentation-libraries [sdk-env]: {{< relref "/docs/reference/specification/protocol/exporter#configuration-options" >}} [context-propagation]: ../context_propagation [events]: ../events [manual-instrumentation]: ../manual_instrumentation +[configure-specific-libraries](configuring_automatic_instrumentation#configuring-specific-instrumentation-libraries) \ No newline at end of file