Custom Instrumentation

To instrument certain regions of your code, you can create transactions to capture them.

The following example creates a transaction for a scope that contains an expensive operation (for example, process_item), and sends the result to Sentry:

# start a transaction
transaction = Sentry.start_transaction(op: "process_item")

# set the transaction on the scope so children span are attached to this transaction
Sentry.get_current_scope.set_span(transaction)

# perform the operation
process_item(args)


# finish the transaction, which will send it to Sentry automatically
transaction.finish

Add More Spans to the Transaction

The next example contains the implementation of the hypothetical process_item function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add all newly created spans as child operations to that transaction. You can choose the values of op and description.

class OrdersController < ApplicationController
  def create
    order = Order.new

    Sentry.with_child_span(op: :process_items, description: 'processing items') do |span|
      span.set_data(:key, 'value')

      order.process_items(params)
    end
  end # the child span ends with the block
end

Your new span will be nested under whichever span is currently running on the scope, otherwise it will be at the root of the transaction event.

Alternatively, you can manually grab the current transaction and use its with_child_span method to always create a top-level span.

class OrdersController < ApplicationController
  def create
    order = Order.new
    transaction = Sentry.get_current_scope.get_transaction

    transaction.with_child_span(op: :process_items, description: 'processing items') do |span|
      span.set_data(:key, 'value')
      order.process_items(params)
    end # the child span ends with the block
  end
end

Keep in mind that there may not be an active transaction, in which case get_transaction returns nil. This case needs to be handled manually and is missing from this example.

Retrieve a Transaction

In cases where you want to attach Spans to an already ongoing Transaction you can use Sentry.get_current_scope.get_transaction. This property will return a Transaction in case there is a running Transaction otherwise it returns nil.

transaction = Sentry.get_current_scope.get_transaction || Sentry.start_transaction(name: 'task')

span = transaction.start_child(op: 'operation')
# perform the operation
span.finish

Retrieve the Current Span

Started spans are stored in the scope, and can be fetched off the scope:

span = Sentry.get_current_scope.get_span