Module: Appsignal

Extended by:
Helpers::Instrumentation, Helpers::Metrics
Defined in:
lib/appsignal.rb,
lib/appsignal/cli.rb,
lib/appsignal/demo.rb,
lib/appsignal/rack.rb,
lib/appsignal/span.rb,
lib/appsignal/hooks.rb,
lib/appsignal/utils.rb,
lib/appsignal/config.rb,
lib/appsignal/logger.rb,
lib/appsignal/marker.rb,
lib/appsignal/probes.rb,
lib/appsignal/system.rb,
lib/appsignal/loaders.rb,
lib/appsignal/version.rb,
lib/appsignal/check_in.rb,
lib/appsignal/cli/demo.rb,
lib/appsignal/extension.rb,
lib/appsignal/hooks/gvl.rb,
lib/appsignal/hooks/mri.rb,
lib/appsignal/hooks/que.rb,
lib/appsignal/auth_check.rb,
lib/appsignal/hooks/http.rb,
lib/appsignal/hooks/puma.rb,
lib/appsignal/hooks/rake.rb,
lib/appsignal/probes/gvl.rb,
lib/appsignal/probes/mri.rb,
lib/appsignal/utils/data.rb,
lib/appsignal/utils/json.rb,
lib/appsignal/cli/helpers.rb,
lib/appsignal/cli/install.rb,
lib/appsignal/environment.rb,
lib/appsignal/hooks/excon.rb,
lib/appsignal/hooks/redis.rb,
lib/appsignal/sample_data.rb,
lib/appsignal/transaction.rb,
lib/appsignal/transmitter.rb,
lib/appsignal/cli/diagnose.rb,
lib/appsignal/hooks/resque.rb,
lib/appsignal/hooks/sequel.rb,
lib/appsignal/utils/ndjson.rb,
lib/appsignal/check_in/cron.rb,
lib/appsignal/custom_marker.rb,
lib/appsignal/hooks/at_exit.rb,
lib/appsignal/hooks/faraday.rb,
lib/appsignal/hooks/sidekiq.rb,
lib/appsignal/hooks/unicorn.rb,
lib/appsignal/loaders/grape.rb,
lib/appsignal/check_in/event.rb,
lib/appsignal/hooks/net_http.rb,
lib/appsignal/loaders/hanami.rb,
lib/appsignal/probes/helpers.rb,
lib/appsignal/probes/sidekiq.rb,
lib/appsignal/event_formatter.rb,
lib/appsignal/extension/jruby.rb,
lib/appsignal/helpers/metrics.rb,
lib/appsignal/hooks/celluloid.rb,
lib/appsignal/hooks/ownership.rb,
lib/appsignal/hooks/passenger.rb,
lib/appsignal/hooks/shoryuken.rb,
lib/appsignal/internal_errors.rb,
lib/appsignal/loaders/padrino.rb,
lib/appsignal/loaders/sinatra.rb,
lib/appsignal/hooks/active_job.rb,
lib/appsignal/hooks/webmachine.rb,
lib/appsignal/integrations/que.rb,
lib/appsignal/hooks/data_mapper.rb,
lib/appsignal/hooks/delayed_job.rb,
lib/appsignal/hooks/dry_monitor.rb,
lib/appsignal/integrations/http.rb,
lib/appsignal/integrations/puma.rb,
lib/appsignal/integrations/rake.rb,
lib/appsignal/rack/body_wrapper.rb,
lib/appsignal/check_in/scheduler.rb,
lib/appsignal/cli/diagnose/paths.rb,
lib/appsignal/cli/diagnose/utils.rb,
lib/appsignal/garbage_collection.rb,
lib/appsignal/hooks/action_cable.rb,
lib/appsignal/hooks/redis_client.rb,
lib/appsignal/integrations/excon.rb,
lib/appsignal/integrations/redis.rb,
lib/appsignal/rack/event_handler.rb,
lib/appsignal/utils/rails_helper.rb,
lib/appsignal/hooks/action_mailer.rb,
lib/appsignal/integrations/resque.rb,
lib/appsignal/hooks/code_ownership.rb,
lib/appsignal/integrations/faraday.rb,
lib/appsignal/integrations/railtie.rb,
lib/appsignal/integrations/sidekiq.rb,
lib/appsignal/integrations/unicorn.rb,
lib/appsignal/integrations/net_http.rb,
lib/appsignal/rack/event_middleware.rb,
lib/appsignal/rack/grape_middleware.rb,
lib/appsignal/integrations/ownership.rb,
lib/appsignal/integrations/shoryuken.rb,
lib/appsignal/rack/hanami_middleware.rb,
lib/appsignal/helpers/instrumentation.rb,
lib/appsignal/hooks/mongo_ruby_driver.rb,
lib/appsignal/integrations/webmachine.rb,
lib/appsignal/integrations/data_mapper.rb,
lib/appsignal/integrations/dry_monitor.rb,
lib/appsignal/rack/abstract_middleware.rb,
lib/appsignal/utils/integration_logger.rb,
lib/appsignal/integrations/action_cable.rb,
lib/appsignal/integrations/redis_client.rb,
lib/appsignal/rack/rails_instrumentation.rb,
lib/appsignal/integrations/code_ownership.rb,
lib/appsignal/utils/sample_data_sanitizer.rb,
lib/appsignal/rack/sinatra_instrumentation.rb,
lib/appsignal/utils/query_params_sanitizer.rb,
lib/appsignal/integrations/mongo_ruby_driver.rb,
lib/appsignal/integrations/delayed_job_plugin.rb,
lib/appsignal/rack/instrumentation_middleware.rb,
lib/appsignal/utils/integration_memory_logger.rb,
lib/appsignal/utils/stdout_and_logger_message.rb,
lib/appsignal/event_formatter/rom/sql_formatter.rb,
lib/appsignal/hooks/active_support_notifications.rb,
lib/appsignal/hooks/active_support_event_reporter.rb,
lib/appsignal/event_formatter/sequel/sql_formatter.rb,
lib/appsignal/integrations/active_support_notifications.rb,
lib/appsignal/integrations/active_support_event_reporter.rb,
lib/appsignal/integrations/capistrano/capistrano_2_tasks.rb,
lib/appsignal/event_formatter/active_record/sql_formatter.rb,
lib/appsignal/event_formatter/action_view/render_formatter.rb,
lib/appsignal/event_formatter/elastic_search/search_formatter.rb,
lib/appsignal/event_formatter/view_component/render_formatter.rb,
lib/appsignal/event_formatter/mongo_ruby_driver/query_formatter.rb,
lib/appsignal/event_formatter/active_record/instantiation_formatter.rb,
sig/appsignal.rbs,
ext/appsignal_extension.c

