From 77bb73c7756d34f846cfbb4eb4cccc3396593ffd Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Fri, 10 Dec 2021 00:21:23 +0000 Subject: [PATCH 1/6] Add autoinstrumentation docs + reorder some pages --- website_docs/automatic_instrumentation.md | 76 +++++++++++++++++++++++ website_docs/context_propagation.md | 2 +- website_docs/getting_started.md | 9 ++- website_docs/manual_instrumentation.md | 2 +- 4 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 website_docs/automatic_instrumentation.md diff --git a/website_docs/automatic_instrumentation.md b/website_docs/automatic_instrumentation.md new file mode 100644 index 0000000000..654675407f --- /dev/null +++ b/website_docs/automatic_instrumentation.md @@ -0,0 +1,76 @@ +--- +title: Automatic instrumentation +weight: 2 +--- + +Automatic instrumentation in ruby is done via instrumentation packages, and most commonly, the `opentelemetry-instrumentation-all` package. These are alled 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 simply 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 (for Rails apps, this would be in the 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. + +### 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 +``` + +### 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 parameter: + +```ruby +require 'opentelemetry/sdk' + +# install all compatible instrumentation with per instrumentation configuration overrides +OpenTelemetry::SDK.configure do |c| + c.use_all('OpenTelemetry::Instrumentation::SomeInstrumentation' => { opt: 'value' }) +end +``` + +This will configure all instrumentation libraries to be used with default values, and `SomeInstrumentation` configuration will be overridden with the value you provide. + +### 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.md) diff --git a/website_docs/context_propagation.md b/website_docs/context_propagation.md index e98282fa36..981e04c877 100644 --- a/website_docs/context_propagation.md +++ b/website_docs/context_propagation.md @@ -1,6 +1,6 @@ --- title: Context Propagation -weight: 2 +weight: 3 --- > Distributed Tracing tracks the progression of a single Request, called a Trace, as it is handled by Services that make up an Application. A Distributed Trace transverses process, network and security boundaries. [Glossary][] diff --git a/website_docs/getting_started.md b/website_docs/getting_started.md index a90fef63cc..a1a46a44fe 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](automatic_instrumentation.md) 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. To see how to configure this to be per-library, see [configuring specific instrumentation libraries](automatic_instrumentation.md#configuring-specific-instrumentation-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 @@ -77,11 +79,14 @@ Lastly, open a browser and navigate to the [Jaeger UI](http://localhost:16686) o Adding tracing to a single service is a great first step and although auto-instrumentation provides quite a bit of insight on its own, OpenTelemetry provides a few more features that will allow you gain even deeper insights! +[Automatic Instrumentation][manual-instrumentation] . + +[Manual Instrumentation][manual-instrumentation] will give provide you the ability to enrich your traces with domain specific data. + [Context Propagation][context-propagation] is perhaps one of the most powerful concepts in OpenTelemetry because it will upgrade your single service trace into a _distributed trace_, which makes it possible for OpenTelemetry vendors to visualize a request from end-to-end across process and network boundaries. [Span Events][events] allow you to add a human-readable message on a span that represents "something happening" during its lifetime. -[Manual Instrumentation][manual-instrumentation] will give provide you the ability to enrich your traces with domain specific data. [repository]: https://github.com/open-telemetry/opentelemetry-ruby [auto-instrumentation]: https://github.com/open-telemetry/opentelemetry-ruby#instrumentation-libraries diff --git a/website_docs/manual_instrumentation.md b/website_docs/manual_instrumentation.md index caa1980ff9..21fefd9969 100644 --- a/website_docs/manual_instrumentation.md +++ b/website_docs/manual_instrumentation.md @@ -1,6 +1,6 @@ --- title: "Manual Instrumentation" -weight: 4 +weight: 2 --- Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. From 6a44cd1e8bbe3a83d6936dc8931ddda839697467 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Fri, 10 Dec 2021 23:51:11 +0000 Subject: [PATCH 2/6] revert page weighting and make the page about configuration --- ...umentation.md => configuring_automatic_instrumentation.md} | 4 ++-- website_docs/context_propagation.md | 2 +- website_docs/getting_started.md | 2 +- website_docs/manual_instrumentation.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) rename website_docs/{automatic_instrumentation.md => configuring_automatic_instrumentation.md} (98%) diff --git a/website_docs/automatic_instrumentation.md b/website_docs/configuring_automatic_instrumentation.md similarity index 98% rename from website_docs/automatic_instrumentation.md rename to website_docs/configuring_automatic_instrumentation.md index 654675407f..cd852a9c6a 100644 --- a/website_docs/automatic_instrumentation.md +++ b/website_docs/configuring_automatic_instrumentation.md @@ -1,6 +1,6 @@ --- -title: Automatic instrumentation -weight: 2 +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 alled Instrumentation Libraries. diff --git a/website_docs/context_propagation.md b/website_docs/context_propagation.md index 981e04c877..e98282fa36 100644 --- a/website_docs/context_propagation.md +++ b/website_docs/context_propagation.md @@ -1,6 +1,6 @@ --- title: Context Propagation -weight: 3 +weight: 2 --- > Distributed Tracing tracks the progression of a single Request, called a Trace, as it is handled by Services that make up an Application. A Distributed Trace transverses process, network and security boundaries. [Glossary][] diff --git a/website_docs/getting_started.md b/website_docs/getting_started.md index a1a46a44fe..34b04bed73 100644 --- a/website_docs/getting_started.md +++ b/website_docs/getting_started.md @@ -46,7 +46,7 @@ OpenTelemetry::SDK.configure do |c| end ``` -The call `c.use_all()` enables all instrumentations in the `instrumentation/all` package. To see how to configure this to be per-library, see [configuring specific instrumentation libraries](automatic_instrumentation.md#configuring-specific-instrumentation-libraries). +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](configuring_automatic_instrumentation.md#configuring-specific-instrumentation-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! diff --git a/website_docs/manual_instrumentation.md b/website_docs/manual_instrumentation.md index 21fefd9969..caa1980ff9 100644 --- a/website_docs/manual_instrumentation.md +++ b/website_docs/manual_instrumentation.md @@ -1,6 +1,6 @@ --- title: "Manual Instrumentation" -weight: 2 +weight: 4 --- Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. From 802d4fd8099d015d35fbec4bf27db643f72f9fbb Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Fri, 10 Dec 2021 23:52:15 +0000 Subject: [PATCH 3/6] whoopsie --- website_docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website_docs/getting_started.md b/website_docs/getting_started.md index 34b04bed73..11e8b43cd9 100644 --- a/website_docs/getting_started.md +++ b/website_docs/getting_started.md @@ -79,7 +79,7 @@ Lastly, open a browser and navigate to the [Jaeger UI](http://localhost:16686) o Adding tracing to a single service is a great first step and although auto-instrumentation provides quite a bit of insight on its own, OpenTelemetry provides a few more features that will allow you gain even deeper insights! -[Automatic Instrumentation][manual-instrumentation] . +[Automatic Instrumentation][auto-instrumentation] . [Manual Instrumentation][manual-instrumentation] will give provide you the ability to enrich your traces with domain specific data. From c9cd0ee329941a83dc1c0501d71198cfeceb7ef1 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Sun, 12 Dec 2021 09:34:52 -0800 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Ariel Valentin --- website_docs/configuring_automatic_instrumentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website_docs/configuring_automatic_instrumentation.md b/website_docs/configuring_automatic_instrumentation.md index cd852a9c6a..21e86c27e8 100644 --- a/website_docs/configuring_automatic_instrumentation.md +++ b/website_docs/configuring_automatic_instrumentation.md @@ -3,13 +3,13 @@ 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 alled Instrumentation Libraries. +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 simply use the `opentelemetry-instrumentation-all` package: +The recommended way to use instrumentation libraries is to use the `opentelemetry-instrumentation-all` package: ```console gem 'opentelemetry-sdk' @@ -17,7 +17,7 @@ gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-instrumentation-all' ``` -and configure it early in your application lifecycle (for Rails apps, this would be in the Rails initializer): +and configure it early in your application lifecycle. See the example below using a Rails initializer: ```ruby # config/initializers/opentelemetry.rb From 24270853d4d1c56627bf80af5a455e014e37f616 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Sun, 12 Dec 2021 17:57:54 +0000 Subject: [PATCH 5/6] Changes as per review feedback --- .../configuring_automatic_instrumentation.md | 35 ++++++++++--------- website_docs/getting_started.md | 12 +++---- 2 files changed, 25 insertions(+), 22 deletions(-) diff --git a/website_docs/configuring_automatic_instrumentation.md b/website_docs/configuring_automatic_instrumentation.md index 21e86c27e8..9fd4c54455 100644 --- a/website_docs/configuring_automatic_instrumentation.md +++ b/website_docs/configuring_automatic_instrumentation.md @@ -32,6 +32,24 @@ 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. @@ -56,21 +74,6 @@ OpenTelemetry::SDK.configure do |c| end ``` -### 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 parameter: - -```ruby -require 'opentelemetry/sdk' - -# install all compatible instrumentation with per instrumentation configuration overrides -OpenTelemetry::SDK.configure do |c| - c.use_all('OpenTelemetry::Instrumentation::SomeInstrumentation' => { opt: 'value' }) -end -``` - -This will configure all instrumentation libraries to be used with default values, and `SomeInstrumentation` configuration will be overridden with the value you provide. - ### 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.md) +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 11e8b43cd9..ee74c06688 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` provides [instrumentations](automatic_instrumentation.md) for Rails, Sinatra, several HTTP libraries, and more. +The inclusion of `opentelemetry-instrumentation-all` provides [instrumentations](auto-instrumentation) for Rails, Sinatra, several HTTP libraries, and more. ### Initialization @@ -46,7 +46,7 @@ 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](configuring_automatic_instrumentation.md#configuring-specific-instrumentation-libraries). +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](configuring_automatic_instrumentation#configuring-specific-instrumentation-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! @@ -79,14 +79,14 @@ Lastly, open a browser and navigate to the [Jaeger UI](http://localhost:16686) o Adding tracing to a single service is a great first step and although auto-instrumentation provides quite a bit of insight on its own, OpenTelemetry provides a few more features that will allow you gain even deeper insights! -[Automatic Instrumentation][auto-instrumentation] . - -[Manual Instrumentation][manual-instrumentation] will give provide you the ability to enrich your traces with domain specific data. - [Context Propagation][context-propagation] is perhaps one of the most powerful concepts in OpenTelemetry because it will upgrade your single service trace into a _distributed trace_, which makes it possible for OpenTelemetry vendors to visualize a request from end-to-end across process and network boundaries. [Span Events][events] allow you to add a human-readable message on a span that represents "something happening" during its lifetime. +[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 From b375d617e22b77af8d95e2dac1121ce7372b225c Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 13 Dec 2021 21:58:39 +0000 Subject: [PATCH 6/6] link fixes --- website_docs/configuring_automatic_instrumentation.md | 2 +- website_docs/getting_started.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/website_docs/configuring_automatic_instrumentation.md b/website_docs/configuring_automatic_instrumentation.md index 9fd4c54455..de52df4f16 100644 --- a/website_docs/configuring_automatic_instrumentation.md +++ b/website_docs/configuring_automatic_instrumentation.md @@ -76,4 +76,4 @@ 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) +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 ee74c06688..6483a50ccc 100644 --- a/website_docs/getting_started.md +++ b/website_docs/getting_started.md @@ -46,7 +46,7 @@ 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](configuring_automatic_instrumentation#configuring-specific-instrumentation-libraries). +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! @@ -94,3 +94,4 @@ Adding tracing to a single service is a great first step and although auto-instr [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