Skip to content

Uptrace for Ruby

Installation

gem install uptrace

Introduction

uptrace-ruby is the official Uptrace client for Ruby that sends your traces/spans to Uptrace.

To learn about tracing, please see Introduction to distributed tracing.

Instrumenting your code

To create a tracer:

require 'opentelemetry'

// Create a named tracer using your repo as an identifier.
tracer = OpenTelemetry.tracer_provider.tracer('github.com/username/app-name', 'semver:1.0')

To create a span:

tracer.in_span('operation-name') do |span|
  do_some_work
end

Internally that does the following:

// Create a span.
span = tracer.start_span('operation-name')

// Activate the span within the current context.
tracer.with_span(span) do |span|
  do_some_work
end

// Finish the span when operation is completed.
span.finish

To get the active span:

span = tracer.current_span

Once you have a span you can start adding attributes:

span.set_attribute('enduser.id', '123')
span.set_attribute('enduser.role', 'admin')

And more complex events:

span.add_event(name: 'log', attributes: {
  'log.severity': 'error',
  'log.message': 'User not found',
  'enduser.id': '123',
})

To record an error use record_error which internally uses add_event. Note that tracer.in_span already records resqued exceptions.

rescue Exception => e
  span.record_error(e)
end