Module: Appsignal
- Extended by:
- Gem::Deprecate
- Defined in:
- lib/appsignal.rb,
lib/appsignal/cli.rb,
lib/appsignal/demo.rb,
lib/appsignal/hooks.rb,
lib/appsignal/utils.rb,
lib/appsignal/config.rb,
lib/appsignal/marker.rb,
lib/appsignal/system.rb,
lib/appsignal/version.rb,
lib/appsignal/cli/demo.rb,
lib/appsignal/minutely.rb,
lib/appsignal/extension.rb,
lib/appsignal/hooks/que.rb,
lib/appsignal/auth_check.rb,
lib/appsignal/hooks/puma.rb,
lib/appsignal/hooks/rake.rb,
lib/appsignal/cli/helpers.rb,
lib/appsignal/cli/install.rb,
lib/appsignal/hooks/redis.rb,
lib/appsignal/transaction.rb,
lib/appsignal/transmitter.rb,
lib/appsignal/cli/diagnose.rb,
lib/appsignal/hooks/sequel.rb,
lib/appsignal/hooks/sidekiq.rb,
lib/appsignal/hooks/unicorn.rb,
lib/appsignal/hooks/net_http.rb,
lib/appsignal/event_formatter.rb,
lib/appsignal/extension/jruby.rb,
lib/appsignal/hooks/celluloid.rb,
lib/appsignal/hooks/passenger.rb,
lib/appsignal/hooks/shoryuken.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/action_cable.rb,
lib/appsignal/integrations/grape.rb,
lib/appsignal/integrations/resque.rb,
lib/appsignal/cli/notify_of_deploy.rb,
lib/appsignal/integrations/padrino.rb,
lib/appsignal/integrations/railtie.rb,
lib/appsignal/utils/params_sanitizer.rb,
lib/appsignal/hooks/mongo_ruby_driver.rb,
lib/appsignal/integrations/webmachine.rb,
lib/appsignal/rack/streaming_listener.rb,
lib/appsignal/integrations/data_mapper.rb,
lib/appsignal/js_exception_transaction.rb,
lib/appsignal/rack/js_exception_catcher.rb,
lib/appsignal/rack/rails_instrumentation.rb,
lib/appsignal/garbage_collection_profiler.rb,
lib/appsignal/rack/generic_instrumentation.rb,
lib/appsignal/rack/sinatra_instrumentation.rb,
lib/appsignal/utils/query_params_sanitizer.rb,
lib/appsignal/integrations/mongo_ruby_driver.rb,
lib/appsignal/integrations/resque_active_job.rb,
lib/appsignal/integrations/delayed_job_plugin.rb,
lib/appsignal/hooks/active_support_notifications.rb,
lib/appsignal/event_formatter/moped/query_formatter.rb,
lib/appsignal/event_formatter/faraday/request_formatter.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/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 instrumentation helpers for ease of use.
Defined Under Namespace
Modules: Grape, Integrations, Rack, System, Utils Classes: AuthCheck, CLI, Capistrano, Config, Demo, EventFormatter, Extension, GarbageCollectionProfiler, Hooks, JSExceptionTransaction, Marker, Minutely, StreamWrapper, Transaction, Transmitter
Constant Summary collapse
- VERSION =
"2.5.1".freeze
Class Attribute Summary collapse
-
.config ⇒ Config?
Accessor for the AppSignal configuration.
-
.extension_loaded ⇒ Boolean?
private
Accessor for toggle if the AppSignal C-extension is loaded.
-
.logger ⇒ Logger
private
Accessor for the AppSignal logger.
Class Method Summary collapse
-
.active? ⇒ Boolean
Returns the active state of the AppSignal integration.
- .add_distribution_value(key, value) ⇒ Object
-
.extension_loaded? ⇒ Boolean
Returns if the C-extension was loaded properly.
- .extensions ⇒ Object private
- .forked ⇒ Object
- .get_server_state(key) ⇒ Object
-
.in_memory_log ⇒ StringIO
private
In memory logger used before any logger is started with Appsignal.start_logger.
- .increment_counter(key, value = 1) ⇒ Object
- .initialize_extensions ⇒ Object private
-
.instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT) { ... } ⇒ Object
Instrument helper for AppSignal.
-
.instrument_sql(name, title = nil, body = nil) { ... } ⇒ Object
Instrumentation helper for SQL queries.
-
.is_ignored_action?(action) ⇒ Boolean
deprecated
Deprecated.
No replacement
-
.is_ignored_error?(error) ⇒ Boolean
(also: is_ignored_exception?)
deprecated
Deprecated.
No replacement
-
.listen_for_error(tags = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) { ... } ⇒ Object
(also: listen_for_exception)
Listen for an error to occur and send it to AppSignal.
- .log_formatter(prefix = nil) ⇒ Object private
-
.monitor_single_transaction(name, env = {}, &block) ⇒ Object
Monitor a transaction, stop AppSignal and wait for this single transaction to be flushed.
-
.monitor_transaction(name, env = {}) { ... } ⇒ Object
Creates an AppSignal transaction for the given block.
-
.send_error(error, tags = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) ⇒ void
(also: send_exception)
Send an error to AppSignal regardless of the context.
-
.set_action(action) ⇒ void
Set a custom action name for the current transaction.
-
.set_error(exception, tags = nil, namespace = nil) ⇒ void
(also: set_exception, add_exception)
Set an error on the current transaction.
- .set_gauge(key, value) ⇒ Object
- .set_host_gauge(key, value) ⇒ Object
-
.set_namespace(namespace) ⇒ void
Set a custom namespace for the current transaction.
- .set_process_gauge(key, value) ⇒ Object
-
.start ⇒ void
Start the AppSignal integration.
-
.start_logger(path_arg = nil) ⇒ void
Start the AppSignal logger.
-
.stop(called_by = nil) ⇒ void
Stop AppSignal's agent.
-
.tag_request(tags = {}) ⇒ void
(also: tag_job)
Set tags on the current transaction.
- .testing? ⇒ Boolean private
-
.without_instrumentation { ... } ⇒ Object
Convenience method for skipping instrumentations around a block of code.
Class Attribute Details
.config ⇒ Config?
Accessor for the AppSignal configuration. Return the current AppSignal configuration.
Can return nil
if no configuration has been set or automatically loaded
by an automatic integration or by calling start.
27 28 29 |
# File 'lib/appsignal.rb', line 27 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.
37 38 39 |
# File 'lib/appsignal.rb', line 37 def extension_loaded @extension_loaded end |
.logger ⇒ Logger
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.
some classes may have options to set custom loggers. Their defaults are pointed to this attribute.
Accessor for the AppSignal logger.
If no logger has been set, it will return a "in memory logger", using
in_memory_log
. Once AppSignal is started (using start) the
contents of the "in memory logger" is written to the new logger.
50 |
# File 'lib/appsignal.rb', line 50 attr_writer :logger |
Class Method Details
.active? ⇒ Boolean
Returns the active state of the AppSignal integration.
Conditions apply for AppSignal to be marked as active:
- There is a config set on the config attribute.
- The set config is active Appsignal::Config#active?.
- The AppSignal Extension is loaded extension_loaded?.
This logic is used within instrument helper such as instrument so it's not necessary to wrap instrument calls with this method.
734 735 736 |
# File 'lib/appsignal.rb', line 734 def active? config && config.active? && extension_loaded? end |
.add_distribution_value(key, value) ⇒ Object
632 633 634 635 636 |
# File 'lib/appsignal.rb', line 632 def add_distribution_value(key, value) Appsignal::Extension.add_distribution_value(key.to_s, value.to_f) rescue RangeError Appsignal.logger.warn("Distribution value #{value} for key '#{key}' is too big") end |
.extension_loaded? ⇒ Boolean
Returns if the C-extension was loaded properly.
705 706 707 |
# File 'lib/appsignal.rb', line 705 def extension_loaded? !!extension_loaded end |
.extensions ⇒ 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.
53 54 55 |
# File 'lib/appsignal.rb', line 53 def extensions @extensions ||= [] end |
.forked ⇒ Object
168 169 170 171 172 173 |
# File 'lib/appsignal.rb', line 168 def forked return unless active? Appsignal.start_logger logger.debug("Forked process, resubscribing and restarting extension") Appsignal::Extension.start end |
.get_server_state(key) ⇒ Object
175 176 177 |
# File 'lib/appsignal.rb', line 175 def get_server_state(key) Appsignal::Extension.get_server_state(key) end |
.in_memory_log ⇒ StringIO
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.
In memory logger used before any logger is started with start_logger.
The contents of this logger are flushed to the logger in start_logger.
644 645 646 647 648 649 650 |
# File 'lib/appsignal.rb', line 644 def in_memory_log if defined?(@in_memory_log) && @in_memory_log @in_memory_log else @in_memory_log = StringIO.new end end |
.increment_counter(key, value = 1) ⇒ Object
626 627 628 629 630 |
# File 'lib/appsignal.rb', line 626 def increment_counter(key, value = 1) Appsignal::Extension.increment_counter(key.to_s, value) rescue RangeError Appsignal.logger.warn("Counter value #{value} for key '#{key}' is too big") end |
.initialize_extensions ⇒ 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.
58 59 60 61 62 63 64 |
# File 'lib/appsignal.rb', line 58 def initialize_extensions Appsignal.logger.debug("Initializing extensions") extensions.each do |extension| Appsignal.logger.debug("Initializing #{extension}") extension.initializer end end |
.instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT) { ... } ⇒ Object
Instrument helper for AppSignal.
For more help, read our custom instrumentation guide, listed under "See also".
570 571 572 573 574 575 |
# File 'lib/appsignal.rb', line 570 def instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT) Appsignal::Transaction.current.start_event yield if block_given? ensure Appsignal::Transaction.current.finish_event(name, title, body, body_format) end |
.instrument_sql(name, title = nil, body = nil) { ... } ⇒ Object
Instrumentation helper for SQL queries.
This helper filters out values from SQL queries so you don't have to.
604 605 606 |
# File 'lib/appsignal.rb', line 604 def instrument_sql(name, title = nil, body = nil, &block) instrument(name, title, body, Appsignal::EventFormatter::SQL_BODY_FORMAT, &block) end |
.is_ignored_action?(action) ⇒ Boolean
No replacement
746 747 748 |
# File 'lib/appsignal.rb', line 746 def is_ignored_action?(action) # rubocop:disable Style/PredicateName Appsignal.config[:ignore_actions].include?(action) end |
.is_ignored_error?(error) ⇒ Boolean Also known as: is_ignored_exception?
No replacement
739 740 741 |
# File 'lib/appsignal.rb', line 739 def is_ignored_error?(error) # rubocop:disable Style/PredicateName Appsignal.config[:ignore_errors].include?(error.class.name) end |
.listen_for_error(tags = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) { ... } ⇒ Object Also known as: listen_for_exception
Listen for an error to occur and send it to AppSignal.
Uses send_error to directly send the error in a separate transaction. Does not add the error to the current transaction.
Make sure that AppSignal is integrated in your application beforehand.
AppSignal won't record errors unless Appsignal::Config#active? is true
.
308 309 310 311 312 313 |
# File 'lib/appsignal.rb', line 308 def listen_for_error( = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) yield rescue Exception => error # rubocop:disable Lint/RescueException send_error(error, , namespace) raise error 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.
660 661 662 663 664 665 666 |
# File 'lib/appsignal.rb', line 660 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 |
.monitor_single_transaction(name, env = {}, &block) ⇒ Object
Monitor a transaction, stop AppSignal and wait for this single transaction to be flushed.
Useful for cases such as Rake tasks and Resque-like systems where a process is forked and immediately exits after the transaction finishes.
275 276 277 278 279 |
# File 'lib/appsignal.rb', line 275 def monitor_single_transaction(name, env = {}, &block) monitor_transaction(name, env, &block) ensure stop("monitor_single_transaction") end |
.monitor_transaction(name, env = {}) { ... } ⇒ Object
Creates an AppSignal transaction for the given block.
If AppSignal is not active? it will still execute the block, but not create a transaction for it.
A event is created for this transaction with the name given in the name
argument. The event name must start with either perform_job
or
process_action
to differentiate between the "web" and "background"
namespace. Custom namespaces are not supported by this helper method.
This helper method also captures any exception that occurs in the given block.
The other (request) env
argument hash keys, not listed here, can be
found on the Appsignal::Transaction::ENV_METHODS array.
Each of these keys are available as keys in the env
hash argument.
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 |
# File 'lib/appsignal.rb', line 234 def monitor_transaction(name, env = {}) unless active? return yield end if name.start_with?("perform_job".freeze) namespace = Appsignal::Transaction::BACKGROUND_JOB request = Appsignal::Transaction::GenericRequest.new(env) elsif name.start_with?("process_action".freeze) namespace = Appsignal::Transaction::HTTP_REQUEST request = ::Rack::Request.new(env) else logger.error("Unrecognized name '#{name}'") return end transaction = Appsignal::Transaction.create( SecureRandom.uuid, namespace, request ) begin Appsignal.instrument(name) do yield end rescue Exception => error # rubocop:disable Lint/RescueException transaction.set_error(error) raise error ensure transaction.set_http_or_background_action(request.env) transaction.set_http_or_background_queue_start Appsignal::Transaction.complete_current! end end |
.send_error(error, tags = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) ⇒ void Also known as: send_exception
This method returns an undefined value.
Send an error to AppSignal regardless of the context.
Records and send the exception to AppSignal.
This instrumentation helper does not require a transaction to be active, it starts a new transaction by itself.
Use set_error if your want to add an exception to the current transaction.
Note: Does not do anything if AppSignal is not active or when the "error" is not a class extended from Ruby's Exception class.
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
# File 'lib/appsignal.rb', line 355 def send_error(error, = nil, namespace = Appsignal::Transaction::HTTP_REQUEST) return unless active? unless error.is_a?(Exception) logger.error("Can't send error, given value is not an exception") return end transaction = Appsignal::Transaction.new( SecureRandom.uuid, namespace, Appsignal::Transaction::GenericRequest.new({}) ) transaction.() if transaction.set_error(error) transaction.complete end |
.set_action(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.
444 445 446 447 448 449 |
# File 'lib/appsignal.rb', line 444 def set_action(action) return if !active? || Appsignal::Transaction.current.nil? || action.nil? Appsignal::Transaction.current.set_action(action) end |
.set_error(exception, tags = nil, namespace = nil) ⇒ void Also known as: set_exception, add_exception
This method returns an undefined value.
Set an error on the current transaction.
Note: Does not do anything if AppSignal is not active, no transaction is currently active or when the "error" is not a class extended from Ruby's Exception class.
410 411 412 413 414 415 416 417 418 |
# File 'lib/appsignal.rb', line 410 def set_error(exception, = nil, namespace = nil) return if !active? || Appsignal::Transaction.current.nil? || exception.nil? transaction = Appsignal::Transaction.current transaction.set_error(exception) transaction.() if transaction.set_namespace(namespace) if namespace end |
.set_gauge(key, value) ⇒ Object
608 609 610 611 612 |
# File 'lib/appsignal.rb', line 608 def set_gauge(key, value) Appsignal::Extension.set_gauge(key.to_s, value.to_f) rescue RangeError Appsignal.logger.warn("Gauge value #{value} for key '#{key}' is too big") end |
.set_host_gauge(key, value) ⇒ Object
614 615 616 617 618 |
# File 'lib/appsignal.rb', line 614 def set_host_gauge(key, value) Appsignal::Extension.set_host_gauge(key.to_s, value.to_f) rescue RangeError Appsignal.logger.warn("Host gauge value #{value} for key '#{key}' is too big") end |
.set_namespace(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.
483 484 485 486 487 488 |
# File 'lib/appsignal.rb', line 483 def set_namespace(namespace) return if !active? || Appsignal::Transaction.current.nil? || namespace.nil? Appsignal::Transaction.current.set_namespace(namespace) end |
.set_process_gauge(key, value) ⇒ Object
620 621 622 623 624 |
# File 'lib/appsignal.rb', line 620 def set_process_gauge(key, value) Appsignal::Extension.set_process_gauge(key.to_s, value.to_f) rescue RangeError Appsignal.logger.warn("Process gauge value #{value} for key '#{key}' is too big") 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 and our Integrating AppSignal guide.
To start the logger see start_logger.
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 96 def start # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity unless extension_loaded? logger.info("Not starting appsignal, extension is not loaded") return end logger.debug("Starting appsignal") unless @config @config = Config.new( Dir.pwd, ENV["APPSIGNAL_APP_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] ) end if config.valid? logger.level = if config[:debug] Logger::DEBUG else Logger::INFO end if config.active? 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::EventFormatter.initialize_formatters initialize_extensions if config[:enable_allocation_tracking] && !Appsignal::System.jruby? Appsignal::Extension.install_allocation_event_hook end if config[:enable_gc_instrumentation] GC::Profiler.enable Appsignal::Minutely.add_gc_probe end Appsignal::Minutely.start if config[:enable_minutely_probes] else logger.info("Not starting, not active for #{config.env}") end else logger.error("Not starting, no valid config for this environment") end end |
.start_logger(path_arg = nil) ⇒ void
This method returns an undefined value.
Start the AppSignal logger.
Sets the log level and sets the logger. Uses a file-based logger or the
STDOUT-based logger. See the :log
configuration option.
677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 |
# File 'lib/appsignal.rb', line 677 def start_logger(path_arg = nil) if config && config[:log] == "file" && config.log_file_path start_file_logger(config.log_file_path) else start_stdout_logger end logger.level = if config && config[:debug] Logger::DEBUG else Logger::INFO end if in_memory_log logger << in_memory_log.string end if path_arg logger.info("Setting the path in start_logger has no effect anymore, set it in the config instead") end 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.
159 160 161 162 163 164 165 166 |
# File 'lib/appsignal.rb', line 159 def stop(called_by = nil) if called_by logger.debug("Stopping appsignal (#{called_by})") else logger.debug("Stopping appsignal") end Appsignal::Extension.stop end |
.tag_request(tags = {}) ⇒ void Also known as: tag_job
This method returns an undefined value.
Set tags on the current transaction.
Tags are extra bits of information that are added to transaction and appear on sample details pages on AppSignal.com.
523 524 525 526 527 528 |
# File 'lib/appsignal.rb', line 523 def tag_request( = {}) return unless active? transaction = Appsignal::Transaction.current return false unless transaction transaction.() 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.
67 68 69 |
# File 'lib/appsignal.rb', line 67 def testing? false end |
.without_instrumentation { ... } ⇒ Object
Convenience method for skipping instrumentations around a block of code.
761 762 763 764 765 766 |
# File 'lib/appsignal.rb', line 761 def without_instrumentation Appsignal::Transaction.current.pause! if Appsignal::Transaction.current yield ensure Appsignal::Transaction.current.resume! if Appsignal::Transaction.current end |