Module: Appsignal::Helpers::Instrumentation

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

Instance Method Summary collapse

Instance Method Details

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

Add breadcrumbs to the transaction.

Breadcrumbs can be used to trace what path a user has taken before encountering an error.

At most 20 of the added breadcrumbs will be saved.

@param category — category of breadcrumb e.g. "UI", "Network", "Navigation", "Console".

@param action — name of breadcrumb e.g "The user clicked a button", "HTTP 500 from http://blablabla.com"

@param message — optional message in string format

@param metadata — key/value metadata in <string, string> format

@param time — time of breadcrumb, should respond to .to_i defaults to Time.now.utc

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

@see https://docs.appsignal.com/ruby/instrumentation/breadcrumbs.html — Breadcrumb reference



936
937
938
939
940
941
942
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 936

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.

@param data — Custom data to add to the transaction.

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]

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

Parameters:



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

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_function_parameters(params = nil, &block) ⇒ void

This method returns an undefined value.

Add the function parameters to the current transaction.

The function parameters are the arguments a background job or function was called with. In collector mode they map to their own attribute, separate from the request payload.

Behaves like #add_params: merges when called multiple times, and a block takes precedence over the argument.

@param params — The function parameters to add to the transaction.

@see #add_request_payload

Parameters:

  • params (?(::Hash[String, Object] | ::Array[Object]), nil) (defaults to: nil) 


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

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

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

#add_headers(headers = nil, &block) ⇒ 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.

@param headers — The request headers to add to the transaction.

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

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-headers.html — Request headers filtering guide

Parameters:

  • headers (::Hash[String, Object], nil) (defaults to: nil) 


888
889
890
891
892
893
894
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 888

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, &block) ⇒ 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.

@param params — The parameters to add to the transaction.

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

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-parameters.html — Parameter filtering guide

Parameters:

  • params (?(::Hash[String, Object] | ::Array[Object]), nil) (defaults to: nil) 


701
702
703
704
705
706
707
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 701

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_query_parameters(params = nil, &block) ⇒ void

This method returns an undefined value.

Add the query parameters to the current transaction.

The query parameters are the parameters parsed from an incoming request's query string. In collector mode they map to their own attribute, separate from the request payload and the function parameters.

Behaves like #add_params: merges when called multiple times, and a block takes precedence over the argument.

@param params — The query parameters to add to the transaction.

@see #add_request_payload

Parameters:

  • params (?(::Hash[String, Object] | ::Array[Object]), nil) (defaults to: nil) 


778
779
780
781
782
783
784
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 778

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

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

#add_request_payload(params = nil, &block) ⇒ void

This method returns an undefined value.

Add the request payload to the current transaction.

The request payload is the parameters of an incoming request, such as the query string and the request body. In collector mode it maps to its own attribute, separate from the function parameters.

Behaves like #add_params: merges when called multiple times, and a block takes precedence over the argument.

@param params — The request payload to add to the transaction.

@see #add_function_parameters

Parameters:

  • params (?(::Hash[String, Object] | ::Array[Object]), nil) (defaults to: nil) 


727
728
729
730
731
732
733
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 727

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

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

#add_session_data(session_data = nil, &block) ⇒ 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.

@param session_data — The session data to add to the transaction.

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

@see https://docs.appsignal.com/guides/custom-data/sample-data.html — Sample data guide

@see https://docs.appsignal.com/guides/filter-data/filter-session-data.html — Session data filtering guide

Parameters:

  • session_data (::Hash[String, Object], nil) (defaults to: nil) 


846
847
848
849
850
851
852
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 846

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.

@param tags — Collection of tags to add to the transaction.

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

@see https://docs.appsignal.com/ruby/instrumentation/tagging.html — Tagging guide

Parameters:



643
644
645
646
647
648
649
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 643

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 ⇒ void

This method returns an undefined value.

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.

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

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.

@see https://docs.appsignal.com/ruby/instrumentation/ignore-instrumentation.html — Ignore instrumentation guide



1095
1096
1097
1098
1099
1100
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 1095

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, opentelemetry_kind: nil, opentelemetry_scope: nil, &block) ⇒ Object

Instrument helper for AppSignal.

For more help, read our custom instrumentation guide, listed under "See also".

