appsignal 2.1.2 → 2.2.0.beta.1

data/appsignal.gemspec

@@ -1,35 +1,36 @@
 # -*- encoding: utf-8 -*-
-require File.expand_path('../lib/appsignal/version', __FILE__)
+require File.expand_path("../lib/appsignal/version", __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = [
-    'Robert Beekman',
-    'Thijs Cadier'
+  gem.authors = [
+    "Robert Beekman",
+    "Thijs Cadier"
   ]
-  gem.email                 = ['support@appsignal.com']
-  gem.description           = 'The official appsignal.com gem'
-  gem.summary               = 'Logs performance and exception data from your app to '\
-                              'appsignal.com'
-  gem.homepage              = 'https://github.com/appsignal/appsignal'
-  gem.license               = 'MIT'
+  gem.email                 = ["support@appsignal.com"]
+  gem.description           = "The official appsignal.com gem"
+  gem.summary               = "Logs performance and exception data from your app to "\
+                              "appsignal.com"
+  gem.homepage              = "https://github.com/appsignal/appsignal"
+  gem.license               = "MIT"
 
-  gem.files                 = `git ls-files`.split($\)
-  gem.executables           = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.files                 = `git ls-files`.split($\) # rubocop:disable Style/SpecialGlobalVars
+  gem.executables           = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.test_files            = gem.files.grep(%r{^(test|spec|features)/})
-  gem.name                  = 'appsignal'
-  gem.require_paths         = ['lib', 'ext']
+  gem.name                  = "appsignal"
+  gem.require_paths         = %w(lib ext)
   gem.version               = Appsignal::VERSION
-  gem.required_ruby_version = '>= 1.9'
+  gem.required_ruby_version = ">= 1.9"
 
   gem.extensions = %w(ext/extconf.rb)
 
-  gem.add_dependency 'rack'
-  gem.add_dependency 'thread_safe'
+  gem.add_dependency "rack"
+  gem.add_dependency "thread_safe"
 
-  gem.add_development_dependency 'rake', '~> 11'
-  gem.add_development_dependency 'rspec', '~> 3.5'
-  gem.add_development_dependency 'pry'
-  gem.add_development_dependency 'timecop'
-  gem.add_development_dependency 'webmock'
-  gem.add_development_dependency 'rubocop', '0.46.0'
+  gem.add_development_dependency "rake", "~> 11"
+  gem.add_development_dependency "rspec", "~> 3.5"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "timecop"
+  gem.add_development_dependency "webmock"
+  gem.add_development_dependency "rubocop", "0.46.0"
+  gem.add_development_dependency "yard"
 end

data/ext/agent.yml

@@ -1,18 +1,18 @@
 ---
-version: '5464697'
+version: f16607c
 triples:
   x86_64-linux:
-    checksum: a70f22af18f50ea1a02adf4ef88f68047b353a185fd100e8a61bc7ade87095bc
-    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/5464697/appsignal-x86_64-linux-all-static.tar.gz
+    checksum: '0479e8b0aeba95360e9fd8cfd7e7f7f4c1a8dfc555f6149c0c35d27593a05193'
+    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/f16607c/appsignal-x86_64-linux-all-static.tar.gz
   i686-linux:
-    checksum: 2101667a3c56dfe78436c4f25b763a1db2028dd6ebe247b64d3c616066269879
-    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/5464697/appsignal-i686-linux-all-static.tar.gz
+    checksum: 3c3c63f26bec0304649cad4fb69410dd6b13313a178f3db7cdeba72b24834715
+    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/f16607c/appsignal-i686-linux-all-static.tar.gz
   x86-linux:
-    checksum: 2101667a3c56dfe78436c4f25b763a1db2028dd6ebe247b64d3c616066269879
-    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/5464697/appsignal-i686-linux-all-static.tar.gz
+    checksum: 3c3c63f26bec0304649cad4fb69410dd6b13313a178f3db7cdeba72b24834715
+    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/f16607c/appsignal-i686-linux-all-static.tar.gz
   x86_64-darwin:
-    checksum: 496f3348ae0e957b2610bb82ae23ab3c9878483a01e447a9f27537c99bd9f69d
-    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/5464697/appsignal-x86_64-darwin-all-static.tar.gz
+    checksum: 853398d93cda5f16edd2a931346f97fedea4c16f729bb987564cfbc29e73ef33
+    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/f16607c/appsignal-x86_64-darwin-all-static.tar.gz
   universal-darwin:
-    checksum: 496f3348ae0e957b2610bb82ae23ab3c9878483a01e447a9f27537c99bd9f69d
-    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/5464697/appsignal-x86_64-darwin-all-static.tar.gz
+    checksum: 853398d93cda5f16edd2a931346f97fedea4c16f729bb987564cfbc29e73ef33
+    download_url: https://appsignal-agent-releases.global.ssl.fastly.net/f16607c/appsignal-x86_64-darwin-all-static.tar.gz

data/ext/appsignal_extension.c

@@ -32,6 +32,10 @@ static VALUE stop(VALUE self) {
   return Qnil;
 }
 
+static VALUE diagnose(VALUE self) {
+  return make_ruby_string(appsignal_diagnose());
+}
+
 static VALUE get_server_state(VALUE self, VALUE key) {
   appsignal_string_t string;
 
@@ -125,7 +129,7 @@ static VALUE record_event(VALUE self, VALUE name, VALUE title, VALUE body, VALUE
   Check_Type(title, T_STRING);
   duration_type = TYPE(duration);
   if (duration_type != T_FIXNUM && duration_type != T_BIGNUM) {
-      rb_raise(rb_eTypeError, "duration should be a Fixnum or Bignum");
+      rb_raise(rb_eTypeError, "duration should be an Integer");
   }
   Check_Type(body_format, T_FIXNUM);
 
@@ -211,13 +215,26 @@ static VALUE set_transaction_action(VALUE self, VALUE action) {
   return Qnil;
 }
 
+static VALUE set_transaction_namespace(VALUE self, VALUE namespace) {
+  appsignal_transaction_t* transaction;
+
+  Check_Type(namespace, T_STRING);
+  Data_Get_Struct(self, appsignal_transaction_t, transaction);
+
+  appsignal_set_transaction_namespace(
+      transaction,
+      make_appsignal_string(namespace)
+  );
+  return Qnil;
+}
+
 static VALUE set_transaction_queue_start(VALUE self, VALUE queue_start) {
   appsignal_transaction_t* transaction;
   int queue_start_type;
 
   queue_start_type = TYPE(queue_start);
   if (queue_start_type != T_FIXNUM && queue_start_type != T_BIGNUM) {
-      rb_raise(rb_eTypeError, "queue_start should be a Fixnum or Bignum");
+      rb_raise(rb_eTypeError, "queue_start should be an Integer");
   }
 
   Data_Get_Struct(self, appsignal_transaction_t, transaction);
@@ -305,18 +322,21 @@ static VALUE data_set_string(VALUE self, VALUE key, VALUE value) {
   return Qnil;
 }
 
-static VALUE data_set_fixnum(VALUE self, VALUE key, VALUE value) {
+static VALUE data_set_integer(VALUE self, VALUE key, VALUE value) {
   appsignal_data_t* data;
+  VALUE value_type = TYPE(value);
 
   Check_Type(key, T_STRING);
-  Check_Type(value, T_FIXNUM);
+  if (value_type != T_FIXNUM && value_type != T_BIGNUM) {
+    rb_raise(rb_eTypeError, "wrong argument type %s (expected Integer)", rb_obj_classname(value));
+  }
 
   Data_Get_Struct(self, appsignal_data_t, data);
 
   appsignal_data_map_set_integer(
     data,
     make_appsignal_string(key),
-    FIX2LONG(value)
+    NUM2LONG(value)
   );
 
   return Qnil;
@@ -404,16 +424,19 @@ static VALUE data_append_string(VALUE self, VALUE value) {
   return Qnil;
 }
 
-static VALUE data_append_fixnum(VALUE self, VALUE value) {
+static VALUE data_append_integer(VALUE self, VALUE value) {
   appsignal_data_t* data;
+  VALUE value_type = TYPE(value);
 
-  Check_Type(value, T_FIXNUM);
+  if (value_type != T_FIXNUM && value_type != T_BIGNUM) {
+    rb_raise(rb_eTypeError, "wrong argument type %s (expected Integer)", rb_obj_classname(value));
+  }
 
   Data_Get_Struct(self, appsignal_data_t, data);
 
   appsignal_data_array_append_integer(
     data,
-    FIX2LONG(value)
+    NUM2LONG(value)
  );
 
   return Qnil;
@@ -579,6 +602,10 @@ static VALUE install_allocation_event_hook() {
   return Qnil;
 }
 
+static VALUE running_in_container() {
+  return appsignal_running_in_container() == 1 ? Qtrue : Qfalse;
+}
+
 void Init_appsignal_extension(void) {
   Appsignal = rb_define_module("Appsignal");
   Extension = rb_define_class_under(Appsignal, "Extension", rb_cObject);
@@ -586,8 +613,10 @@ void Init_appsignal_extension(void) {
   Data = rb_define_class_under(Extension, "Data", rb_cObject);
 
   // Starting and stopping
-  rb_define_singleton_method(Extension, "start", start, 0);
-  rb_define_singleton_method(Extension, "stop",  stop,  0);
+  rb_define_singleton_method(Extension, "start",    start,    0);
+  rb_define_singleton_method(Extension, "stop",     stop,     0);
+  // Diagnostics
+  rb_define_singleton_method(Extension, "diagnose", diagnose, 0);
 
   // Server state
   rb_define_singleton_method(Extension, "get_server_state", get_server_state, 1);
@@ -602,6 +631,7 @@ void Init_appsignal_extension(void) {
   rb_define_method(Transaction, "set_error",       set_transaction_error,       3);
   rb_define_method(Transaction, "set_sample_data", set_transaction_sample_data, 2);
   rb_define_method(Transaction, "set_action",      set_transaction_action,      1);
+  rb_define_method(Transaction, "set_namespace",   set_transaction_namespace,   1);
   rb_define_method(Transaction, "set_queue_start", set_transaction_queue_start, 1);
   rb_define_method(Transaction, "set_metadata",    set_transaction_metadata,    2);
   rb_define_method(Transaction, "finish",          finish_transaction,          1);
@@ -613,7 +643,7 @@ void Init_appsignal_extension(void) {
 
   // Add content to a data map
   rb_define_method(Data, "set_string",  data_set_string,  2);
-  rb_define_method(Data, "set_fixnum",  data_set_fixnum,  2);
+  rb_define_method(Data, "set_integer", data_set_integer, 2);
   rb_define_method(Data, "set_float",   data_set_float,   2);
   rb_define_method(Data, "set_boolean", data_set_boolean, 2);
   rb_define_method(Data, "set_nil",     data_set_nil,     1);
@@ -621,7 +651,7 @@ void Init_appsignal_extension(void) {
 
   // Add content to a data array
   rb_define_method(Data, "append_string",  data_append_string,  1);
-  rb_define_method(Data, "append_fixnum",  data_append_fixnum,  1);
+  rb_define_method(Data, "append_integer", data_append_integer, 1);
   rb_define_method(Data, "append_float",   data_append_float,   1);
   rb_define_method(Data, "append_boolean", data_append_boolean, 1);
   rb_define_method(Data, "append_nil",     data_append_nil,     0);
@@ -635,6 +665,7 @@ void Init_appsignal_extension(void) {
 
   // Event hook installation
   rb_define_singleton_method(Extension, "install_allocation_event_hook", install_allocation_event_hook, 0);
+  rb_define_singleton_method(Extension, "running_in_container?", running_in_container, 0);
 
   // Metrics
   rb_define_singleton_method(Extension, "set_gauge",              set_gauge,              2);

data/ext/extconf.rb

@@ -7,10 +7,10 @@ require "rubygems/package"
 require "yaml"
 require File.expand_path("../../lib/appsignal/version.rb", __FILE__)
 
-EXT_PATH     = File.expand_path("..", __FILE__)
-AGENT_CONFIG = YAML.load(File.read(File.join(EXT_PATH, "agent.yml")))
-ARCH         = "#{Gem::Platform.local.cpu}-#{Gem::Platform.local.os}"
-CA_CERT_PATH = File.join(EXT_PATH, "../resources/cacert.pem")
+EXT_PATH     = File.expand_path("..", __FILE__).freeze
+AGENT_CONFIG = YAML.load(File.read(File.join(EXT_PATH, "agent.yml"))).freeze
+ARCH         = "#{Gem::Platform.local.cpu}-#{Gem::Platform.local.os}".freeze
+CA_CERT_PATH = File.join(EXT_PATH, "../resources/cacert.pem").freeze
 
 def ext_path(path)
   File.join(EXT_PATH, path)
@@ -66,14 +66,14 @@ def install
 
     Gem::Package::TarReader.new(Zlib::GzipReader.open(archive)) do |tar|
       tar.each do |entry|
-        if entry.file?
-          File.open(ext_path(entry.full_name), "wb") do |f|
-            f.write(entry.read)
-          end
+        next unless entry.file?
+
+        File.open(ext_path(entry.full_name), "wb") do |f|
+          f.write(entry.read)
         end
       end
     end
-    FileUtils.chmod(0755, ext_path("appsignal-agent"))
+    FileUtils.chmod(0o755, ext_path("appsignal-agent"))
   end
 
   logger.info "Creating makefile"

data/gemfiles/padrino.gemfile

@@ -1,6 +1,6 @@
 source 'https://rubygems.org'
 
-gem 'padrino', '~> 0.12.0'
+gem 'padrino', '~> 0.13.0'
 gem 'rack', '~> 1.6'
 gem 'activesupport', '~> 4.2'
 

data/lib/appsignal.rb

@@ -2,17 +2,59 @@ require "json"
 require "logger"
 require "securerandom"
 
+# AppSignal for Ruby gem's main module.
+#
+# Provides method to control the AppSignal instrumentation and the system agent.
+# Also provides instrumentation helpers for ease of use.
 module Appsignal
   class << self
     extend Gem::Deprecate
 
-    attr_accessor :config, :extension_loaded
-    attr_writer :logger, :in_memory_log
-
+    # Accessor for the AppSignal configuration.
+    # Return the current AppSignal configuration.
+    #
+    # Can return `nil` if no configuration has been set or automatically loaded
+    # by an automatic integration or by calling {.start}.
+    #
+    # @example
+    #   Appsignal.config
+    #
+    # @example Setting the configuration
+    #   Appsignal.config = Appsignal::Config.new(Dir.pwd, "production")
+    #
+    # @return [Config, nil]
+    # @see Config
+    attr_accessor :config
+    # Accessor for toggle if the AppSignal C-extension is loaded.
+    #
+    # Can be `nil` if extension has not been loaded yet. See
+    # {.extension_loaded?} for a boolean return value.
+    #
+    # @api private
+    # @return [Boolean, nil]
+    # @see Extension
+    # @see extension_loaded?
+    attr_accessor :extension_loaded
+    # @!attribute [rw] logger
+    #   Accessor for the AppSignal logger.
+    #
+    #   If no logger has been set, it will return a "in memory logger", using
+    #   `in_memory_log`. Once AppSignal is started (using {.start}) the
+    #   contents of the "in memory logger" is written to the new logger.
+    #
+    #   @note some classes may have options to set custom loggers. Their
+    #     defaults are pointed to this attribute.
+    #   @api private
+    #   @return [Logger]
+    #   @see start_logger
+    attr_writer :logger
+
+    # @api private
     def extensions
       @extensions ||= []
     end
 
+    # @api private
     def initialize_extensions
       Appsignal.logger.debug("Initializing extensions")
       extensions.each do |extension|
@@ -21,14 +63,39 @@ module Appsignal
       end
     end
 
+    # Start the AppSignal integration.
+    #
+    # Starts AppSignal with the given configuration. If no configuration is set
+    # yet it will try to automatically load the configuration using the
+    # environment loaded from environment variables and the currently working
+    # directory.
+    #
+    # This is not required for the automatic integrations AppSignal offers, but
+    # this is required for all non-automatic integrations and pure Ruby
+    # applications. For more information, see our [integrations
+    # list](http://docs.appsignal.com/ruby/integrations/) and our [Integrating
+    # AppSignal](http://docs.appsignal.com/ruby/instrumentation/integrating-appsignal.html)
+    # guide.
+    #
+    # To start the logger see {.start_logger}.
+    #
+    # @example
+    #   Appsignal.start
+    #
+    # @example with custom loaded configuration
+    #   Appsignal.config = Appsignal::Config.new(Dir.pwd, "production")
+    #   Appsignal.start
+    #
+    # @return [void]
+    # @since 0.7.0
     def start
       unless extension_loaded?
         logger.info("Not starting appsignal, extension is not loaded")
         return
-      else
-        logger.debug("Starting appsignal")
       end
 
+      logger.debug("Starting appsignal")
+
       unless @config
         @config = Config.new(
           Dir.pwd,
@@ -44,7 +111,8 @@ module Appsignal
             Logger::INFO
           end
         if config.active?
-          logger.info("Starting AppSignal #{Appsignal::VERSION} (#{$0}, Ruby #{RUBY_VERSION}, #{RUBY_PLATFORM})")
+          logger.info "Starting AppSignal #{Appsignal::VERSION} "\
+            "(#{$PROGRAM_NAME}, Ruby #{RUBY_VERSION}, #{RUBY_PLATFORM})"
           config.write_to_environment
           Appsignal::Extension.start
           Appsignal::Hooks.load_hooks
@@ -69,14 +137,20 @@ module Appsignal
       end
     end
 
-    def in_memory_log
-      if defined?(@in_memory_log) && @in_memory_log
-        @in_memory_log
-      else
-        @in_memory_log = StringIO.new
-      end
-    end
-
+    # Stop AppSignal's agent.
+    #
+    # Stops the AppSignal agent. Call this before the end of your program to
+    # make sure the agent is stopped as well.
+    #
+    # @example
+    #   Appsignal.start
+    #   # Run your application
+    #   Appsignal.stop
+    #
+    # @param called_by [String] Name of the thing that requested the agent to
+    #   be stopped. Will be used in the AppSignal log file.
+    # @return [void]
+    # @since 1.0.0
     def stop(called_by = nil)
       if called_by
         logger.debug("Stopping appsignal (#{called_by})")
@@ -97,7 +171,7 @@ module Appsignal
       Appsignal::Extension.get_server_state(key)
     end
 
-    # Wrap a transaction with appsignal monitoring.
+    # Wrap a transaction with AppSignal monitoring.
     def monitor_transaction(name, env = {})
       unless active?
         return yield
@@ -110,7 +184,8 @@ module Appsignal
         namespace = Appsignal::Transaction::HTTP_REQUEST
         request   = ::Rack::Request.new(env)
       else
-        logger.error("Unrecognized name '#{name}'") and return
+        logger.error("Unrecognized name '#{name}'")
+        return
       end
       transaction = Appsignal::Transaction.create(
         SecureRandom.uuid,
@@ -131,11 +206,11 @@ module Appsignal
       end
     end
 
-    # Monitor a transaction, stop Appsignal and wait for this single transaction to be
-    # flushed.
+    # 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.
+    # Useful for cases such as Rake tasks and Resque-like systems where a
+    # process is forked and immediately exits after the transaction finishes.
     def monitor_single_transaction(name, env = {}, &block)
       monitor_transaction(name, env, &block)
     ensure
@@ -150,10 +225,49 @@ module Appsignal
     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
+    #
+    # @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 [Exception] The namespace in which the error occurred.
+    #   See also {.set_namespace}.
+    # @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')
+        logger.error("Can't send error, given value is not an exception")
         return
       end
       transaction = Appsignal::Transaction.new(
@@ -167,6 +281,40 @@ module Appsignal
     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.
+    # @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)
       return if !active? ||
           Appsignal::Transaction.current.nil? ||
@@ -176,14 +324,152 @@ module Appsignal
     alias :set_exception :set_error
     alias :add_exception :set_error
 
-    def tag_request(params = {})
+    # 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(params)
+      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 blocks return value.
+    #
+    # @see .instrument_sql Specific helper for SQL queries.
+    # @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
       return_value = yield if block_given?
@@ -191,6 +477,33 @@ module Appsignal
       return_value
     end
 
+    # Instrumentation helper for SQL queries.
+    #
+    # This helper filters out values from SQL queries so you don't have to.
+    #
+    # @example SQL query instrumentation
+    #   Appsignal.instrument_sql("perform.query", nil, "SELECT * FROM ...") do
+    #     # To be instrumented code
+    #   end
+    #
+    # @example SQL query instrumentation
+    #   Appsignal.instrument_sql("perform.query", nil, "WHERE email = 'foo@..'") 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 blocks 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
@@ -225,6 +538,20 @@ module Appsignal
       Appsignal.logger.warn("Distribution value #{value} for key '#{key}' is too big")
     end
 
+    # In memory logger used before any logger is started with {.start_logger}.
+    #
+    # The contents of this logger are flushed to the logger in {.start_logger}.
+    #
+    # @api private
+    # @return [StringIO]
+    def in_memory_log
+      if defined?(@in_memory_log) && @in_memory_log
+        @in_memory_log
+      else
+        @in_memory_log = StringIO.new
+      end
+    end
+
     def logger
       @logger ||= Logger.new(in_memory_log).tap do |l|
         l.level = Logger::INFO
@@ -232,13 +559,24 @@ module Appsignal
       end
     end
 
+    # @api private
     def log_formatter(prefix = nil)
       pre = "#{prefix}: " if prefix
       proc do |severity, datetime, _progname, msg|
-        "[#{datetime.strftime("%Y-%m-%dT%H:%M:%S")} (process) ##{Process.pid}][#{severity}] #{pre}#{msg}\n"
+        "[#{datetime.strftime("%Y-%m-%dT%H:%M:%S")} (process) "\
+          "##{Process.pid}][#{severity}] #{pre}#{msg}\n"
       end
     end
 
+    # Start the AppSignal logger.
+    #
+    # Sets the log level and sets the logger. Uses a file-based logger or the
+    # STDOUT-based logger. See the `:log` configuration option.
+    #
+    # @param path_arg [nil] Deprecated param. Use the `:log_path`
+    #   configuration option instead.
+    # @return [void]
+    # @since 0.7.0
     def start_logger(path_arg = nil)
       if config && config[:log] == "file" && config.log_file_path
         start_file_logger(config.log_file_path)
@@ -262,27 +600,66 @@ module Appsignal
       end
     end
 
+    # Returns if the C-extension was loaded properly.
+    #
+    # @return [Boolean]
+    # @see Extension
+    # @since 1.0.0
     def extension_loaded?
       !!@extension_loaded
     end
 
+    # Returns the active state of the AppSignal integration.
+    #
+    # Conditions apply for AppSignal to be marked as active:
+    #
+    # - There is a config set on the {.config} attribute.
+    # - The set config is active {Config.active?}.
+    # - The AppSignal Extension is loaded {.extension_loaded?}.
+    #
+    # This logic is used within instrument helper such as {.instrument} so it's
+    # not necessary to wrap {.instrument} calls with this method.
+    #
+    # @example Do this
+    #   Appsignal.instrument(..) do
+    #     # Do this
+    #   end
+    #
+    # @example Don't do this
+    #   if Appsignal.active?
+    #     Appsignal.instrument(..) do
+    #       # Don't do this
+    #     end
+    #   end
+    #
+    # @return [Boolean]
+    # @since 0.2.7
     def active?
       config && config.active? && extension_loaded?
     end
 
-    def is_ignored_error?(error)
+    # @deprecated No replacement
+    def is_ignored_error?(error) # rubocop:disable Style/PredicateName
       Appsignal.config[:ignore_errors].include?(error.class.name)
     end
     alias :is_ignored_exception? :is_ignored_error?
     deprecate :is_ignored_error?, :none, 2017, 3
 
-    def is_ignored_action?(action)
+    # @deprecated No replacement
+    def is_ignored_action?(action) # rubocop:disable Style/PredicateName
       Appsignal.config[:ignore_actions].include?(action)
     end
     deprecate :is_ignored_action?, :none, 2017, 3
 
     # 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