Uptrace Ruby exporter for OpenTelemetry
Introduction
uptrace-ruby is an exporter for OpenTelemetry that sends your traces/spans and metrics to Uptrace.dev. Briefly the process is the following:
- OpenTelemetry API is used to instrument your application with spans and metrics.
- OpenTelemetry SDK and this exporter send collected information to Uptrace.dev.
- Uptrace.dev uses that information to help you pinpoint failures and find performance bottlenecks.
Instrumenting code
You instrument your application by wrapping potentially interesting operations with spans. Each span has:
- an operation name;
- a start time and end time;
- a set of key/value attributes containing data about the operation;
- a set of timed events representing events, errors, logs, etc.
You create spans using 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 roughly 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 from the context:
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')
or 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