diff --git a/website_docs/_index.md b/website_docs/_index.md deleted file mode 100644 index 5c4bfe6962..0000000000 --- a/website_docs/_index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Ruby -description: > - Ruby - A language-specific implementation of OpenTelemetry in Ruby. -aliases: [/ruby, /ruby/metrics, /ruby/tracing] -cascade: - github_repo: &repo https://github.com/open-telemetry/opentelemetry-ruby - github_subdir: website_docs - path_base_for_github_subdir: content/en/docs/instrumentation/ruby/ - github_project_repo: *repo -weight: 24 ---- - -{{% lang_instrumentation_index_head "ruby" /%}} - -## Who's using OpenTelemetry Ruby? - -OpenTelemetry Ruby is in use by a number of companies, including: - -- [Heroku](https://heroku.com) -- [GitHub](https://github.com/) -- [Fulcrum](https://www.fulcrumapp.com/) -- [Puppet](https://puppet.com/) -- [Shopify](https://shopify.com) -- [TableCheck](https://www.tablecheck.com/) - -If you would like to add your name to this list, please feel free to submit a pull request. - -## Further Reading - -- [OpenTelemetry for Ruby on GitHub][repository] -- [Ruby API Documentation][ruby-docs] -- [Examples][] - -[repository]: https://github.com/open-telemetry/opentelemetry-ruby -[ruby-docs]: https://open-telemetry.github.io/opentelemetry-ruby/ -[examples]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples diff --git a/website_docs/api.md b/website_docs/api.md deleted file mode 100644 index 2a7f168993..0000000000 --- a/website_docs/api.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: API reference -linkTitle: API -redirect: https://open-telemetry.github.io/opentelemetry-ruby/ -manualLinkTarget: _blank -_build: { render: link } -weight: 50 ---- \ No newline at end of file diff --git a/website_docs/automatic.md b/website_docs/automatic.md deleted file mode 100644 index d8560373f7..0000000000 --- a/website_docs/automatic.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Automatic instrumentation -linkTitle: Automatic -aliases: [/docs/instrumentation/ruby/configuring_automatic_instrumentation] -spelling: cSpell:ignore faraday sinatra -weight: 2 ---- - -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 `Faraday` 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). diff --git a/website_docs/examples.md b/website_docs/examples.md deleted file mode 100644 index 7454432842..0000000000 --- a/website_docs/examples.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Examples -redirect: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples -manualLinkTarget: _blank -_build: { render: link } -weight: 60 ---- \ No newline at end of file diff --git a/website_docs/getting-started.md b/website_docs/getting-started.md deleted file mode 100644 index add5f359c3..0000000000 --- a/website_docs/getting-started.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Getting Started -aliases: [/docs/instrumentation/ruby/getting_started] -weight: 1 ---- - -[OpenTelemetry for Ruby][repository] can be used to add automatic and manual instrumentation to your applications. -Automatic instrumentation is enabled by adding [instrumentation packages][auto]. -Manual instrumentation can be added using the [OpenTelemetry API][manual]. - -### Requirements - -These instructions will explain how to set up automatic and manual instrumentation for a Ruby service. -In order to follow along, you will need: - -- MRI Ruby >= `2.7`, jruby >= `9.3.2.0`, or truffleruby >= 22.1 -- Docker Compose - -> jruby only targets compatibility with MRI Ruby 2.6.8; which is EOL. This project does not officially support MRI Ruby 2.6.8, and provides jruby support on a best-effort basis until the jruby project supports compatibility with more modern Ruby runtimes. - -> truffleruby is tested, but support is best-effort at this time. - -### Installation - -The first step is to add these gems to your Gemfile: - -```ruby -gem 'opentelemetry-sdk' -gem 'opentelemetry-exporter-otlp' -gem 'opentelemetry-instrumentation-all' -``` - -The inclusion of `opentelemetry-instrumentation-all` provides [instrumentations][auto] for Rails, Sinatra, several HTTP libraries, and more. - -### Initialization - -The OpenTelemetry initialization needs to happen early in your application lifecycle. -For Rails applications, the usual way to initialize OpenTelemetry is in a Rails initializer. -For other Ruby services, perform this initialization as early as possible in the start-up process. - -OpenTelemetry initialization: - -```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 -``` - -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][config]. - -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 - -The following section assumes you are new to OpenTelemetry or do not currently use a vendor that supports distributed tracing using OTLP. Please refer to your vendor's product documentation if you would like to export your traces to a vendor for analysis and visualization. - -For the purposes of this tutorial you will configure an OpenTelemetry collector that will receive the traces and visualize them using Jaeger or Zipkin UI. - -First, start up an example system: - -```console -$ git clone git@github.com:open-telemetry/opentelemetry-ruby.git; \ - cd opentelemetry-ruby/examples/otel-collector; \ - docker-compose up -d -``` - -Next, you'll have to let the SDK know where the collector endpoint is to receive traces. -Set the [`OTEL_EXPORTER_OTLP_ENDPOINT`][sdk-env] environment variable to `http://0.0.0.0:4318`: - -```console -$ export OTEL_EXPORTER_OTLP_ENDPOINT=http://0.0.0.0:4318 -``` - -Now, start up your application and perform a few operations to generate tracing data, e.g. navigate around your web app or kick off background tasks. - -Lastly, open a browser and navigate to the [Jaeger UI](http://localhost:16686) or [Zipkin UI](http://localhost:9411) and search for traces related to your service, which were generated by the auto-instrumentation features of OpenTelemetry! - -### What next? - -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! - -- [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][] allow you to add a human-readable message on a span that - represents "something happening" during its lifetime. -- [Manual instrumentation][manual] will give provide you the ability to enrich - your traces with domain specific data. - -[auto]: https://github.com/open-telemetry/opentelemetry-ruby#instrumentation-libraries -[config]: {{< relref "automatic#configuring-specific-instrumentation-libraries" >}} -[Context propagation]: ../manual#context-propagation -[manual]: ../manual -[repository]: https://github.com/open-telemetry/opentelemetry-ruby -[sdk-env]: {{< relref "/docs/reference/specification/protocol/exporter#configuration-options" >}} -[Span events]: ../manual#span-events diff --git a/website_docs/manual.md b/website_docs/manual.md deleted file mode 100644 index bcedef93de..0000000000 --- a/website_docs/manual.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Manual Instrumentation -linkTitle: Manual -aliases: - - /docs/instrumentation/ruby/manual_instrumentation - - /docs/instrumentation/ruby/events - - /docs/instrumentation/ruby/context-propagation -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. -To do this, use the OpenTelemetry SDK to access the currently executing span and add attributes to it, and/or to create new spans. - -### Add information to the current span - -It's often beneficial to add information to the currently executing span in a trace. -For example, you may have an application or service that handles extended warranties, and you want to associate it with the span when querying your tracing datastore. -In order to do this, get the current span and set [attributes](#attributes) with your application's domain specific data: - -```ruby -def track_extended_warranty(extended_warranty) - current_span = OpenTelemetry::Trace.current_span - current_span.add_attributes({ - "com.extended_warranty.id" => extended_warranty.id, - "com.extended_warranty.timestamp" => extended_warranty.timestamp - }) -end -``` - -### Creating New Spans - -Auto-instrumentation can show the shape of requests to your system, but only you know the really important parts. -In order to get the full picture of what's happening, you will have to add manual instrumentation and create some custom spans. -To do this, grab the tracer from the OpenTelemetry API and generate a span: - -```ruby -# ... - -def search_by(query) - tracer = OpenTelemetry.tracer_provider.tracer('my-tracer') - tracer.in_span("search_by") do |span| - # ... expensive query - end -end -``` - -The `in_span` convenience method is unique to Ruby implementation, which reduces some of the boilerplate code that you would have to otherwise write yourself: - -```ruby -def search_by(query) - span = tracer.start_span("search_by", kind: :internal) - OpenTelemetry::Trace.with_span(span) do |span, context| - # ... expensive query - end -rescue Exception => e - span&.record_exception(e) - span&.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{e.class}") - raise e -ensure - span&.finish -end -``` - -### Attributes - -Attributes are keys and values that are applied as metadata to your spans and are useful for aggregating, filtering, and grouping traces. Attributes can be added at span creation, or at any other time during the lifecycle of a span before it has completed. - -```ruby -# setting attributes at creation... -tracer.in_span('foo', attributes: { "hello" => "world", "some.number" => 1024, "tags" => [ "bugs", "won't fix" ] }, kind: :internal) do |span| - - # ... and after creation - span.set_attribute("animals", ["elephant", "tiger"]) - - span.add_attributes({ "my.cool.attribute" => "a value", "my.first.name" => "Oscar" }) -end -``` - -> ⚠ Spans are thread safe data structures that require locks when they are mutated. -> You should therefore avoid calling `set_attribute` multiple times and instead assign attributes in bulk with a Hash, either during span creation or with `add_attributes` on an existing span. - -> ⚠ Sampling decisions happen at the moment of span creation. -> If your sampler considers span attributes when deciding to sample a span, then you _must_ pass those attributes as part of span creation. Any attributes added after creation will not be seen by the sampler, because the sampling decision has already been made. - -#### Semantic Attributes - -Semantic Attributes are attributes that are defined by the [OpenTelemetry Specification][] in order to provide a shared set of attribute keys across multiple languages, frameworks, and runtimes for common concepts like HTTP methods, status codes, user agents, and more. These attributes are available in the [Semantic Conventions gem][semconv-gem]. - -For details, see [Trace semantic conventions][semconv-spec]. - -### Span Events - -An event is a human-readable message on a span that represents "something happening" during it's lifetime. For example, imagine a function that requires exclusive access to a resource that is under a mutex. An event could be created at two points - once, when we try to gain access to the resource, and another when we acquire the mutex. - -```ruby -span.add_event("Acquiring lock") -if mutex.try_lock - span.add_event("Got lock, doing work...") - # some code here - span.add_event("Releasing lock") -else - span.add_event("Lock already in use") -end -``` - -A useful characteristic of events is that their timestamps are displayed as offsets from the beginning of the span, allowing you to easily see how much time elapsed between them. - -Events can also have attributes of their own e.g. - -```ruby -span.add_event("Cancelled wait due to external signal", attributes: { "pid" => 4328, "signal" => "SIGHUP" }) -``` - -## Context Propagation - -> 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][] - -This requires _context propagation_, a mechanism where identifiers for a trace are sent to remote processes. - -> ℹ The OpenTelemetry Ruby SDK will take care of context propagation as long as your service is leveraging auto-instrumented libraries. Please refer to the [README][auto-instrumentation] for more details. - -In order to propagate trace context over the wire, a propagator must be registered with the OpenTelemetry SDK. -The W3 TraceContext and Baggage propagators are configured by default. -Operators may override this value by setting `OTEL_PROPAGATORS` environment variable to a comma separated list of [propagators][propagators]. -For example, to add B3 propagation, set `OTEL_PROPAGATORS` to the complete list of propagation formats you wish to support: - -```sh -export OTEL_PROPAGATORS=tracecontext,baggage,b3 -``` - -Propagators other than `tracecontext` and `baggage` must be added as gem dependencies to your Gemfile, e.g.: - -```ruby -gem 'opentelemetry-propagator-b3' -``` - -[glossary]: /docs/concepts/glossary/ -[propagators]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/propagator -[auto-instrumentation]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation -[semconv-gem]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/semantic_conventions -[semconv-spec]: {{< relref "/docs/reference/specification/trace/semantic_conventions" >}} -[OpenTelemetry Specification]: {{< relref "/docs/reference/specification" >}}