Overview

AppSignal for Ruby gem's main module.

Provides method to control the AppSignal instrumentation and the system agent. Also provides direct access to instrumentation helpers (from Helpers::Instrumentation) and metrics helpers (from Helpers::Metrics) for ease of use.

Defined Under Namespace

Modules: CheckIn, Helpers, Probes Classes: Config, CustomMarker, Demo, EventFormatter, InternalError, Logger, NotStartedError, Transaction

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"4.9.0"

Class Attribute Summary collapse

Class Method Summary collapse

Methods included from Helpers::Metrics

add_distribution_value, increment_counter, set_gauge

Methods included from Helpers::Instrumentation

add_breadcrumb, add_custom_data, add_headers, add_params, add_session_data, add_tags, ignore_instrumentation_events, instrument, instrument_sql, monitor, monitor_and_stop, report_error, send_error, set_action, set_empty_params!, set_error, set_namespace

Class Attribute Details

.config ⇒ Config? (readonly)

The loaded AppSignal configuration. Returns the current AppSignal configuration.

Can return nil if no configuration has been set or automatically loaded by an automatic integration or by calling start.

Appsignal.config

@see configure

@see Config

Returns:



35
36
37
 
# File 'lib/appsignal.rb', line 35

def config
  @config
end

.config_error ⇒ Exception? (readonly) Also known as: config_error?

Returns the error that was encountered while loading the appsignal.rb config file.

It does not include any error that occurred while loading the appsignal.yml file.

If the value is nil, no error was encountered or AppSignal wasn't started yet.

Returns:

  • (Exception, nil) 


75
76
77
 
# File 'lib/appsignal.rb', line 75

def config_error
  @config_error
end

Class Method Details

.active? ⇒ Boolean

Returns the active state of the AppSignal integration.

Conditions apply for AppSignal to be marked as active:

This logic is used within instrument helper such as instrument so it's not necessary to wrap instrument calls with this method.

Do this

Appsignal.instrument(..) do
  # Do this
end

Don't do this

if Appsignal.active?
  Appsignal.instrument(..) do
    # Don't do this
  end
end

Returns:

  • (Boolean) 


506
507
508
 
# File 'lib/appsignal.rb', line 506

def active?
  config&.active? && extension_loaded?
end

.add_breadcrumb ⇒ Object

Add breadcrumbs to the transaction.

Breadcrumbs can be used to trace what path a user has taken before encountering an error.

Only the last 20 added breadcrumbs will be saved.

@param category — category of breadcrumb e.g. "UI", "Network", "Navigation", "Console".

@param action — name of breadcrumb e.g "The user clicked a button", "HTTP 500 from http://blablabla.com"

@param message — optional message in string format

@param metadata — key/value metadata in <string, string> format

@param time — time of breadcrumb, should respond to .to_i defaults to Time.now.utc

