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

.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

._load_config!(env_param = 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.

PRIVATE METHOD. DO NOT USE.

Parameters:

  • env_var (String, NilClass) —

    Used by diagnose CLI to pass through the environment CLI option value.



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/appsignal.rb', line 155

def _load_config!(env_param = nil)
  context = Appsignal::Config::Context.new(
    :env => Config.determine_env(env_param),
    :root_path => Config.determine_root_path
  )
  # If there's a config/appsignal.rb file
  if context.dsl_config_file?
    if config
      # When calling `Appsignal.configure` from an app, not the
      # `config/appsignal.rb` file, with also a Ruby config file present.
      message = "The `Appsignal.configure` helper is called from within an " \
        "app while a `#{context.dsl_config_file}` file is present. " \
        "The `config/appsignal.rb` file is ignored when the " \
        "config is loaded with `Appsignal.configure` from within an app. " \
        "We recommend moving all config to the `config/appsignal.rb` file " \
        "or the `Appsignal.configure` helper in the app."
      Appsignal::Utils::StdoutAndLoggerMessage.warning(message)
    else
      # Load it when no config is present
      load_dsl_config_file(context.dsl_config_file, env_param)
    end
  else
    # Load config if no config file was found and no config is present yet
    # This will load the config/appsignal.yml file automatically
    @config ||= Config.new(context.root_path, context.env)
  end
  # Validate the config, if present
  config&.validate
end

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



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/appsignal.rb', line 390

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



454
455
456
 
# File 'lib/appsignal.rb', line 454

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

.configure(env_param = 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_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:

See Also:



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/appsignal.rb', line 274

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

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

Returns:

  • (Boolean) 


459
460
461
 
# File 'lib/appsignal.rb', line 459

def dsl_config_file_loaded?
  defined?(@dsl_config_file_loaded) ? true : false
end

.extension_loaded? ⇒ Boolean

Returns if the C-extension was loaded properly.

Returns:

  • (Boolean)

See Also:

Since:

  • 1.0.0



415
416
417
 
# File 'lib/appsignal.rb', line 415

def extension_loaded?
  !!extension_loaded
end

.forked ⇒ Object 



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

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. 



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

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. 



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

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



352
353
354
 
# File 'lib/appsignal.rb', line 352

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. 



375
376
377
378
379
380
381
 
# File 'lib/appsignal.rb', line 375

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
144
145
146
147
148
 
# File 'lib/appsignal.rb', line 95

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



425
426
427
 
# File 'lib/appsignal.rb', line 425

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



199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/appsignal.rb', line 199

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