OpenTelemetry Ruby distro for Uptrace

This document explains how to configure OpenTelemetry Ruby SDK to export spans and metrics to Uptrace using OTLP/HTTP.

To learn about OpenTelemetry API, see OpenTelemetry Ruby Tracing API and OpenTelemetry Ruby Metrics API.

• OpenTelemetry Ruby
• Configuration
• Getting started
• What's next?

OpenTelemetry Ruby

Add to Gemfile:

gem 'uptrace'

Or install the gem:

gem install uptrace

Configuration

You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<token>@uptrace.dev/<project_id>) from the project settings page.

require 'uptrace'

# copy your project DSN here or use UPTRACE_DSN env var
Uptrace.configure_opentelemetry(dsn: 'https://<token>@uptrace.dev/<project_id>') do |c|
  # c is OpenTelemetry::SDK::Configurator
  c.service_name = 'myservice'
  c.service_version = '1.0.0'

  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    'deployment.environment' => 'production'
  )
end

You can also use environment variables to configure the client:

Env var	Description
UPTRACE_DSN	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTES	Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORS	Propagators to be used as a comma separated list. The default is tracecontext,baggage.

Getting started

Install OpenTelemetry distro, generate your first trace, and click the link in your terminal to open Uptrace. All it takes is a minute of your time.

• Step 0. Create an Uptrace project to obtain a DSN (connection string), for example, https://<token>@uptrace.dev/<project_id>.

• Step 1. Add uptrace to the Gemfile:

gem 'uptrace'

• Step 2. Copy the code to main.rb replacing the <dsn>:

#!/usr/bin/env ruby
# frozen_string_literal: true

require 'rubygems'
require 'bundler/setup'
require 'uptrace'

# Configure OpenTelemetry with sensible defaults.
# copy your project DSN here or use UPTRACE_DSN env var
Uptrace.configure_opentelemetry(dsn: 'https://<token>@uptrace.dev/<project_id>') do |c|
  # c is OpenTelemetry::SDK::Configurator
  c.service_name = 'myservice'
  c.service_version = '1.0.0'
end

# Create a tracer. Usually, tracer is a global variable.
tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')

# Create a root span (a trace) to measure some operation.
tracer.in_span('main-operation') do |main|
  tracer.in_span('child1-of-main') do |child1|
    child1.set_attribute('key1', 'value1')
    child1.record_exception(ArgumentError.new('error1'))
  end

  tracer.in_span('child2-of-main') do |child2|
    child2.set_attribute('key2', '24')
    child2.set_attribute('key3', 123.456)
  end

  puts("trace URL: #{Uptrace.trace_url(main)}")
end

# Send buffered spans and free resources.
OpenTelemetry.tracer_provider.shutdown

• Step 3. Run the example to get a link for the generated trace:

ruby main.rb
trace URL: https://uptrace.dev/traces/<trace_id>

• Step 4. Follow the link to view the generated trace:

What's next?

• Look for instrumentations and browse examples.
• Learn about Tracing API and Metrics API to create your own instrumentations.

Tutorials:

• OpenTelemetry guide for Ruby on Rails