Exporters

In order to visualize and analyze your telemetry, you will need to export your data to an OpenTelemetry Collector or a backend such as Jaeger, Zipkin, Prometheus or a vendor-specific one.

As part of OpenTelemetry Ruby you will find many exporters being available. Among them, the OpenTelemetry Protocol (OTLP) exporters provide the best experience for you as an end-user, since it is a general-purpose telemetry data delivery protocol designed in the scope of the OpenTelemetry project.

To learn more about the OTLP protocol, you can read the OTLP Specification.

Below you will find some introductions on how to set up exporters for OTLP and other common protocols in your code.

OTLP endpoint

To send trace data to a OTLP endpoint (like the collector or Jaeger) you’ll want to use an exporter package, such as opentelemetry-exporter-otlp:

• bundler
• gem

bundle add opentelemetry-exporter-otlp

gem install opentelemetry-exporter-otlp

Next, configure the exporter to point at an OTLP endpoint. For example you can update config/initializers/opentelemetry.rb from the Getting Started by adding require 'opentelemetry-exporter-otlp' to the code:

# 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:

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:

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:

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:

docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin

Install the exporter package as a dependency for your application:

• bundle
• gem

bundle add opentelemetry-exporter-zipkin

gem install opentelemetry-exporter-zipkin

Update your OpenTelemetry configuration to use the exporter and to send data to your Zipkin backend:

# 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:

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:

env OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:9411" rails server