appsignal 2.8.4 → 2.9.0

data/lib/appsignal/cli/diagnose.rb

@@ -82,6 +82,8 @@ module Appsignal
           print_empty_line
 
           library_information
+          data[:installation] = fetch_installation_report
+          print_installation_report
           print_empty_line
 
           host_information
@@ -180,7 +182,8 @@ module Appsignal
           if rails_app?
             data[:app][:rails] = true
             current_path = Rails.root
-            initial_config[:name] = Rails.application.class.parent_name
+            initial_config[:name] =
+              Appsignal::Utils::RailsHelper.detected_rails_app_name
             initial_config[:log_path] = current_path.join("log")
           end
 
@@ -325,12 +328,89 @@ module Appsignal
             save :language, "ruby"
             puts_and_save :package_version, "Gem version", Appsignal::VERSION
             puts_and_save :agent_version, "Agent version", Appsignal::Extension.agent_version
-            puts_and_save :agent_architecture, "Agent architecture",
-              Appsignal::System.installed_agent_architecture
             puts_and_save :extension_loaded, "Extension loaded", Appsignal.extension_loaded
           end
         end
 
+        def fetch_installation_report
+          path = File.expand_path("../../../../ext/install.report", __FILE__)
+          raw_report = File.read(path)
+          Utils.parse_yaml(raw_report)
+        rescue => e
+          {
+            "parsing_error" => {
+              "error" => "#{e.class}: #{e}",
+              "backtrace" => e.backtrace
+            }.tap do |r|
+              r["raw"] = raw_report if raw_report
+            end
+          }
+        end
+
+        def print_installation_report
+          puts "\nExtension installation report"
+          install_report = data[:installation]
+          if install_report.key? "parsing_error"
+            print_installation_report_parsing_error(install_report)
+            return
+          end
+
+          print_installation_result_report(install_report)
+          print_installation_language_report(install_report)
+          print_installation_download_report(install_report)
+          print_installation_build_report(install_report)
+          print_installation_host_report(install_report)
+        end
+
+        def print_installation_report_parsing_error(report)
+          report = report["parsing_error"]
+          puts "  Error found while parsing the report."
+          puts "  Error: #{report["error"]}"
+          puts "  Raw report:\n#{report["raw"]}" if report["raw"]
+        end
+
+        def print_installation_result_report(report)
+          report = report.fetch("download", {})
+          puts "  Installation result"
+          puts "    Status: #{report["status"]}"
+          puts "    Message: #{report["message"]}" if report["message"]
+          puts "    Error: #{report["error"]}" if report["error"]
+        end
+
+        def print_installation_language_report(report)
+          report = report.fetch("language", {})
+          puts "  Language details"
+          puts "    Implementation: #{report["implementation"]}"
+          puts "    Ruby version: #{report["version"]}"
+        end
+
+        def print_installation_download_report(report)
+          report = report.fetch("download", {})
+          puts "  Download details"
+          puts "    Download URL: #{report["download_url"]}"
+          puts "    Checksum: #{report["checksum"]}"
+        end
+
+        def print_installation_build_report(report)
+          report = report.fetch("build", {})
+          puts "  Build details"
+          puts "    Install time: #{report["time"]}"
+          puts "    Architecture: #{report["architecture"]}"
+          puts "    Target: #{report["target"]}"
+          puts "    Musl override: #{report["musl_override"]}"
+          puts "    Library type: #{report["library_type"]}"
+          puts "    Source: #{report["source"]}" if report["source"] != "remote"
+          puts "    Dependencies: #{report["dependencies"]}"
+          puts "    Flags: #{report["flags"]}"
+        end
+
+        def print_installation_host_report(report)
+          report = report.fetch("host", {})
+          puts "  Host details"
+          puts "    Root user: #{report["root_user"]}"
+          puts "    Dependencies: #{report["dependencies"]}"
+        end
+
         def host_information
           rbconfig = RbConfig::CONFIG
           puts "Host information"