@param name — Name of the instrumented event. Read our event naming guide listed under "See also".

@param title — Human readable name of the event.

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

@param body_format — 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.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind for the event's span, such as :client for an outgoing HTTP request. Defaults to the OpenTelemetry default of :internal.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record the event's span under, given as a [name, version] pair. Defaults to the AppSignal scope.

@return — Returns the block's return value.

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

@see .instrument_sql

@see https://docs.appsignal.com/ruby/instrumentation/instrumentation.html — AppSignal custom instrumentation guide

@see https://docs.appsignal.com/api/event-names.html — AppSignal event naming guide



988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 988

def instrument( # rubocop:disable Metrics/ParameterLists
  name,
  title = nil,
  body = nil,
  body_format = Appsignal::EventFormatter::DEFAULT,
  opentelemetry_kind: nil,
  opentelemetry_scope: nil,
  &block
)
  Appsignal::Transaction.current
    .instrument(
      name,
      title,
      body,
      body_format,
      :opentelemetry_kind => opentelemetry_kind,
      :opentelemetry_scope => opentelemetry_scope,
      &block
    )
end

#instrument_sql(name, title = nil, body = nil, opentelemetry_kind: :client, opentelemetry_scope: nil, &block) ⇒ Object

Instrumentation helper for SQL queries.

This helper filters out values from SQL queries so you don't have to.

@param name — Name of the instrumented event. Read our event naming guide listed under "See also".

@param title — Human readable name of the event.

@param body — SQL query that's being executed.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind for the event's span. Defaults to :client, because a query is an outgoing call to a datastore. Pass :internal for a query that is not an outgoing call.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record the event's span under, given as a [name, version] pair. Defaults to the AppSignal scope.

@return — Returns the block's return value.

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

@see .instrument

@see https://docs.appsignal.com/ruby/instrumentation/instrumentation.html — AppSignal custom instrumentation guide

@see https://docs.appsignal.com/api/event-names.html — AppSignal event naming guide



1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 1046

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

#monitor(action:, namespace: nil, opentelemetry_context: nil, opentelemetry_scope: nil, opentelemetry_kind: nil, opentelemetry_relationship: 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.

@param namespace — 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.

@param action — 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.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind: one of :server, :consumer, :producer or :internal. Defaults to :server.

@param opentelemetry_relationship — In collector mode, how an incoming opentelemetry_context relates to this transaction's span: one of :parent, :link, :both or :none. Defaults to :parent.

@param opentelemetry_context — In collector mode, an incoming OpenTelemetry trace context to relate this transaction's span to.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record this transaction's spans under, given as a [name, version] pair. Defaults to the AppSignal scope.

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

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

@see https://docs.appsignal.com/ruby/instrumentation/background-jobs.html — Monitor guide



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
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 127

def monitor( # rubocop:disable Metrics/ParameterLists
  action:,
  namespace: nil,
  opentelemetry_context: nil,
  opentelemetry_scope: nil,
  opentelemetry_kind: nil,
  opentelemetry_relationship: 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,
        :opentelemetry_context => opentelemetry_context,
        :opentelemetry_scope => opentelemetry_scope,
        :opentelemetry_kind => opentelemetry_kind,
        :opentelemetry_relationship => opentelemetry_relationship
      )
    end

  begin
    yield if block_given?
  rescue Exception => error
    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, opentelemetry_context: nil, opentelemetry_scope: nil, opentelemetry_kind: nil, opentelemetry_relationship: nil, &block) ⇒ 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.

@param namespace — 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.

@param action — 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.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind: one of :server, :consumer, :producer or :internal. Defaults to :server.

@param opentelemetry_relationship — In collector mode, how an incoming opentelemetry_context relates to this transaction's span: one of :parent, :link, :both or :none. Defaults to :parent.

@param opentelemetry_context — In collector mode, an incoming OpenTelemetry trace context to relate this transaction's span to.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record this transaction's spans under, given as a [name, version] pair. Defaults to the AppSignal scope.

@return — The value of the given block is returned.

@see monitor



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 215

