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/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/passenger.rb,
lib/appsignal/hooks/shoryuken.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/grape_middleware.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, GarbageCollection, Helpers, Integrations, Loaders, Probes, Rack, System, Utils Classes: AuthCheck, CLI, Config, Demo, Environment, EventFormatter, Extension, Hooks, Logger, Marker, SampleData, Span, Transaction, Transmitter

Constant Summary collapse

VERSION = 
"4.1.1"

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

.extension_loaded ⇒ Boolean?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Returns:

  • (Boolean, nil)

See Also:



46
47
48
 
# File 'lib/appsignal.rb', line 46

def extension_loaded
  @extension_loaded
end

.internal_logger ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



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

attr_writer :internal_logger

Class Method Details

._start_logger ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Start the AppSignal internal logger.

Sets the log level and sets the logger. Uses a file-based logger or the STDOUT-based logger. See the ‘:log` configuration option.



332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/appsignal.rb', line 332

def _start_logger
  if config && config[:log] == "file" && config.log_file_path
    start_internal_file_logger(config.log_file_path)
  else
    start_internal_stdout_logger
  end

  internal_logger.level =
    if config
      config.log_level
    else
      Appsignal::Config::DEFAULT_LOG_LEVEL
    end
  return unless @in_memory_logger

  messages = @in_memory_logger.messages_for_level(internal_logger.level)
  internal_logger << messages.join
  @in_memory_logger = nil
end

.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



396
397
398
 
# File 'lib/appsignal.rb', line 396

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

.configure(env = nil, root_path: nil) {|Config| ... } ⇒ 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 (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:

See Also:



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/appsignal.rb', line 234

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

  if config && ((env.nil? || config.env == env.to_s) &&
      (root_path.nil? || config.root_path == root_path))
    config
  else
    @config = Config.new(
      root_path || Config.determine_root_path,
      Config.determine_env(env)
    )
  end

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

  yield config_dsl
  config.merge_dsl_options(config_dsl.dsl_options)
end

.extension_loaded? ⇒ Boolean

Returns if the C-extension was loaded properly.

Returns:

  • (Boolean)

See Also:

Since:

  • 1.0.0



357
358
359
 
# File 'lib/appsignal.rb', line 357

def extension_loaded?
  !!extension_loaded
end

.forked ⇒ Object 



258
259
260
261
262
263
264
 
# File 'lib/appsignal.rb', line 258

def forked
  return unless active?

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

.get_server_state(key) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



299
300
301
 
# File 'lib/appsignal.rb', line 299

def get_server_state(key)
  Appsignal::Extension.get_server_state(key)
end

.in_memory_logger ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



304
305
306
307
308
309
 
# File 'lib/appsignal.rb', line 304

def in_memory_logger
  @in_memory_logger ||=
    Appsignal::Utils::IntegrationMemoryLogger.new.tap do |l|
      l.formatter = log_formatter("appsignal")
    end
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



294
295
296
 
# File 'lib/appsignal.rb', line 294

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

.log_formatter(prefix = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



317
318
319
320
321
322
323
 
# File 'lib/appsignal.rb', line 317

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"
  end
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



95
96
97
98
99
100
101
102
103
104
105
106
107
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
 
# File 'lib/appsignal.rb', line 95

def start # rubocop:disable Metrics/AbcSize
  if ENV.fetch("_APPSIGNAL_DIAGNOSE", false)
    internal_logger.warn("Skipping start in diagnose context")
    return
  end

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

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

  internal_logger.debug("Loading AppSignal gem")

  @config ||= Config.new(Config.determine_root_path, Config.determine_env)
  @config.validate

  _start_logger

  if config.valid?
    if config.active?
      @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, not active for #{config.env}")
    end
  else
    internal_logger.error("Not starting, no valid config for this environment")
  end
end

.started? ⇒ Boolean

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

Returns:

  • (Boolean)

See Also:

Since:

  • 3.12.0



367
368
369
 
# File 'lib/appsignal.rb', line 367

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



159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/appsignal.rb', line 159

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

.testing? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/appsignal.rb', line 66

def testing?
  false
end