Ruby Tracing SDK

Tracing with Instana is automatic but if you want even more visibility into custom code, a specific application area or some in-house component, you can use Instana's Ruby Tracing SDK as detailed as follows.

The Instana Ruby Tracing SDK

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

To instrument a section of code, it can be simply done with:

begin
  ::Instana.tracer.log_entry(:mywork, { :helpful_kvs => @user.id })
  # The code to be instrumented
  @id = User.find_by_name('john.smith')
rescue => e
  ::Instana.tracer.log_error(e)
ensure
  ::Instana.tracer.log_exit(:mywork, { :found_id => @id })
end

or alternatively you can use the trace block method that will automagically capture and log any exceptions raised:

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

The above are simple examples but shows how easy it is to instrument any arbitrary piece of code you like.

Asynchronous Tracing

Some operations that you want to trace might be asynchronous meaning that they may return immediately but will still continue to work out of band. To do this, 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

Carrying Context into New Threads

Tracing is thread local. If you spawn 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`
  ::Instana.tracer.log_start_or_continue(:async_thread, { :async_start => 1 }, t_context)

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

Tracing Jobs Scheduled for Later

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

::Instana.tracer.log_entry(:prep_job, { :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)
  t_context = ::Instana.tracer.log_start_or_continue_trace(:my_async_op, { :helpful_kvs => true }, t_context)
  #
  # Some Asynchronous work to be done
  #
  ::Instana.tracer.log_info({:job_name => Job.get(id).name})
  # More Asynchronous work
  ::Instana.tracer.log_end(:my_async_op, { :job_success => true })
end

MyClass.run_in_5_minutes(block)

::Instana.tracer.log_exit(:prep_job, { :prep_successful => true })

Adding Custom Tags to Instana Provided Spans

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

See Also