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