Appsignal.add_breadcrumb(
  "Navigation",
  "http://blablabla.com",
  "",
  { :response => 200 },
  Time.now.utc
)
Appsignal.add_breadcrumb(
  "Network",
  "[GET] http://blablabla.com",
  "",
  { :response => 500 }
)
Appsignal.add_breadcrumb(
  "UI",
  "closed modal(change_password)",
  "User closed modal without actions"
)

@see https://docs.appsignal.com/ruby/instrumentation/breadcrumbs.html — Breadcrumb reference



815
 
# File 'sig/appsignal.rbs', line 815

def self.add_breadcrumb: (

.add_custom_data ⇒ void

This method returns an undefined value.

Add custom data to the current transaction.

Add extra information about the request or background that cannot be expressed in tags, like nested data structures.

If the root data type changes between calls of this method, the last method call is stored.

@param data — Custom data to add to the transaction.

Add Hash data

Appsignal.add_custom_data(:user => { :locale => "en" })

Merges Hash data

Appsignal.add_custom_data(:abc => "def")
Appsignal.add_custom_data(:xyz => "...")
# The custom data is: { :abc => "def", :xyz => "..." }

Add Array data

Appsignal.add_custom_data([
  "array with data",
  "other value",
  :options => { :verbose => true }
])

Merges Array data

Appsignal.add_custom_data([1, 2, 3])
Appsignal.add_custom_data([4, 5, 6])
# The custom data is: [1, 2, 3, 4, 5, 6]

Mixing of root data types is not supported

Appsignal.add_custom_data(:abc => "def")
Appsignal.add_custom_data([1, 2, 3])
# The custom data is: [1, 2, 3]

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

Parameters:



607
 
# File 'sig/appsignal.rbs', line 607

def self.add_custom_data: ((::Hash[Object, Object] | ::Array[Object]) data) -> void

.add_distribution_value ⇒ void

This method returns an undefined value.

Report a distribution metric.

@param name — The name of the metric.

@param value — The value of the metric.

@param tags — The tags for the metric. The Hash keys can be either a String or a Symbol. The tag values can be a String, Symbol, Integer, Float, TrueClass or FalseClass.

@see https://docs.appsignal.com/metrics/custom.html — Metrics documentation

Parameters:

  • name (String, Symbol)
  • value (Integer, Float)
  • tags (::Hash[String, Object]) 


242
 
# File 'sig/appsignal.rbs', line 242

def self.add_distribution_value: ((String | Symbol) name, (Integer | Float) value, ?::Hash[String, Object] tags) -> void

.add_headers ⇒ void

This method returns an undefined value.

Add request headers to the current transaction.

Request headers are automatically added by most of our integrations. It should not be necessary to call this method unless you want to also report different request headers.

To filter request headers, see our request header filtering guide.

When both the request_headers argument and a block is given to this method, the block is leading and the argument will not be used.

@param headers — The request headers to add to the transaction.

Add request headers

Appsignal.add_headers("PATH_INFO" => "/some-path")
# The request headers will include:
# { "PATH_INFO" => "/some-path" }

Calling add_headers multiple times merge the values

Appsignal.add_headers("PATH_INFO" => "/some-path")
Appsignal.add_headers("HTTP_USER_AGENT" => "Firefox")
# The request headers will include:
# { "PATH_INFO" => "/some-path", "HTTP_USER_AGENT" => "Firefox" }

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-headers.html — Request headers filtering guide

Parameters:

  • headers (::Hash[String, Object], nil) 


774
 
# File 'sig/appsignal.rbs', line 774

def self.add_headers: (?::Hash[String, Object]? headers) ?{ () -> ::Hash[String, Object] } -> void

.add_params ⇒ void

This method returns an undefined value.

Add parameters to the current transaction.

Parameters are automatically added by most of our integrations. It should not be necessary to call this method unless you want to report different parameters.

This method accepts both Hash and Array parameter types:

  • Hash parameters will be merged when called multiple times
  • Array parameters will be concatenated when called multiple times
  • Mixing Hash and Array types will use the latest type (and log a warning)

To filter parameters, see our parameter filtering guide.

When both the params argument and a block is given to this method, the block is leading and the argument will not be used.

@param params — The parameters to add to the transaction.

Add Hash parameters

Appsignal.add_params("param1" => "value1")
# The parameters include: { "param1" => "value1" }

Add Array parameters

Appsignal.add_params(["item1", "item2"])
# The parameters include: ["item1", "item2"]

Calling add_params multiple times with Hashes merges values

Appsignal.add_params("param1" => "value1")
Appsignal.add_params("param2" => "value2")
# The parameters include:
# { "param1" => "value1", "param2" => "value2" }

Calling add_params multiple times with Arrays concatenates values

Appsignal.add_params(["item1"])
Appsignal.add_params(["item2"])
# The parameters include: ["item1", "item2"]

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-parameters.html — Parameter filtering guide

Parameters:



692
 
# File 'sig/appsignal.rbs', line 692

def self.add_params: (?(::Hash[String, Object] | ::Array[Object])? params) ?{ () -> (::Hash[String, Object] | ::Array[Object]) } -> void

.add_session_data ⇒ void

This method returns an undefined value.

Add session data to the current transaction.

Session data is automatically added by most of our integrations. It should not be necessary to call this method unless you want to report different session data.

To filter session data, see our session data filtering guide.

When both the session_data argument and a block is given to this method, the bock is leading and the argument will not be used.

@param session_data — The session data to add to the transaction.

Add session data

Appsignal.add_session_data("session" => "data")
# The session data will include:
# { "session" => "data" }

Calling add_session_data multiple times merge the values

Appsignal.add_session_data("session" => "data")
Appsignal.add_session_data("other" => "value")
# The session data will include:
# { "session" => "data", "other" => "value" }

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-session-data.html — Session data filtering guide

Parameters:

  • session_data (::Hash[String, Object], nil) 


741
 
# File 'sig/appsignal.rbs', line 741

def self.add_session_data: (?::Hash[String, Object]? session_data) ?{ () -> ::Hash[String, Object] } -> void

.add_tags ⇒ void

This method returns an undefined value.

Add tags to the current transaction.

Tags are extra bits of information that are added to transaction and appear on sample details pages on AppSignal.com.

When this method is called multiple times, it will merge the tags.

@param tags — Collection of tags to add to the transaction.

Appsignal.add_tags(:locale => "en", :user_id => 1)
Appsignal.add_tags("locale" => "en")
Appsignal.add_tags("user_id" => 1)

Nested hashes are not supported

# Bad
Appsignal.add_tags(:user => { :locale => "en" })

in a Rails controller

class SomeController < ApplicationController
  before_action :add_appsignal_tags

  def add_appsignal_tags
    Appsignal.add_tags(:locale => I18n.locale)
  end
end

@see https://docs.appsignal.com/ruby/instrumentation/tagging.html — Tagging guide

Parameters:



642
 
# File 'sig/appsignal.rbs', line 642

def self.add_tags: (?::Hash[Object, Object] tags) -> void

.check_if_started! ⇒ void

This method returns an undefined value.

Check if the AppSignal Ruby gem has started successfully.

If it has not (yet) started or encountered an error in the config/appsignal.rb config file during start up that prevented it from starting, it will raise a NotStartedError.

If there an error raised from the config file, it will include it as the error cause of the raised error.



526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/appsignal.rb', line 526

def check_if_started!
  return if started?

  begin
    raise config_error if config_error?
  rescue
    # Raise the NotStartedError and make the config error the error cause
    raise NotStartedError, config_error
  end

  # Raise the NotStartedError as normal
  raise NotStartedError
end

.configure(env_param = nil, root_path: nil) ⇒ void

This method returns an undefined value.

Configure the AppSignal Ruby gem using a DSL.

Pass a block to the configure method to configure the Ruby gem.

Each config option defined in our docs can be fetched, set and modified via a helper method in the given block.

After AppSignal has started using start, the configuration can not be modified. Any calls to this helper will be ignored.

This helper should not be used to configure multiple environments, like done in the YAML file. Configure the environment you want active when the application starts.

@param env_param — The environment to load.

@param root_path — The path to look the config/appsignal.yml config file in. Defaults to the current working directory.

Configure AppSignal for the application

Appsignal.configure do |config|
  config.path = "/the/app/path"
  config.active = ENV["APP_ACTIVE"] == "true"
  config.push_api_key = File.read("appsignal_key.txt").chomp
  config.ignore_actions = ENDPOINTS.select { |e| e.public? }.map(&:name)
  config.request_headers << "MY_CUSTOM_HEADER"
end

Configure AppSignal for the application and select the environment

Appsignal.configure(:production) do |config|
  config.active = true
end

Automatically detects the app environment

# Tries to determine the app environment automatically from the
# environment and the libraries it integrates with.
ENV["RACK_ENV"] = "production"

Appsignal.configure do |config|
  config.env # => "production"
end

Calling configure multiple times for different environments resets the configuration

Appsignal.configure(:development) do |config|
  config.ignore_actions = ["My action"]
end

Appsignal.configure(:production) do |config|
  config.ignore_actions # => []
end

Load config without a block

# This will require either ENV vars being set
# or the config/appsignal.yml being present
Appsignal.configure
# Or for the environment given as an argument
Appsignal.configure(:production)

@see config

@see Config

@see https://docs.appsignal.com/ruby/configuration.html — Configuration guide

@see https://docs.appsignal.com/ruby/configuration/options.html — Configuration options

Parameters:

  • env_param (?(String | Symbol), nil) (defaults to: nil)
  • root_path: (String, nil) (defaults to: nil) 


320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/appsignal.rb', line 320

def configure(env_param = nil, root_path: nil)
  if Appsignal.started?
    Appsignal.internal_logger
      .warn("AppSignal is already started. Ignoring `Appsignal.configure` call.")
    return
  end

  root_path_param = root_path
  if params_match_loaded_config?(env_param, root_path_param)
    config
  else
    @config = Config.new(
      root_path_param || Config.determine_root_path,
      Config.determine_env(env_param),
      # If in the context of an `config/appsignal.rb` config file, do not
      # load the `config/appsignal.yml` file.
      # The `.rb` file is a replacement for the `.yml` file so it shouldn't
      # load both.
      :load_yaml_file => !config_file_context?
    )
  end

  # When calling `Appsignal.configure` from a Rails initializer and a YAML
  # file is present. We will not load the YAML file in the future.
  if !config_file_context? && config.yml_config_file?
    caller_location = external_caller_location
    message = "The `Appsignal.configure` helper is called while a " \
      "`config/appsignal.yml` file is present. In future versions the " \
      "`config/appsignal.yml` file will be ignored when loading the " \
      "config. We recommend moving all config to the " \
      "`config/appsignal.rb` file, or the `Appsignal.configure` helper " \
      "in Rails initializer file, and remove the " \
      "`config/appsignal.yml` file."
    message += "\n  Called from: #{caller_location}" if caller_location
    Appsignal::Utils::StdoutAndLoggerMessage.warning(message)
  end

  config_dsl = Appsignal::Config::ConfigDSL.new(config)
  return unless block_given?

  yield config_dsl
  config.merge_dsl_options(config_dsl.dsl_options)
  nil
end

.extension_loaded? ⇒ Boolean

Returns if the C-extension was loaded properly.

@see Extension

Returns:

  • (Boolean) 


467
468
469
 
# File 'lib/appsignal.rb', line 467

def extension_loaded?
  !!extension_loaded
end

.forked ⇒ void

This method returns an undefined value.



366
367
368
369
370
371
372
373
 
# File 'lib/appsignal.rb', line 366

def forked
  return unless active?

  Appsignal._start_logger
  internal_logger.debug("Forked process, resubscribing and restarting extension")
  Appsignal::Extension.start
  nil
end

.ignore_instrumentation_events ⇒ void

This method returns an undefined value.

Convenience method for ignoring instrumentation events in a block of code.

  • This helper ignores events, like those created Appsignal.instrument, within this block. This includes custom instrumentation and events recorded by AppSignal integrations for requests, database queries, view rendering, etc.
  • The time spent in the block is still reported on the transaction.
  • Errors and metrics are reported from within this block.

@return — Returns the return value of the block. Return nil if the block returns nil or no block is given.

Appsignal.instrument "my_event.my_group" do
  # Complex code here
end
Appsignal.ignore_instrumentation_events do
  Appsignal.instrument "my_ignored_event.my_ignored_group" do
    # Complex code here
  end
end

# Only the "my_event.my_group" instrumentation event is reported.

@see https://docs.appsignal.com/ruby/instrumentation/ignore-instrumentation.html — Ignore instrumentation guide



930
 
# File 'sig/appsignal.rbs', line 930

def self.ignore_instrumentation_events: () ?{ () -> Object } -> Object?

.increment_counter ⇒ void

This method returns an undefined value.

Report a counter metric.

@param name — The name of the metric.

@param value — The value of the metric.

@param tags — The tags for the metric. The Hash keys can be either a String or a Symbol. The tag values can be a String, Symbol, Integer, Float, TrueClass or FalseClass.

@see https://docs.appsignal.com/metrics/custom.html — Metrics documentation

Parameters:

  • name (String, Symbol)
  • value (?(Integer | Float))
  • tags (::Hash[String, Object]) 


231
 
# File 'sig/appsignal.rbs', line 231

def self.increment_counter: ((String | Symbol) name, ?(Integer | Float) value, ?::Hash[String, Object] tags) -> void

.instrument ⇒ Object

Instrument helper for AppSignal.

For more help, read our custom instrumentation guide, listed under "See also".

@param name — Name of the instrumented event. Read our event naming guide listed under "See also".

@param title — Human readable name of the event.

@param body — Value of importance for the event, such as the server against an API call is made.

@param body_format — Enum for the type of event that is instrumented. Accepted values are Appsignal::EventFormatter::DEFAULT and Appsignal::EventFormatter::SQL_BODY_FORMAT, but we recommend you use instrument_sql instead of Appsignal::EventFormatter::SQL_BODY_FORMAT.

@return — Returns the block's return value.

Simple instrumentation

Appsignal.instrument("fetch.issue_fetcher") do
  # To be instrumented code
end

Instrumentation with title and body

Appsignal.instrument(
  "fetch.issue_fetcher",
  "Fetching issue",
  "GitHub API"
) do
  # To be instrumented code
end

@see .instrument_sql

@see https://docs.appsignal.com/ruby/instrumentation/instrumentation.html — AppSignal custom instrumentation guide

@see https://docs.appsignal.com/api/event-names.html — AppSignal event naming guide



861
 
# File 'sig/appsignal.rbs', line 861

def self.instrument: (

.instrument_sql ⇒ Object

Instrumentation helper for SQL queries.

This helper filters out values from SQL queries so you don't have to.

@param name — Name of the instrumented event. Read our event naming guide listed under "See also".

@param title — Human readable name of the event.

@param body — SQL query that's being executed.

@return — Returns the block's return value.

SQL query instrumentation

body = "SELECT * FROM ..."
Appsignal.instrument_sql("perform.query", nil, body) do
  # To be instrumented code
end

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

@see .instrument

@see https://docs.appsignal.com/ruby/instrumentation/instrumentation.html — AppSignal custom instrumentation guide

@see https://docs.appsignal.com/api/event-names.html — AppSignal event naming guide

Parameters:

  • name (String)
  • title (String, nil)
  • body (String, nil)

Returns:



901
 
# File 'sig/appsignal.rbs', line 901

def self.instrument_sql: (String name, ?String? title, ?String? body) -> Object

.load(integration_name) ⇒ void

This method returns an undefined value.

Load an AppSignal integration.

Load one of the supported integrations via our loader system. This will set config defaults and integratie with the library if AppSignal is active upon start.

@param integration_name — Name of the integration to load.

Load Sinatra integrations

# First load the integration
Appsignal.load(:sinatra)
# Start AppSignal
Appsignal.start

Load Sinatra integrations and define custom config

# First load the integration
Appsignal.load(:sinatra)

# Customize config
Appsignal.configure do |config|
  config.ignore_actions = ["GET /ping"]
end

# Start AppSignal
Appsignal.start

Parameters:

  • integration_name (String, Symbol) 


403
404
405
406
 
# File 'lib/appsignal.rb', line 403

def load(integration_name)
  Loaders.load(integration_name)
  nil
end

.monitor ⇒ void

This method returns an undefined value.

Monitor a block of code with AppSignal.

This is a helper to create an AppSignal transaction, track any errors that may occur and complete the transaction.

This helper is recommended to be used in Ruby scripts and parts of an app not already instrumented by AppSignal's automatic instrumentations.

Use this helper in combination with our instrument helper to track instrumentation events.

If AppSignal is not active (active?) it will still execute the block, but not create a transaction for it.

@param namespace — The namespace to set on the new transaction. Defaults to the 'web' namespace. This will not update the active transaction's namespace if monitor is called when another transaction is already active.

@param action — The action name for the transaction. The action name is required to be set for the transaction to be reported. The argument can be set to nil or :set_later if the action is set within the block with Appsignal::Helpers::Instrumentation#set_action. This will not update the active transaction's action if monitor is called when another transaction is already active.

@return — The value of the given block is returned. Returns nil if there already is a transaction active and no block was given.

Instrument a block of code

Appsignal.monitor(
  :namespace => "my_namespace",
  :action => "MyClass#my_method"
) do
  # Some code
end

Instrument a block of code using the default namespace

Appsignal.monitor(
  :action => "MyClass#my_method"
) do
  # Some code
end

Instrument a block of code with an instrumentation event

Appsignal.monitor(
  :namespace => "my_namespace",
  :action => "MyClass#my_method"
) do
  Appsignal.instrument("some_event.some_group") do
    # Some code
  end
end

Set the action name in the monitor block

Appsignal.monitor(
  :action => nil
) do
  # Some code

  Appsignal.set_action("GET /resource/:id")
end

Set the action name in the monitor block

Appsignal.monitor(
  :action => :set_later # Explicit placeholder
) do
  # Some code

  Appsignal.set_action("GET /resource/:id")
end

Set custom metadata on the transaction

Appsignal.monitor(
  :namespace => "my_namespace",
  :action => "MyClass#my_method"
) do
  # Some code

  Appsignal.add_tags(:tag1 => "value1", :tag2 => "value2")
  Appsignal.add_params(:param1 => "value1", :param2 => "value2")
end

Call monitor within monitor will do nothing

Appsignal.monitor(
  :namespace => "my_namespace",
  :action => "MyClass#my_method"
) do
  # This will _not_ update the namespace and action name
  Appsignal.monitor(
    :namespace => "my_other_namespace",
    :action => "MyOtherClass#my_other_method"
  ) do
    # Some code

    # The reported namespace will be "my_namespace"
    # The reported action will be "MyClass#my_method"
  end
end

@see https://docs.appsignal.com/ruby/instrumentation/background-jobs.html — Monitor guide

Parameters:

  • action: (String, Symbol, NilClass)
  • namespace: (String, Symbol, nil) 


352
 
# File 'sig/appsignal.rbs', line 352

def self.monitor: (action: (String | Symbol | NilClass), ?namespace: (String | Symbol)?) ?{ () -> Object } -> Object?

.monitor_and_stop ⇒ void

This method returns an undefined value.

Instrument a block of code and stop AppSignal.

Useful for cases such as one-off scripts where there is no long running process active and the data needs to be sent after the process exists.

Acts the same way as monitor. See that method for more documentation.

@param namespace — The namespace to set on the new transaction. Defaults to the 'web' namespace. This will not update the active transaction's namespace if monitor is called when another transaction is already active.

@param action — The action name for the transaction. The action name is required to be set for the transaction to be reported. The argument can be set to nil or :set_later if the action is set within the block with Appsignal::Helpers::Instrumentation#set_action. This will not update the active transaction's action if monitor is called when another transaction is already active.

@return — The value of the given block is returned.

@see monitor

Parameters:

  • action: (String, Symbol, NilClass)
  • namespace: (String, Symbol, nil) 


369
 
# File 'sig/appsignal.rbs', line 369

def self.monitor_and_stop: (action: (String | Symbol | NilClass), ?namespace: (String | Symbol)?) ?{ () -> Object } -> Object?

.report_error ⇒ void

This method returns an undefined value.

Report an error to AppSignal.

If a transaction is currently active, it will report the error on the current transaction. If no transaction is active, it will report the error on a new transaction.

If a transaction is active and the transaction already has an error reported on it, it will report multiple errors, up to a maximum of 10 errors.

If a block is given to this method, the metadata set in this block will only be applied to the transaction created for the given error. The block will be called when the transaction is completed, which can be much later than when Appsignal::Helpers::Instrumentation#report_error is called.

Note: If AppSignal is not active, no error is reported.

Note: If the given exception argument is not an Exception subclass, it will not be reported.

@param exception — The error to add to the current transaction.

class SomeController < ApplicationController
  def create
    # Do something that breaks
  rescue => error
    Appsignal.report_error(error)
  end
end

Add more metadata to transaction

Appsignal.report_error(error) do
  Appsignal.set_namespace("my_namespace")
  Appsignal.set_action("my_action_name")
  Appsignal.add_params(:search_query => params[:search_query])
  Appsignal.add_tags(:key => "value")
end

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide

Parameters:

  • exception (Exception) 


501
 
# File 'sig/appsignal.rbs', line 501

def self.report_error: (Exception exception) ?{ (Transaction transaction) -> void } -> void

.send_error ⇒ void

This method returns an undefined value.

Send an error to AppSignal regardless of the context.

We recommend using the Appsignal::Helpers::Instrumentation#report_error helper instead.

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.

@param error — The error to send to AppSignal.

Send an exception

begin
  raise "oh no!"
rescue => e
  Appsignal.send_error(e)
end

Add more metadata to transaction

Appsignal.send_error(e) do
  Appsignal.set_namespace("my_namespace")
  Appsignal.set_action("my_action_name")
  Appsignal.add_params(:search_query => params[:search_query])
  Appsignal.add_tags(:key => "value")
end

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide

Parameters:

  • error (Exception) 


408
 
# File 'sig/appsignal.rbs', line 408

def self.send_error: (Exception error) ?{ (Transaction transaction) -> void } -> void

.set_action ⇒ void

This method returns an undefined value.

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.

@param action

in a Rails controller

class SomeController < ApplicationController
  before_action :set_appsignal_action

  def set_appsignal_action
    Appsignal.set_action("DynamicController#dynamic_method")
  end
end

Parameters:

  • action (String) 


524
 
# File 'sig/appsignal.rbs', line 524

def self.set_action: (String action) -> void

.set_empty_params! ⇒ void

This method returns an undefined value.

Mark the parameters sample data to be set as an empty value.

Use this helper to unset request parameters / background job arguments and not report any for this transaction.

If parameters would normally be added by AppSignal instrumentations of libraries, these parameters will not be added to the Transaction.

Calling Appsignal::Helpers::Instrumentation#add_params after this helper will add new parameters to the transaction.

@see Transaction#set_empty_params!

@see Transaction#set_params_if_nil



708
 
# File 'sig/appsignal.rbs', line 708

def self.set_empty_params!: () -> void

.set_error ⇒ void

This method returns an undefined value.

Set an error on the current transaction.

We recommend using the Appsignal::Helpers::Instrumentation#report_error helper instead.

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.

@param exception — The error to add to the current transaction.

Manual instrumentation of set_error.

# Manually starting AppSignal here
# Manually starting a transaction here.
begin
  raise "oh no!"
rescue => e
  Appsignal.set_error(e)
end
# Manually completing the transaction here.
# Manually stopping AppSignal here

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

Add more metadata to transaction

Appsignal.set_error(e) do
  Appsignal.set_namespace("my_namespace")
  Appsignal.set_action("my_action_name")
  Appsignal.add_params(:search_query => params[:search_query])
  Appsignal.add_tags(:key => "value")
end

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide

Parameters:

  • exception (Exception) 


456
 
# File 'sig/appsignal.rbs', line 456

def self.set_error: (Exception exception) ?{ (Transaction transaction) -> void } -> void

.set_gauge ⇒ void

This method returns an undefined value.

Report a gauge metric.

@param name — The name of the metric.

@param value — The value of the metric.

@param tags — The tags for the metric. The Hash keys can be either a String or a Symbol. The tag values can be a String, Symbol, Integer, Float, TrueClass or FalseClass.

@see https://docs.appsignal.com/metrics/custom.html — Metrics documentation

Parameters:

  • name (String, Symbol)
  • value (Integer, Float)
  • tags (::Hash[String, Object]) 


220
 
# File 'sig/appsignal.rbs', line 220

def self.set_gauge: ((String | Symbol) name, (Integer | Float) value, ?::Hash[String, Object] tags) -> void

.set_namespace ⇒ void

This method returns an undefined value.

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.

@param namespace

create a custom admin namespace

class AdminController < ApplicationController
  before_action :set_appsignal_namespace

  def set_appsignal_namespace
    Appsignal.set_namespace("admin")
  end
end

@see https://docs.appsignal.com/guides/namespaces.html — Grouping with namespaces guide

Parameters:

  • namespace (String) 


559
 
# File 'sig/appsignal.rbs', line 559

def self.set_namespace: (String namespace) -> void

.start ⇒ void

This method returns an undefined value.

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 and our Integrating AppSignal guide.

Appsignal.start

with custom loaded configuration

Appsignal.configure(:production) do |config|
  config.ignore_actions = ["My action"]
end
Appsignal.start



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/appsignal.rb', line 108

def start
  if ENV.fetch("_APPSIGNAL_DIAGNOSE", false)
    internal_logger.info("Skipping start in diagnose context")
    return
  end

  if started?
    internal_logger.warn("Ignoring call to Appsignal.start after AppSignal has started")
    return
  end

  if config_file_context?
    internal_logger.warn(
      "Ignoring call to Appsignal.start in config file context."
    )
    return
  end

  unless extension_loaded?
    internal_logger.info("Not starting AppSignal, extension is not loaded")
    return
  end

  internal_logger.debug("Loading AppSignal gem")

  _load_config!
  _start_logger

  if config.active_for_env?
    if config.valid?
      @started = true
      internal_logger.info "Starting AppSignal #{Appsignal::VERSION} " \
        "(#{$PROGRAM_NAME}, Ruby #{RUBY_VERSION}, #{RUBY_PLATFORM})"
      config.write_to_environment
      Appsignal::Extension.start
      Appsignal::Hooks.load_hooks
      Appsignal::Loaders.start

      if config[:enable_allocation_tracking] && !Appsignal::System.jruby?
        Appsignal::Extension.install_allocation_event_hook
        Appsignal::Environment.report_enabled("allocation_tracking")
      end

      Appsignal::Probes.start if config[:enable_minutely_probes]

      collect_environment_metadata
      @config.freeze
    else
      internal_logger.info("Not starting, no valid config for this environment")
    end
  else
    internal_logger.info("Not starting, not active for #{config.env}")
  end
  nil
end

.started? ⇒ Boolean

Returns if start has been called before with a valid config to start AppSignal.

@see Extension

Returns:

  • (Boolean) 


477
478
479
 
# File 'lib/appsignal.rb', line 477

def started?
  defined?(@started) ? @started : false
end

.stop(called_by = nil) ⇒ void

This method returns an undefined value.

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.

@param called_by — Name of the thing that requested the agent to be stopped. Will be used in the AppSignal log file.

Appsignal.start
# Run your application
Appsignal.stop

Parameters:

  • called_by (String, nil) (defaults to: nil) 


243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/appsignal.rb', line 243

def stop(called_by = nil)
  Thread.new do
    if called_by
      internal_logger.info("Stopping AppSignal (#{called_by})")
    else
      internal_logger.info("Stopping AppSignal")
    end
    Appsignal::Extension.stop
    Appsignal::Probes.stop
    Appsignal::CheckIn.stop
  end.join
  nil
end