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/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/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/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/event_formatter/sequel/sql_formatter.rb,
lib/appsignal/event_formatter/faraday/request_formatter.rb,
lib/appsignal/integrations/active_support_notifications.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,
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.7.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.

Examples:

Appsignal.config

Returns:

See Also:



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

def config
  @config
end

.config_error ⇒ nil, 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:

  • (nil, Exception) 


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

def config_error
  @config_error
end

.internal_logger=(value) ⇒ Object

Sets the attribute internal_logger

Parameters:

  • value —

    the value to set the attribute internal_logger to.



63
 
# File 'lib/appsignal.rb', line 63

attr_writer :internal_logger

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.

Examples:

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)

Since:

  • 0.2.7



502
503
504
 
# File 'lib/appsignal.rb', line 502

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

.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.

Raises:



522
523
524
525
526
527
528
529
530
531
532
533
534
 
# File 'lib/appsignal.rb', line 522

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) {|config_dsl| ... } ⇒ 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.

Examples:

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)

Parameters:

  • env_param (String, Symbol) (defaults to: nil) —

    The environment to load.

  • root_path (String) (defaults to: nil) —

    The path to look the ‘config/appsignal.yml` config file in. Defaults to the current working directory.

Yields:

  • (config_dsl) —

    Gives the configuration DSL instance to the block.

Yield Parameters:

See Also:



318
319
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
 
# File 'lib/appsignal.rb', line 318

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?
    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."
    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.

Returns:

  • (Boolean)

See Also:

  • Extension

Since:

  • 1.0.0



463
464
465
 
# File 'lib/appsignal.rb', line 463

def extension_loaded?
  !!extension_loaded
end

.forked ⇒ void

This method returns an undefined value.



362
363
364
365
366
367
368
369
 
# File 'lib/appsignal.rb', line 362

def forked
  return unless active?

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

.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.

Examples:

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) —

    Name of the integration to load.

Since:

  • 3.12.0



399
400
401
402
 
# File 'lib/appsignal.rb', line 399

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

.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](docs.appsignal.com/ruby/integrations/) and our [Integrating AppSignal](docs.appsignal.com/ruby/instrumentation/integrating-appsignal.html) guide.

Examples:

Appsignal.start

with custom loaded configuration

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

Since:

  • 0.7.0



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 # rubocop:disable Metrics/AbcSize
  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.

Returns:

  • (Boolean)

See Also:

  • Extension

Since:

  • 3.12.0



473
474
475
 
# File 'lib/appsignal.rb', line 473

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.

Examples:

Appsignal.start
# Run your application
Appsignal.stop

Parameters:

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

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

Since:

  • 1.0.0



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

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