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 the Instana Ruby Tracing SDK.

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

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

::Instana.tracer.trace(:mywork, { :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.

Asynchronous tracing

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

Carrying context into new threads

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