Module: Appsignal::Helpers::Instrumentation

Included in:
Appsignal
Defined in:
lib/appsignal/helpers/instrumentation.rb

Instance Method Summary collapse

Instance Method Details

#add_breadcrumb(category, action, message = "", metadata = {}, time = Time.now.utc) ⇒ void

This method returns an undefined value.

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.

Examples:

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

Parameters:

  • category (String) —

    category of breadcrumb e.g. “UI”, “Network”, “Navigation”, “Console”.

  • action (String) —

    name of breadcrumb e.g “The user clicked a button”, “HTTP 500 from blablabla.com”

  • message (String) (defaults to: "") —

    optional message in string format

  • metadata (Hash<String, String>) (defaults to: {}) —

    key/value metadata in <string, string> format

  • time (Time) (defaults to: Time.now.utc) —

    time of breadcrumb, should respond to ‘.to_i` defaults to `Time.now.utc`

See Also:

Since:

  • 2.12.0



752
753
754
755
756
757
758
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 752

def add_breadcrumb(category, action, message = "", metadata = {}, time = Time.now.utc)
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_breadcrumb(category, action, message, metadata, time)
end

#add_custom_data(data) ⇒ void Also known as: set_custom_data

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.

Examples:

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]

Parameters:

See Also:

Since:

  • 4.0.0



493
494
495
496
497
498
499
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 493

def add_custom_data(data)
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_custom_data(data)
end

#add_headers(headers = nil) { ... } ⇒ void Also known as: set_headers

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.

Examples:

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

Parameters:

  • headers (Hash<String, Object>) (defaults to: nil) —

    The request headers to add to the transaction.

Yields:

  • This block is called when the transaction is sampled. The block’s return value will become the new request headers.

Yield Returns:

See Also:

Since:

  • 4.0.0



704
705
706
707
708
709
710
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 704

def add_headers(headers = nil, &block)
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_headers(headers, &block)
end

#add_params(params = nil) { ... } ⇒ void Also known as: set_params

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.

Examples:

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

Parameters:

  • params (Hash<String, Object>, Array<Object>) (defaults to: nil) —

    The parameters to add to the transaction.

Yields:

  • This block is called when the transaction is sampled. The block’s return value will become the new parameters.

Yield Returns:

See Also:

Since:

  • 4.0.0



596
597
598
599
600
601
602
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 596

def add_params(params = nil, &block)
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_params(params, &block)
end

#add_session_data(session_data = nil) { ... } ⇒ void Also known as: set_session_data

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.

Examples:

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

Parameters:

  • session_data (Hash<String, Object>) (defaults to: nil) —

    The session data to add to the transaction.

Yields:

  • This block is called when the transaction is sampled. The block’s return value will become the new session data.

Yield Returns:

See Also:

Since:

  • 4.0.0



662
663
664
665
666
667
668
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 662

def add_session_data(session_data = nil, &block)
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_session_data(session_data, &block)
end

#add_tags(tags = {}) ⇒ void Also known as: tag_request, tag_job, set_tags

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.

Examples:

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

Parameters:

  • tags (Hash<Object, Object>) (defaults to: {}) —

    Collection of tags to add to the transaction.

Options Hash (tags):

  • :any (String, Symbol, Integer) —

    The name of the tag as a Symbol.

  • "any" (String, Symbol, Integer) —

    The name of the tag as a String.

See Also:

Since:

  • 4.0.0



538
539
540
541
542
543
544
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 538

def add_tags(tags = {})
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.add_tags(tags)
end

#ignore_instrumentation_events { ... } ⇒ Object?

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.

Examples:

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.

Yields:

  • block of code that shouldn’t be instrumented.

Yield Returns:

  • (Object) —

    The return value of the block

Returns:

  • (Object, nil) —

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

See Also:

Since:

  • 3.10.0



879
880
881
882
883
884
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 879

def ignore_instrumentation_events
  Appsignal::Transaction.current&.pause!
  yield if block_given?
ensure
  Appsignal::Transaction.current&.resume!
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”.

Examples:

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

Parameters:

  • name (String) —

    Name of the instrumented event. Read our event naming guide listed under “See also”.

  • title (String, nil) (defaults to: nil) —

    Human readable name of the event.

  • body (String, nil) (defaults to: nil) —

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

  • body_format (Integer) (defaults to: Appsignal::EventFormatter::DEFAULT) —

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

Yields:

  • yields the given block of code instrumented in an AppSignal

    event.

Returns:

  • (Object) —

    Returns the block’s return value.

See Also:

Since:

  • 1.3.0



798
799
800
801
802
803
804
805
806
807
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 798

def instrument(
  name,
  title = nil,
  body = nil,
  body_format = Appsignal::EventFormatter::DEFAULT,
  &block
)
  Appsignal::Transaction.current
    .instrument(name, title, body, body_format, &block)
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.

Examples:

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

Parameters:

  • name (String) —

    Name of the instrumented event. Read our event naming guide listed under “See also”.

  • title (String, nil) (defaults to: nil) —

    Human readable name of the event.

  • body (String, nil) (defaults to: nil) —

    SQL query that’s being executed.

Yields:

  • yields the given block of code instrumented in an AppSignal

    event.

Returns:

  • (Object) —

    Returns the block’s return value.

See Also:

Since:

  • 2.0.0



839
840
841
842
843
844
845
846
847
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 839

def instrument_sql(name, title = nil, body = nil, &block)
  instrument(
    name,
    title,
    body,
    Appsignal::EventFormatter::SQL_BODY_FORMAT,
    &block
  )
end

#monitor(action:, namespace: nil) { ... } ⇒ Object?

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 (Appsignal.active?) it will still execute the block, but not create a transaction for it.

Examples:

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

Parameters:

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

    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.

  • action (String, Symbol, NilClass) —

    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 #set_action. This will not update the active transaction’s action if #monitor is called when another transaction is already active.

Yields:

  • The block to monitor.

Yield Returns:

  • (Object) —

    The return value of the block

Returns:

  • (Object, nil) —

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

Raises:

  • (Exception) —

    Any exception that occurs within the given block is re-raised by this method.

See Also:

Since:

  • 3.11.0



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/helpers/instrumentation.rb', line 115

def monitor(action:, namespace: nil)
  return yield unless Appsignal.active?

  has_parent_transaction = Appsignal::Transaction.current?
  if has_parent_transaction
    callers = caller
    Appsignal::Utils::StdoutAndLoggerMessage.warning \
      "A transaction is active around this 'Appsignal.monitor' call. " \
        "Calling `Appsignal.monitor` in another `Appsignal.monitor` block has no effect. " \
        "The namespace and action are not updated for the active transaction." \
        "Did you mean to use `Appsignal.instrument`? " \
        "Update the 'Appsignal.monitor' call in: #{callers.first}"
    return yield if block_given?

    return
  end

  transaction =
    if has_parent_transaction
      Appsignal::Transaction.current
    else
      Appsignal::Transaction.create(namespace || Appsignal::Transaction::HTTP_REQUEST)
    end

  begin
    yield if block_given?
  rescue Exception => error # rubocop:disable Lint/RescueException
    transaction.set_error(error)
    raise error
  ensure
    transaction.set_action_if_nil(action.to_s) if action && action != :set_later
    Appsignal::Transaction.complete_current!
  end
end

#monitor_and_stop(action:, namespace: nil) { ... } ⇒ Object?

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.

Parameters:

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

    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.

  • action (String, Symbol, NilClass) —

    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 #set_action. This will not update the active transaction’s action if #monitor is called when another transaction is already active.

Yields:

  • The block to monitor.

Yield Returns:

  • (Object) —

    The return value of the block

Returns:

  • (Object, nil) —

    The value of the given block is returned.

Raises:

  • (Exception) —

    Any exception that occurs within the given block is re-raised by this method.

See Also:



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 178

def monitor_and_stop(action:, namespace: nil, &block)
  Appsignal::Utils::StdoutAndLoggerMessage.warning \
    "The `Appsignal.monitor_and_stop` helper is deprecated. " \
      "Use the `Appsignal.monitor` along with our `enable_at_exit_hook` " \
      "option instead."

  monitor(:namespace => namespace, :action => action, &block)
ensure
  Appsignal.stop("monitor_and_stop")
end

#report_error(exception) {|transaction| ... } ⇒ void Also known as: report_exception

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

Examples:

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

Parameters:

  • exception (Exception) —

    The error to add to the current transaction.

Yields:

  • (transaction) —

    yields block to allow modification of the transaction.

Yield Parameters:

  • transaction (Transaction) —

    yields the AppSignal transaction used to report the error.

See Also:

Since:

  • 4.0.0



359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 359

def report_error(exception, &block)
  unless exception.is_a?(Exception)
    Appsignal.internal_logger.error "Appsignal.report_error: " \
      "Cannot add error. " \
      "The given value is not an exception: #{exception.inspect}"
    return
  end
  return unless Appsignal.active?

  has_parent_transaction = Appsignal::Transaction.current?
  transaction =
    if has_parent_transaction
      Appsignal::Transaction.current
    else
      Appsignal::Transaction.new(Appsignal::Transaction::HTTP_REQUEST)
    end

  transaction.add_error(exception, &block)

  transaction.complete unless has_parent_transaction
end

#send_error(error) {|transaction| ... } ⇒ void Also known as: send_exception

This method returns an undefined value.

Send an error to AppSignal regardless of the context.

**We recommend using the #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.

Examples:

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

Parameters:

  • error (Exception) —

    The error to send to AppSignal.

Yields:

  • (transaction) —

    yields block to allow modification of the transaction before it’s send.

Yield Parameters:

  • transaction (Transaction) —

    yields the AppSignal transaction used to send the error.

See Also:

Since:

  • 0.6.0



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 229

def send_error(error, &block)
  return unless Appsignal.active?

  unless error.is_a?(Exception)
    Appsignal.internal_logger.error "Appsignal.send_error: " \
      "Cannot send error. " \
      "The given value is not an exception: #{error.inspect}"
    return
  end

  transaction =
    Appsignal::Transaction.new(Appsignal::Transaction::HTTP_REQUEST)
  transaction.set_error(error, &block)

  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.

Examples:

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)

Since:

  • 2.2.0



403
404
405
406
407
408
409
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 403

def set_action(action)
  return if !Appsignal.active? ||
    !Appsignal::Transaction.current? ||
    action.nil?

  Appsignal::Transaction.current.set_action(action)
end

#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 #add_params after this helper will add new parameters to the transaction.

See Also:

Since:

  • 4.2.0



621
622
623
624
625
626
627
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 621

def set_empty_params!
  return unless Appsignal.active?
  return unless Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.set_empty_params!
end

#set_error(exception) {|transaction| ... } ⇒ void Also known as: set_exception, add_exception

This method returns an undefined value.

Set an error on the current transaction.

**We recommend using the #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.

Examples:

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

Parameters:

  • exception (Exception) —

    The error to add to the current transaction.

Yields:

  • (transaction) —

    yields block to allow modification of the transaction.

Yield Parameters:

  • transaction (Transaction) —

    yields the AppSignal transaction used to store the error.

See Also:

Since:

  • 0.6.6



295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 295

def set_error(exception)
  unless exception.is_a?(Exception)
    Appsignal.internal_logger.error "Appsignal.set_error: " \
      "Cannot set error. " \
      "The given value is not an exception: #{exception.inspect}"
    return
  end
  return if !Appsignal.active? || !Appsignal::Transaction.current?

  transaction = Appsignal::Transaction.current
  transaction.set_error(exception)
  yield transaction if block_given?
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.

Examples:

create a custom admin namespace

class AdminController < ApplicationController
  before_action :set_appsignal_namespace

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

Parameters:

  • namespace (String)

See Also:

Since:

  • 2.2.0



445
446
447
448
449
450
451
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 445

def set_namespace(namespace)
  return if !Appsignal.active? ||
    !Appsignal::Transaction.current? ||
    namespace.nil?

  Appsignal::Transaction.current.set_namespace(namespace)
end