@@ -349,7 +429,7 @@ module Appsignal
             save :heroku, Appsignal::System.heroku?
 
             save :root, Process.uid.zero?
-            puts_value "root user",
+            puts_value "Root user",
               Process.uid.zero? ? "true (not recommended)" : "false"
             puts_and_save :running_in_container, "Running in container",
               Appsignal::Extension.running_in_container?

data/lib/appsignal/cli/diagnose/paths.rb

@@ -17,7 +17,6 @@ module Appsignal
             begin
               config = Appsignal.config
               log_file_path = config.log_file_path
-              install_log_path = File.join("ext", "install.log")
               makefile_log_path = File.join("ext", "mkmf.log")
               {
                 :package_install_path => {
@@ -36,10 +35,6 @@ module Appsignal
                   :label => "Log directory",
                   :path => log_file_path ? File.dirname(log_file_path) : ""
                 },
-                install_log_path => {
-                  :label => "Extension install log",
-                  :path => File.join(gem_path, install_log_path)
-                },
                 makefile_log_path => {
                   :label => "Makefile install log",
                   :path => File.join(gem_path, makefile_log_path)

data/lib/appsignal/cli/diagnose/utils.rb

@@ -30,6 +30,23 @@ module Appsignal
 
           IO.binread(path, length, offset)
         end
+
+        def self.parse_yaml(contents)
+          arguments = [contents]
+          if YAML.respond_to? :safe_load
+            method = :safe_load
+            arguments << \
+              if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.6.0")
+                # Use keyword params for Ruby 2.6 and up
+                { :permitted_classes => [Time] }
+              else
+                [Time]
+              end
+          else
+            method = :load
+          end
+          YAML.send(method, *arguments)
+        end
       end
     end
   end

data/lib/appsignal/cli/helpers.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require "appsignal/utils/rails_helper"
+
 module Appsignal
   class CLI
     module Helpers
       private
 
+      def ruby_2_6_or_up?
+        Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.6.0")
+      end
+
       def colorize(text, color)
         return text if Gem.win_platform?
 

data/lib/appsignal/cli/install.rb

@@ -77,8 +77,7 @@ module Appsignal
 
           require File.expand_path(File.join(Dir.pwd, "config/application.rb"))
 
-          config[:name] = Rails.application.class.parent_name
-
+          config[:name] = Appsignal::Utils::RailsHelper.detected_rails_app_name
           name_overwritten = yes_or_no("  Your app's name is: '#{config[:name]}' \n  Do you want to change how this is displayed in AppSignal? (y/n): ")
           puts
           if name_overwritten
@@ -249,12 +248,19 @@ module Appsignal
         end
 
         def write_config_file(data)
-          template = ERB.new(
-            File.read(File.join(File.dirname(__FILE__), "../../../resources/appsignal.yml.erb")),
-            nil,
-            "-"
+          filename = File.join(
+            File.dirname(__FILE__),
+            "../../../resources/appsignal.yml.erb"
           )
-
+          file_contents = File.read(filename)
+          arguments = [file_contents]
+          if ruby_2_6_or_up?
+            arguments << { :trim_mode => "-" }
+          else
+            arguments << nil
+            arguments << "-"
+          end
+          template = ERB.new(*arguments)
           config = template.result(OpenStruct.new(data).instance_eval { binding })
 
           FileUtils.mkdir_p(File.join(Dir.pwd, "config"))

data/lib/appsignal/config.rb

@@ -36,7 +36,7 @@ module Appsignal
       :enable_allocation_tracking     => true,
       :enable_gc_instrumentation      => false,
       :enable_host_metrics            => true,
-      :enable_minutely_probes         => false,
+      :enable_minutely_probes         => true,
       :ca_file_path                   => File.expand_path(File.join("../../../resources/cacert.pem"), __FILE__),
       :dns_servers                    => [],
       :files_world_accessible         => true
@@ -214,7 +214,6 @@ module Appsignal
       ENV["_APPSIGNAL_WORKING_DIR_PATH"]             = config_hash[:working_dir_path] if config_hash[:working_dir_path]
       ENV["_APPSIGNAL_WORKING_DIRECTORY_PATH"]       = config_hash[:working_directory_path] if config_hash[:working_directory_path]
       ENV["_APPSIGNAL_ENABLE_HOST_METRICS"]          = config_hash[:enable_host_metrics].to_s
-      ENV["_APPSIGNAL_ENABLE_MINUTELY_PROBES"]       = config_hash[:enable_minutely_probes].to_s
       ENV["_APPSIGNAL_HOSTNAME"]                     = config_hash[:hostname].to_s
       ENV["_APPSIGNAL_PROCESS_NAME"]                 = $PROGRAM_NAME
       ENV["_APPSIGNAL_CA_FILE_PATH"]                 = config_hash[:ca_file_path].to_s

data/lib/appsignal/event_formatter.rb

@@ -75,16 +75,15 @@ module Appsignal
 
       def initialize_formatter(name, formatter)
         format_method = formatter.instance_method(:format)
-        if format_method && format_method.arity == 1
-          formatter_classes[name] = formatter
-          formatters[name] = formatter.new
-        else
+        if !format_method || format_method.arity != 1
           raise "#{formatter} does not have a format(payload) method"
         end
+        formatter_classes[name] = formatter
+        formatters[name] = formatter.new
       rescue => ex
         formatter_classes.delete(name)
         formatters.delete(name)
-        logger.warn("'#{ex.message}' when initializing #{name} event formatter")
+        logger.error("'#{ex.message}' when initializing #{name} event formatter")
       end
 
       def register_deprecated_formatter(name)

data/lib/appsignal/event_formatter/moped/query_formatter.rb

@@ -6,65 +6,66 @@ module Appsignal
     module Moped
       class QueryFormatter
         def format(payload)
-          if payload[:ops] && !payload[:ops].empty?
-            op = payload[:ops].first
-            case op.class.to_s
-            when "Moped::Protocol::Command"
-              [
-                "Command", {
-                  :database => op.full_collection_name,
-                  :selector => sanitize(op.selector, true, :mongodb)
-                }.inspect
-              ]
-            when "Moped::Protocol::Query"
-              [
-                "Query", {
-                  :database => op.full_collection_name,
-                  :selector => sanitize(op.selector, false, :mongodb),
-                  :flags    => op.flags,
-                  :limit    => op.limit,
-                  :skip     => op.skip,
-                  :fields   => op.fields
-                }.inspect
-              ]
-            when "Moped::Protocol::Delete"
-              [
-                "Delete", {
-                  :database => op.full_collection_name,
-                  :selector => sanitize(op.selector, false, :mongodb),
-                  :flags    => op.flags
-                }.inspect
-              ]
-            when "Moped::Protocol::Insert"
-              [
-                "Insert", {
-                  :database   => op.full_collection_name,
-                  :documents  => sanitize(op.documents, true, :mongodb),
-                  :count      => op.documents.count,
-                  :flags      => op.flags
-                }.inspect
-              ]
-            when "Moped::Protocol::Update"
-              [
-                "Update",
-                {
-                  :database => op.full_collection_name,
-                  :selector => sanitize(op.selector, false, :mongodb),
-                  :update   => sanitize(op.update, true, :mongodb),
-                  :flags    => op.flags
-                }.inspect
-              ]
-            when "Moped::Protocol::KillCursors"
-              [
-                "KillCursors",
-                { :number_of_cursor_ids => op.number_of_cursor_ids }.inspect
-              ]
-            else
-              [
-                op.class.to_s.sub("Moped::Protocol::", ""),
-                { :database => op.full_collection_name }.inspect
-              ]
-            end
+          return unless payload[:ops]
+          return if payload[:ops].empty?
+
+          op = payload[:ops].first
+          case op.class.to_s
+          when "Moped::Protocol::Command"
+            [
+              "Command", {
+                :database => op.full_collection_name,
+                :selector => sanitize(op.selector, true, :mongodb)
+              }.inspect
+            ]
+          when "Moped::Protocol::Query"
+            [
+              "Query", {
+                :database => op.full_collection_name,
+                :selector => sanitize(op.selector, false, :mongodb),
+                :flags    => op.flags,
+                :limit    => op.limit,
+                :skip     => op.skip,
+                :fields   => op.fields
+              }.inspect
+            ]
+          when "Moped::Protocol::Delete"
+            [
+              "Delete", {
+                :database => op.full_collection_name,
+                :selector => sanitize(op.selector, false, :mongodb),
+                :flags    => op.flags
+              }.inspect
+            ]
+          when "Moped::Protocol::Insert"
+            [
+              "Insert", {
+                :database   => op.full_collection_name,
+                :documents  => sanitize(op.documents, true, :mongodb),
+                :count      => op.documents.count,
+                :flags      => op.flags
+              }.inspect
+            ]
+          when "Moped::Protocol::Update"
+            [
+              "Update",
+              {
+                :database => op.full_collection_name,
+                :selector => sanitize(op.selector, false, :mongodb),
+                :update   => sanitize(op.update, true, :mongodb),
+                :flags    => op.flags
+              }.inspect
+            ]
+          when "Moped::Protocol::KillCursors"
+            [
+              "KillCursors",
+              { :number_of_cursor_ids => op.number_of_cursor_ids }.inspect
+            ]
+          else
+            [
+              op.class.to_s.sub("Moped::Protocol::", ""),
+              { :database => op.full_collection_name }.inspect
+            ]
           end
         end
 

data/lib/appsignal/extension.rb

@@ -12,8 +12,8 @@ begin
   end
 rescue LoadError => err
   Appsignal.logger.error(
-    "Failed to load extension (#{err}), please check the install.log file in " \
-    "the ext directory of the gem and email us at support@appsignal.com"
+    "Failed to load extension (#{err}), please run `appsignal diagnose` " \
+      "and email us at support@appsignal.com"
   )
   Appsignal.extension_loaded = false
 end

data/lib/appsignal/helpers/instrumentation.rb

@@ -0,0 +1,485 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Helpers
+    # @api private
+    module Instrumentation # rubocop:disable Metrics/ModuleLength
+      # Creates an AppSignal transaction for the given block.
+      #
+      # If AppSignal is not {.active?} it will still execute the block, but not
+      # create a transaction for it.
+      #
+      # A event is created for this transaction with the name given in the
+      # `name` argument. The event name must start with either `perform_job` or
+      # `process_action` to differentiate between the "web" and "background"
+      # namespace. Custom namespaces are not supported by this helper method.
+      #
+      # This helper method also captures any exception that occurs in the given
+      # block.
+      #
+      # @example
+      #   Appsignal.monitor_transaction("perform_job.nightly_update") do
+      #     # your code
+      #   end
+      #
+      # @example with an environment
+      #   Appsignal.monitor_transaction(
+      #     "perform_job.nightly_update",
+      #     :metadata => { "user_id" => 1 }
+      #   ) do
+      #     # your code
+      #   end
+      #
+      # @param name [String] main event name.
+      # @param env [Hash<Symbol, Object>]
+      # @option env [Hash<Symbol/String, Object>] :params Params for the
+      #   monitored request/job, see {Appsignal::Transaction#params=} for more
+      #   information.
+      # @option env [String] :controller name of the controller in which the
+      #   transaction was recorded.
+      # @option env [String] :class name of the Ruby class in which the
+      #   transaction was recorded. If `:controller` is also given,
+      #   `:controller` is used instead.
+      # @option env [String] :action name of the controller action in which the
+      #   transaction was recorded.
+      # @option env [String] :method name of the Ruby method in which the
+      #   transaction was recorded. If `:action` is also given, `:action`
+      #   is used instead.
+      # @option env [Integer] :queue_start the moment the request/job was
+      #   queued. Used to track how long requests/jobs were queued before being
+      #   executed.
+      # @option env [Hash<Symbol/String, String/Fixnum>] :metadata Additional
+      #   metadata for the transaction, see
+      #   {Appsignal::Transaction#set_metadata} for more information.
+      # @yield the block to monitor.
+      # @raise [Exception] any exception that occurs within the given block is
+      #   re-raised by this method.
+      # @return [Object] the value of the given block is returned.
+      # @since 0.10.0
+      def monitor_transaction(name, env = {})
+        return yield unless active?
+
+        if name.start_with?("perform_job".freeze)
+          namespace = Appsignal::Transaction::BACKGROUND_JOB
+          request   = Appsignal::Transaction::GenericRequest.new(env)
+        elsif name.start_with?("process_action".freeze)
+          namespace = Appsignal::Transaction::HTTP_REQUEST
+          request   = ::Rack::Request.new(env)
+        else
+          logger.error("Unrecognized name '#{name}'")
+          return
+        end
+        transaction = Appsignal::Transaction.create(
+          SecureRandom.uuid,
+          namespace,
+          request
+        )
+        begin
+          Appsignal.instrument(name) do
+            yield
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          transaction.set_error(error)
+          raise error
+        ensure
+          transaction.set_http_or_background_action(request.env)
+          transaction.set_http_or_background_queue_start
+          Appsignal::Transaction.complete_current!
+        end
+      end
+
+      # Monitor a transaction, stop AppSignal and wait for this single
+      # transaction to be flushed.
+      #
+      # Useful for cases such as Rake tasks and Resque-like systems where a
+      # process is forked and immediately exits after the transaction finishes.
+      #
+      # @see monitor_transaction
+      def monitor_single_transaction(name, env = {}, &block)
+        monitor_transaction(name, env, &block)
+      ensure
+        stop("monitor_single_transaction")
+      end
+
+      # Listen for an error to occur and send it to AppSignal.
+      #
+      # Uses {.send_error} to directly send the error in a separate
+      # transaction. Does not add the error to the current transaction.
+      #
+      # Make sure that AppSignal is integrated in your application beforehand.
+      # AppSignal won't record errors unless {Config#active?} is `true`.
+      #
+      # @example
+      #   # my_app.rb
+      #   # setup AppSignal beforehand
+      #
+      #   Appsignal.listen_for_error do
+      #     # my code
+      #     raise "foo"
+      #   end
+      #
+      # @see Transaction.set_tags
+      # @see Transaction.set_namespace
+      # @see .send_error
+      # @see https://docs.appsignal.com/ruby/instrumentation/integrating-appsignal.html
+      #   AppSignal integration guide
+      #
+      # @param tags [Hash, nil]
+      # @param namespace [String] the namespace for this error.
+      # @yield yields the given block.
+      # @return [Object] returns the return value of the given block.
+      def listen_for_error(
+        tags = nil,
+        namespace = Appsignal::Transaction::HTTP_REQUEST
+      )
+        yield
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        send_error(error, tags, namespace)
+        raise error
+      end
+      alias :listen_for_exception :listen_for_error
+
+      # Send an error to AppSignal regardless of the context.
+      #
+      # Records and send the exception to AppSignal.
+      #
+      # This instrumentation helper does not require a transaction to be
+      # active, it starts a new transaction by itself.
+      #
+      # Use {.set_error} if your want to add an exception to the current
+      # transaction.
+      #
+      # **Note**: Does not do anything if AppSignal is not active or when the
+      # "error" is not a class extended from Ruby's Exception class.
+      #
+      # @example Send an exception
+      #   begin
+      #     raise "oh no!"
+      #   rescue => e
+      #     Appsignal.send_error(e)
+      #   end
+      #
+      # @example Send an exception with tags
+      #   begin
+      #     raise "oh no!"
+      #   rescue => e
+      #     Appsignal.send_error(e, :key => "value")
+      #   end
+      #
+      # @example Add more metadata to transaction
+      #   Appsignal.send_error(e, :key => "value") do |transaction|
+      #     transaction.params(:search_query => params[:search_query])
+      #     transaction.set_action("my_action_name")
+      #     transaction.set_namespace("my_namespace")
+      #   end
+      #
+      # @param error [Exception] The error to send to AppSignal.
+      # @param tags [Hash{String, Symbol => String, Symbol, Integer}]
+      #   Additional tags to add to the error. See also {.tag_request}.
+      # @param namespace [String] The namespace in which the error occurred.
+      #   See also {.set_namespace}.
+      # @yield [transaction] yields block to allow modification of the
+      #   transaction before it's send.
+      # @yieldparam transaction [Transaction] yields the AppSignal transaction
+      #   used to send the error.
+      # @return [void]
+      #
+      # @see http://docs.appsignal.com/ruby/instrumentation/exception-handling.html
+      #   Exception handling guide
+      # @see http://docs.appsignal.com/ruby/instrumentation/tagging.html
+      #   Tagging guide
+      # @since 0.6.0
+      def send_error(
+        error,
+        tags = nil,
+        namespace = Appsignal::Transaction::HTTP_REQUEST
+      )
+        return unless active?
+        unless error.is_a?(Exception)
+          logger.error("Can't send error, given value is not an exception")
+          return
+        end
+        transaction = Appsignal::Transaction.new(
+          SecureRandom.uuid,
+          namespace,
+          Appsignal::Transaction::GenericRequest.new({})
+        )
+        transaction.set_tags(tags) if tags
+        transaction.set_error(error)
+        yield transaction if block_given?
+        transaction.complete
+      end
+      alias :send_exception :send_error
+
+      # Set an error on the current transaction.
+      #
+      # **Note**: Does not do anything if AppSignal is not active, no
+      # transaction is currently active or when the "error" is not a class
+      # extended from Ruby's Exception class.
+      #
+      # @example Manual instrumentation of set_error.
+      #   # Manually starting AppSignal here
+      #   # Manually starting a transaction here.
+      #   begin
+      #     raise "oh no!"
+      #   rescue => e
+      #     Appsignal.set_error(error)
+      #   end
+      #   # Manually completing the transaction here.
+      #   # Manually stopping AppSignal here
+      #
+      # @example In a Rails application
+      #   class SomeController < ApplicationController
+      #     # The AppSignal transaction is created by our integration for you.
+      #     def create
+      #       # Do something that breaks
+      #     rescue => e
+      #       Appsignal.set_error(e)
+      #     end
+      #   end
+      #
+      # @param exception [Exception] The error to add to the current
+      #   transaction.
+      # @param tags [Hash{String, Symbol => String, Symbol, Integer}]
+      #   Additional tags to add to the error. See also {.tag_request}.
+      # @param namespace [String] The namespace in which the error occurred.
+      #   See also {.set_namespace}.
+      # @return [void]
+      #
+      # @see Transaction#set_error
+      # @see http://docs.appsignal.com/ruby/instrumentation/exception-handling.html
+      #   Exception handling guide
+      # @since 0.6.6
+      def set_error(exception, tags = nil, namespace = nil)
+        return if !active? ||
+            Appsignal::Transaction.current.nil? ||
+            exception.nil?
+        transaction = Appsignal::Transaction.current
+        transaction.set_error(exception)
+        transaction.set_tags(tags) if tags
+        transaction.set_namespace(namespace) if namespace
+      end
+      alias :set_exception :set_error
+      alias :add_exception :set_error
+
+      # Set a custom action name for the current transaction.
+      #
+      # When using an integration such as the Rails or Sinatra AppSignal will
+      # try to find the action name from the controller or endpoint for you.
+      #
+      # If you want to customize the action name as it appears on AppSignal.com
+      # you can use this method. This overrides the action name AppSignal
+      # generates in an integration.
+      #
+      # @example in a Rails controller
+      #   class SomeController < ApplicationController
+      #     before_action :set_appsignal_action
+      #
+      #     def set_appsignal_action
+      #       Appsignal.set_action("DynamicController#dynamic_method")
+      #     end
+      #   end
+      #
+      # @param action [String]
+      # @return [void]
+      # @see Transaction#set_action
+      # @since 2.2.0
+      def set_action(action)
+        return if !active? ||
+            Appsignal::Transaction.current.nil? ||
+            action.nil?
+        Appsignal::Transaction.current.set_action(action)
+      end
+
+      # Set a custom namespace for the current transaction.
+      #
+      # When using an integration such as Rails or Sidekiq AppSignal will try
+      # to find a appropriate namespace for the transaction.
+      #
+      # A Rails controller will be automatically put in the "http_request"
+      # namespace, while a Sidekiq background job is put in the
+      # "background_job" namespace.
+      #
+      # Note: The "http_request" namespace gets transformed on AppSignal.com to
+      # "Web" and "background_job" gets transformed to "Background".
+      #
+      # If you want to customize the namespace in which transactions appear you
+      # can use this method. This overrides the namespace AppSignal uses by
+      # default.
+      #
+      # A common request we've seen is to split the administration panel from
+      # the main application.
+      #
+      # @example create a custom admin namespace
+      #   class AdminController < ApplicationController
+      #     before_action :set_appsignal_namespace
+      #
+      #     def set_appsignal_namespace
+      #       Appsignal.set_namespace("admin")
+      #     end
+      #   end
+      #
+      # @param namespace [String]
+      # @return [void]
+      # @see Transaction#set_namespace
+      # @since 2.2.0
+      def set_namespace(namespace)
+        return if !active? ||
+            Appsignal::Transaction.current.nil? ||
+            namespace.nil?
+        Appsignal::Transaction.current.set_namespace(namespace)
+      end
+
+      # Set tags on the current transaction.
+      #
+      # Tags are extra bits of information that are added to transaction and
+      # appear on sample details pages on AppSignal.com.
+      #
+      # @example
+      #   Appsignal.tag_request(:locale => "en")
+      #   Appsignal.tag_request("locale" => "en")
+      #   Appsignal.tag_request("user_id" => 1)
+      #
+      # @example Nested hashes are not supported
+      #   # Bad
+      #   Appsignal.tag_request(:user => { :locale => "en" })
+      #
+      # @example in a Rails controller
+      #   class SomeController < ApplicationController
+      #     before_action :set_appsignal_tags
+      #
+      #     def set_appsignal_tags
+      #       Appsignal.tag_request(:locale => I18n.locale)
+      #     end
+      #   end
+      #
+      # @param tags [Hash] Collection of tags.
+      # @option tags [String, Symbol, Integer] :any
+      #   The name of the tag as a Symbol.
+      # @option tags [String, Symbol, Integer] "any"
+      #   The name of the tag as a String.
+      # @return [void]
+      #
+      # @see Transaction.set_tags
+      # @see http://docs.appsignal.com/ruby/instrumentation/tagging.html
+      #   Tagging guide
+      def tag_request(tags = {})
+        return unless active?
+        transaction = Appsignal::Transaction.current
+        return false unless transaction
+        transaction.set_tags(tags)
+      end
+      alias :tag_job :tag_request
+
+      # Instrument helper for AppSignal.
+      #
+      # For more help, read our custom instrumentation guide, listed under "See
+      # also".
+      #
+      # @example Simple instrumentation
+      #   Appsignal.instrument("fetch.issue_fetcher") do
+      #     # To be instrumented code
+      #   end
+      #
+      # @example Instrumentation with title and body
+      #   Appsignal.instrument(
+      #     "fetch.issue_fetcher",
+      #     "Fetching issue",
+      #     "GitHub API"
+      #   ) do
+      #     # To be instrumented code
+      #   end
+      #
+      # @param name [String] Name of the instrumented event. Read our event
+      #   naming guide listed under "See also".
+      # @param title [String, nil] Human readable name of the event.
+      # @param body [String, nil] Value of importance for the event, such as
+      #   the server against an API call is made.
+      # @param body_format [Integer] Enum for the type of event that is
+      #   instrumented. Accepted values are {EventFormatter::DEFAULT} and
+      #   {EventFormatter::SQL_BODY_FORMAT}, but we recommend you use
+      #   {.instrument_sql} instead of {EventFormatter::SQL_BODY_FORMAT}.
+      # @yield yields the given block of code instrumented in an AppSignal
+      #   event.
+      # @return [Object] Returns the block's return value.
+      #
+      # @see Appsignal::Transaction#instrument
+      # @see .instrument_sql
+      # @see http://docs.appsignal.com/ruby/instrumentation/instrumentation.html
+      #   AppSignal custom instrumentation guide
+      # @see http://docs.appsignal.com/api/event-names.html
+      #   AppSignal event naming guide
+      # @since 1.3.0
+      def instrument(
+        name,
+        title = nil,
+        body = nil,
+        body_format = Appsignal::EventFormatter::DEFAULT
+      )
+        Appsignal::Transaction.current.start_event
+        yield if block_given?
+      ensure
+        Appsignal::Transaction
+          .current
+          .finish_event(name, title, body, body_format)
+      end
+
+      # Instrumentation helper for SQL queries.
+      #
+      # This helper filters out values from SQL queries so you don't have to.
+      #
+      # @example SQL query instrumentation
+      #   body = "SELECT * FROM ..."
+      #   Appsignal.instrument_sql("perform.query", nil, body) do
+      #     # To be instrumented code
+      #   end
+      #
+      # @example SQL query instrumentation
+      #   body = "WHERE email = 'foo@..'"
+      #   Appsignal.instrument_sql("perform.query", nil, body) do
+      #     # query value will replace 'foo..' with a question mark `?`.
+      #   end
+      #
+      # @param name [String] Name of the instrumented event. Read our event
+      #   naming guide listed under "See also".
+      # @param title [String, nil] Human readable name of the event.
+      # @param body [String, nil] SQL query that's being executed.
+      # @yield yields the given block of code instrumented in an AppSignal
+      #   event.
+      # @return [Object] Returns the block's return value.
+      #
+      # @see .instrument
+      # @see http://docs.appsignal.com/ruby/instrumentation/instrumentation.html
+      #   AppSignal custom instrumentation guide
+      # @see http://docs.appsignal.com/api/event-names.html
+      #   AppSignal event naming guide
+      # @since 2.0.0
+      def instrument_sql(name, title = nil, body = nil, &block)
+        instrument(
+          name,
+          title,
+          body,
+          Appsignal::EventFormatter::SQL_BODY_FORMAT,
+          &block
+        )
+      end
+
+      # Convenience method for skipping instrumentations around a block of code.
+      #
+      # @example
+      #   Appsignal.without_instrumentation do
+      #     # Complex code here
+      #   end
+      #
+      # @yield block of code that shouldn't be instrumented.
+      # @return [Object] Returns the return value of the block.
+      # @since 0.8.7
+      def without_instrumentation
+        Appsignal::Transaction.current.pause! if Appsignal::Transaction.current
+        yield
+      ensure
+        Appsignal::Transaction.current.resume! if Appsignal::Transaction.current
+      end
+    end
+  end
+end