Ruby Tracing SDK

The Instana Ruby gem provides a simple-to-use API to trace any arbitrary part of your application.

You can instrument a section of code as follows:

begin
  span = ::Instana.tracer.start_span(:mywork, attributes: { :helpful_kvs => @user.id })
  # The code to be instrumented
  @id = User.find_by_name('john.smith')
rescue => e
  span.record_exception(e)
ensure
  span.finish
end

Alternatively, you can use the in_span block method that automagically captures and logs any exceptions that are raised:

::Instana.tracer.in_span(:mywork, attributes: { :helpful_kvs => @user.id }) do
  # The code to be instrumented
  @id = User.find_by_name('john.smith')
 end

The preceding examples show how easy it is to instrument any arbitrary piece of code you like.

Some operations that you want to trace might be asynchronous meaning that they might return immediately but still continue to work out of band. To trace such operations, you can use the log_async_* related tracing methods:

::Instana.tracer.log_entry(:prep_job, { :helpful_kvs => @job.name })

http_ops = {:get => "/", :post => "/post_data"}

cb_block = Proc.new do |response, payload|
  # The callback block that is invoked on HTTP response (payload == t_context)
  #
  # process response
  #
  ::Instana.tracer.log_async_exit(:http_op, :status => response.status, payload)
end

http_ops.each do |op|
  t_context = ::Instana.tracer.log_async_entry(:http_op)

  # Example op that returns immediately
  request_id = connection.async_request(op, cb_block, t_context)

  ::Instana.tracer.log_async_info({:request_id => request_id}, t_context)
end  

Tracing is thread local. If you create a new thread, the context must be carried to that new thread and then picked up.

# Get the tracing context
t_context = ::Instana.tracer.context

# Spawn new thread
Thread.new do
  # Pickup context in this thread with `t_context` and attach it to a nonrecording span. Use that span as parent for future spans.
  Instana::Trace.with_span(OpenTelemetry::Trace.non_recording_span(t_context)) do
    span = ::Instana.tracer.start_span(:async_thread, attributes: { :async_start => 1 })

    # Continue tracing work as usual
    begin
      span = ::Instana.tracer.start_span(:mywork, attributes: { :helpful_kvs => @user.id })
      # The code to be instrumented
      @id = User.find_by_name('john.smith')
    rescue => e
      span.record_exception(e)
    ensure
      span.finish
    end
  end
end

Jobs that are queued to be run later can be instrumented as such:

parent_span = ::Instana.tracer.start_span(:prep_job, attributes: { :job_name => @job.name })

# Get the current tracing context
t_context = ::Instana.tracer.context

# The Async proc (job) that will be executed out of band.
block = Proc.new do
  # This will pickup context and link the two traces (root + job)
  parent_context = OpenTelemetry::Trace.context_with_span(parent_span)
  second_span = ::Instana.tracer.start_span(:my_async_op, attributes: { :helpful_kvs => true }, with_parent: parent_context)

  #
  # Some Asynchronous work to be done
  #
  second_span.set_tags({:job_name => Job.get(id).name})
  # More Asynchronous work
  second_span.finish
end

MyClass.run_in_5_minutes(block)

parent_span.finish

To add custom tags to an Instana provided span, use the set_tag method and attach the following hash to the active span.

active_span = ::Instana.tracer.current_span

unless active_span.custom?
  custom_tags = {
    key: 'value'
  }

  active.span.set_tag(:sdk, {custom: {tags: custom_tags}})
end

• Ruby overview
• Ruby configuration
• Ruby Tracing SDK
• Deprecated Ruby OpenTracing
• Ruby troubleshooting
• Ruby supported versions
• Ruby GitHub repository