def monitor_and_stop( # rubocop:disable Metrics/ParameterLists
  action:,
  namespace: nil,
  opentelemetry_context: nil,
  opentelemetry_scope: nil,
  opentelemetry_kind: nil,
  opentelemetry_relationship: 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,
    :opentelemetry_context => opentelemetry_context,
    :opentelemetry_scope => opentelemetry_scope,
    :opentelemetry_kind => opentelemetry_kind,
    :opentelemetry_relationship => opentelemetry_relationship,
    &block
  )
ensure
  Appsignal.stop("monitor_and_stop")
end

#report_error(exception, opentelemetry_context: nil, opentelemetry_scope: nil, opentelemetry_kind: nil, opentelemetry_relationship: nil, &block) ⇒ Object Also known as: report_exception

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.

@param exception — The error to add to the current transaction.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind: one of :server, :consumer, :producer or :internal. Defaults to :server. Only used when a new transaction is created.

@param opentelemetry_relationship — In collector mode, how an incoming opentelemetry_context relates to this transaction's span: one of :parent, :link, :both or :none. Defaults to :parent. Only used when a new transaction is created.

@param opentelemetry_context — In collector mode, an incoming OpenTelemetry trace context to relate this transaction's span to. Only used when a new transaction is created.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record this transaction's spans under, given as a [name, version] pair. Defaults to the AppSignal scope.

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

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 451

def report_error(
  exception,
  opentelemetry_context: nil,
  opentelemetry_scope: nil,
  opentelemetry_kind: nil,
  opentelemetry_relationship: nil,
  &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,
        :opentelemetry_context => opentelemetry_context,
        :opentelemetry_scope => opentelemetry_scope,
        :opentelemetry_kind => opentelemetry_kind,
        :opentelemetry_relationship => opentelemetry_relationship
      )
    end

  transaction.add_error(exception, :source => "Appsignal.report_error", &block)

  transaction.complete unless has_parent_transaction
end

#send_error(error, opentelemetry_context: nil, opentelemetry_scope: nil, opentelemetry_kind: nil, opentelemetry_relationship: nil, &block) ⇒ Object Also known as: send_exception

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.

@param error — The error to send to AppSignal.

@param opentelemetry_kind — In collector mode, the OpenTelemetry span kind: one of :server, :consumer, :producer or :internal. Defaults to :server.

@param opentelemetry_relationship — In collector mode, how an incoming opentelemetry_context relates to this transaction's span: one of :parent, :link, :both or :none. Defaults to :parent.

@param opentelemetry_context — In collector mode, an incoming OpenTelemetry trace context to relate this transaction's span to.

@param opentelemetry_scope — In collector mode, the OpenTelemetry instrumentation scope to record this transaction's spans under, given as a [name, version] pair. Defaults to the AppSignal scope.

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

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 294

def send_error(
  error,
  opentelemetry_context: nil,
  opentelemetry_scope: nil,
  opentelemetry_kind: nil,
  opentelemetry_relationship: nil,
  &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,
      :opentelemetry_context => opentelemetry_context,
      :opentelemetry_scope => opentelemetry_scope,
      :opentelemetry_kind => opentelemetry_kind,
      :opentelemetry_relationship => opentelemetry_relationship
    )
  transaction.set_error(error, :source => "Appsignal.send_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.

@param action

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) 


508
509
510
511
512
513
514
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 508

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 report no parameters for this transaction, whatever their source.

This suppresses every params channel. In collector mode, where the request payload and the function parameters (a background job's arguments) are tracked as separate attributes, it suppresses both, not only the request payload. Parameters that an AppSignal integration would otherwise add are not added.

Calling #add_params, #add_request_payload or #add_function_parameters after this helper adds parameters again.

@see Transaction#set_empty_params!

@see Transaction#set_params_if_nil



805
806
807
808
809
810
811
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 805

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

@param exception — The error to add to the current transaction.

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

@see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html — Exception handling guide

Parameters:

  • exception (Exception) 


373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 373

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.

@param namespace

create a custom admin namespace

class AdminController < ApplicationController
  before_action :set_appsignal_namespace

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

@see https://docs.appsignal.com/guides/namespaces.html — Grouping with namespaces guide

Parameters:

  • namespace (String) 


550
551
552
553
554
555
556
 
# File 'lib/appsignal/helpers/instrumentation.rb', line 550

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

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