diff --git a/content/en/docs/instrumentation/python/getting-started.md b/content/en/docs/instrumentation/python/getting-started.md index 856db365d7f2..59df5544437a 100644 --- a/content/en/docs/instrumentation/python/getting-started.md +++ b/content/en/docs/instrumentation/python/getting-started.md @@ -51,7 +51,7 @@ Create a file `app.py` and add the following code to it: ```python from random import randint -from flask import Flask, request +from flask import Flask app = Flask(__name__) @@ -274,7 +274,7 @@ create a trace that's a child of the one that's automatically generated: from opentelemetry import trace from random import randint -from flask import Flask, request +from flask import Flask # Acquire a tracer tracer = trace.get_tracer("diceroller.tracer") @@ -400,7 +400,7 @@ from opentelemetry import trace from opentelemetry import metrics from random import randint -from flask import Flask, request +from flask import Flask tracer = trace.get_tracer("diceroller.tracer") # Acquire a meter. diff --git a/content/en/docs/instrumentation/ruby/exporters.md b/content/en/docs/instrumentation/ruby/exporters.md new file mode 100644 index 000000000000..d6436e7e42a2 --- /dev/null +++ b/content/en/docs/instrumentation/ruby/exporters.md @@ -0,0 +1,125 @@ +--- +title: Exporters +weight: 5 +spelling: cSpell:ignore Zipkin jaegertracing openzipkin zipkin +--- + +In order to visualize and analyze your traces, you will need to export them to a +backend such as [Jaeger](https://www.jaegertracing.io/) or +[Zipkin](https://zipkin.io/). OpenTelemetry Ruby provides exporters for some +common open source backends. + +Below you will find some introductions on how to set up backends and the +matching exporters. + +## OTLP endpoint + +To send trace data to a OTLP endpoint (like the [collector](/docs/collector) or +Jaeger) you'll want to use an exporter package, such as +`opentelemetry-exporter-otlp`: + +{{< tabpane lang=shell persistLang=false >}} + +{{< tab bundler >}} bundle add opentelemetry-exporter-otlp {{< /tab >}} + +{{< tab gem >}} gem install opentelemetry-exporter-otlp {{< /tab >}} + +{{< /tabpane>}} + +Next, configure the exporter to point at an OTLP endpoint. For example you can +update `config/initializers/opentelemetry.rb` from the +[Getting Started](../getting-started/) by adding +`require 'opentelemetry-exporter-otlp'` to the code: + +```ruby +# config/initializers/opentelemetry.rb +require 'opentelemetry/sdk' +require 'opentelemetry/instrumentation/all' +require 'opentelemetry-exporter-otlp' +OpenTelemetry::SDK.configure do |c| + c.service_name = 'dice-ruby' + c.use_all() # enables all instrumentation! +end +``` + +If you now run your application it will use OTLP to export traces: + +```sh +rails server -p 8080 +``` + +By default traces are sent to an OTLP endpoint listening on localhost:4318. You +can change the endpoint by setting the `OTEL_EXPORTER_OTLP_ENDPOINT` +accordingly: + +```sh +env OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces" rails server -p 8080 +``` + +To try out the OTLP exporter quickly and see your traces visualized at the +receiving end, you can run Jaeger in a docker container: + +```shell +docker run -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ + -e COLLECTOR_OTLP_ENABLED=true \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 4317:4317 \ + -p 4318:4318 \ + -p 14250:14250 \ + -p 14268:14268 \ + -p 14269:14269 \ + -p 9411:9411 \ + jaegertracing/all-in-one:latest +``` + +## Zipkin + +To set up Zipkin as quickly as possible, run it in a docker container: + +```shell +docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin +``` + +Install the exporter package as a dependency for your application: + +{{< tabpane lang=shell persistLang=false >}} + +{{< tab bundle >}} bundle add opentelemetry-exporter-zipkin {{< /tab >}} + +{{< tab gem >}} gem install opentelemetry-exporter-zipkin {{< /tab >}} + +{{< /tabpane>}} + +Update your OpenTelemetry configuration to use the exporter and to send data to +your Zipkin backend: + +```ruby +# config/initializers/opentelemetry.rb +require 'opentelemetry/sdk' +require 'opentelemetry/instrumentation/all' + +require 'opentelemetry-exporter-zipkin' +OpenTelemetry::SDK.configure do |c| + c.service_name = 'dice-ruby' + c.use_all() # enables all instrumentation! +end +``` + +If you now run your application, set the environment variable +`OTEL_TRACES_EXPORTER` to zipkin: + +```sh +env OTEL_TRACES_EXPORTER=zipkin rails server +``` + +By default traces are sent to a Zipkin endpoint listening on port +localhost:9411. You can change the endpoint by setting the +`OTEL_EXPORTER_ZIPKIN_ENDPOINT` accordingly: + +```sh +env OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:9411" rails server +``` diff --git a/content/en/docs/instrumentation/ruby/getting-started.md b/content/en/docs/instrumentation/ruby/getting-started.md index dfa3e40d6f12..9aa2cf1e663b 100644 --- a/content/en/docs/instrumentation/ruby/getting-started.md +++ b/content/en/docs/instrumentation/ruby/getting-started.md @@ -1,58 +1,122 @@ --- title: Getting Started +description: Get telemetry from your app in less than 5 minutes! aliases: [/docs/instrumentation/ruby/getting_started] +spelling: cSpell:ignore truffleruby sinatra rolldice struct darwin Tracestate +spelling: cSpell:ignore tracestate 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]. +This page will show you how to get started with OpenTelemetry in Ruby. -### Requirements +You will learn how you can instrument a simple application automatically, in +such a way that [traces][], [metrics][] and [logs][] are emitted to the console. -These instructions will explain how to set up automatic and manual -instrumentation for a Ruby service. In order to follow along, you will need: +## Prerequisites + +Ensure that you have the following installed locally: - MRI Ruby >= `3.0`, jruby >= `9.3.2.0`, or truffleruby >= 22.1 -- Docker Compose +- [Bundler](https://bundler.io/) + +{{% alert title="Warning" color="warning" %}} `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. + +While tested, support for `truffleruby` is on a best-effort basis at this time. +{{% /alert %}} + +## Example Application + +The following example uses a basic [Rails](https://rubyonrails.org/) +application. If you are not using Sinatra, that's ok — you can use OpenTelemetry +Ruby with other web frameworks as well, such as Sinatra and Rack. For a complete +list of libraries for supported frameworks, see the +[registry](/ecosystem/registry/?component=instrumentation&language=ruby). + +For more elaborate examples, see +[examples](/docs/instrumentation/ruby/examples/). + +### Dependencies + +To begin, install rails: + +```sh +gem install rails +``` + +### Create the application + +Create a new api-only application called `dice-ruby` and change into the newly +created folder `dice-ruby` + +```sh +rails new --api dice-ruby +cd dice-ruby +``` + +Create a controller for rolling a dice: + +```sh +rails generate controller dice +``` + +This will create a file called `app/controllers/dice_controller.rb`. Open that +file in your preferred editor and update it with the following code: -> 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. +```ruby +class DiceController < ApplicationController + def roll + render json: (rand(6) + 1).to_s + end +end +``` -### Installation +Next, open the `config/routes.rb` file and add the following code: -The first step is to add these gems to your Gemfile: +```ruby +Rails.application.routes.draw do + get 'rolldice', to: 'dice#roll' +end +``` + +Run the application with the following command and open + in your web browser to ensure it is working. ```sh -gem 'opentelemetry-sdk' -gem 'opentelemetry-exporter-otlp' -gem 'opentelemetry-instrumentation-all' +rails server -p 8080 +``` + +If everything works fine you should see a number between 1 and 6 returned to +you. You can now stop the application and instrument it using OpenTelemetry. + +### Instrumentation + +Install the `opentelemetry-sdk` and `opentelemetry-instrumentation-all` +packages: + +```sh +bundle add opentelemetry-sdk 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. +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: +Create a file named `config/initializers/opentelemetry.rb` with the following +code: ```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.service_name = 'dice-ruby' c.use_all() # enables all instrumentation! end ``` @@ -61,52 +125,65 @@ 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. +### Run the instrumented app -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: +You can now run your instrumented app and have it print to the console for now: ```sh -git clone git@github.com:open-telemetry/opentelemetry-ruby.git; \ - cd opentelemetry-ruby/examples/otel-collector; \ - docker-compose up -d +env OTEL_TRACES_EXPORTER=console rails server -p 8080 ``` -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`: +Open in your web browser and reload the page a +few times. You should see the spans printed in the console, such as the +following: -```sh -export OTEL_EXPORTER_OTLP_ENDPOINT=http://0.0.0.0:4318 +```ruby +#, + parent_span_id="\x00\x00\x00\x00\x00\x00\x00\x00", + total_recorded_attributes=8, + total_recorded_events=0, + total_recorded_links=0, + start_timestamp=1683555544407294000, + end_timestamp=1683555544464308000, + attributes= + {"http.method"=>"GET", + "http.host"=>"localhost:8080", + "http.scheme"=>"http", + "http.target"=>"/rolldice", + "http.user_agent"=>"curl/7.87.0", + "code.namespace"=>"DiceController", + "code.function"=>"roll", + "http.status_code"=>200}, + links=nil, + events=nil, + resource= + #"", + "process.pid"=>83900, + "process.command"=>"bin/rails", + "process.runtime.name"=>"ruby", + "process.runtime.version"=>"3.2.2", + "process.runtime.description"=>"ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]", + "telemetry.sdk.name"=>"opentelemetry", + "telemetry.sdk.language"=>"ruby", + "telemetry.sdk.version"=>"1.2.0"}>, + instrumentation_scope=#, + span_id="\xA7\xF0\x9B#\b[\xE4I", + trace_id="\xF3\xDC\b8\x91h\xB0\xDF\xDEn*CH\x9Blf", + trace_flags=#, + tracestate=#> ``` -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? +## 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! +Adding tracing to a single service is a great first step. OpenTelemetry provides +a few more features that will allow you gain even deeper insights! +- [Exporters][] allow you to export your data to a preferred backend. - [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 @@ -116,12 +193,13 @@ provides a few more features that will allow you gain even deeper insights! - [Manual instrumentation][manual] will give provide you the ability to enrich your traces with domain specific data. +[traces]: /docs/concepts/signals/traces/ +[metrics]: /docs/concepts/signals/metrics/ +[logs]: /docs/concepts/signals/logs/ [auto]: https://github.com/open-telemetry/opentelemetry-ruby#instrumentation-libraries [config]: ../automatic/#configuring-specific-instrumentation-libraries +[exporters]: ../exporters/ [context propagation]: ../manual/#context-propagation [manual]: ../manual/ -[repository]: https://github.com/open-telemetry/opentelemetry-ruby -[sdk-env]: - /docs/reference/specification/protocol/exporter/#configuration-options [span events]: ../manual/#add-span-events diff --git a/static/refcache.json b/static/refcache.json index 53b393ff7d01..aedd5829666b 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -139,6 +139,10 @@ "StatusCode": 200, "LastSeen": "2023-02-15T20:36:46.174243-05:00" }, + "https://bundler.io/": { + "StatusCode": 206, + "LastSeen": "2023-05-04T10:07:22.237529+02:00" + }, "https://calendar.google.com/calendar/embed": { "StatusCode": 200, "LastSeen": "2023-02-15T20:41:36.268773-05:00" @@ -3623,6 +3627,14 @@ "StatusCode": 206, "LastSeen": "2023-02-18T12:42:33.865992-05:00" }, + "https://rubyonrails.org/": { + "StatusCode": 206, + "LastSeen": "2023-05-08T18:19:46.152081+02:00" + }, + "https://rubyonrails.org//": { + "StatusCode": 206, + "LastSeen": "2023-05-08T16:34:49.259754+02:00" + }, "https://sched.co/182Ib": { "StatusCode": 200, "LastSeen": "2023-02-18T12:45:22.56496-05:00" @@ -3691,6 +3703,10 @@ "StatusCode": 206, "LastSeen": "2023-02-18T12:43:42.995104-05:00" }, + "https://sinatrarb.com/": { + "StatusCode": 206, + "LastSeen": "2023-05-04T10:07:22.738034+02:00" + }, "https://skywalking.apache.org": { "StatusCode": 206, "LastSeen": "2023-02-27T02:42:59.806812281Z"