ScoutApm.Error (scout_apm v2.0.0)

Copy Markdown

Public API for capturing errors in Scout APM.

Errors can be captured manually using capture/1 or capture/2, or automatically via Phoenix telemetry handlers.

Manual Error Capture

try do
  some_risky_operation()
rescue
  e ->
    ScoutApm.Error.capture(e, stacktrace: __STACKTRACE__)
    reraise e, __STACKTRACE__
end

With Additional Context

try do
  process_user_request(user)
rescue
  e ->
    ScoutApm.Error.capture(e,
      stacktrace: __STACKTRACE__,
      context: %{user_id: user.id},
      request_path: "/api/users",
      request_params: %{action: "update"}
    )
    reraise e, __STACKTRACE__
end

Configuration

Error capture can be configured in your config:

config :scout_apm,
  errors_enabled: true,
  errors_ignored_exceptions: [Phoenix.Router.NoRouteError],
  errors_filter_parameters: ["credit_card", "cvv"]

Options

All capture functions accept these options:

  • :stacktrace - The exception stacktrace. For best results, pass __STACKTRACE__ from within a rescue block.
  • :context - A map of additional context to include with the error.
  • :request_path - The request path (e.g., "/api/users").
  • :request_params - A map of request parameters.
  • :session - A map of session data.
  • :custom_controller - Override the controller name.
  • :custom_params - A map of custom parameters.

Summary

Types

capture_opts()

Functions

capture(exception, opts \\ [])

Captures an exception and sends it to Scout APM.

capture_from_telemetry(kind, reason, stacktrace, opts \\ [])

Captures an error from kind/reason/stacktrace tuple (as received in telemetry exception events).

enabled?()

Returns whether error capture is currently enabled.

Types

capture_opts()

@type capture_opts() :: [
  stacktrace: Exception.stacktrace(),
  context: map(),
  request_path: String.t(),
  request_params: map(),
  session: map(),
  custom_controller: String.t(),
  custom_params: map()
]

Functions

capture(exception, opts \\ [])

@spec capture(Exception.t(), capture_opts()) :: :ok

Captures an exception and sends it to Scout APM.

The stacktrace will be captured automatically if not provided, but for best results, pass __STACKTRACE__ from within a rescue block.

Returns :ok on success.

Examples

try do
  do_something_risky()
rescue
  e ->
    ScoutApm.Error.capture(e, stacktrace: __STACKTRACE__)
    reraise e, __STACKTRACE__
end

# With additional context
ScoutApm.Error.capture(exception,
  stacktrace: __STACKTRACE__,
  context: %{user_id: 123},
  request_path: conn.request_path
)

capture_from_telemetry(kind, reason, stacktrace, opts \\ [])

@spec capture_from_telemetry(
  kind :: :error | :throw | :exit,
  reason :: term(),
  stacktrace :: Exception.stacktrace(),
  capture_opts()
) :: :ok

Captures an error from kind/reason/stacktrace tuple (as received in telemetry exception events).

This is primarily used internally by telemetry handlers but can be called directly when handling exceptions in catch blocks.

Examples

try do
  do_something()
catch
  kind, reason ->
    ScoutApm.Error.capture_from_telemetry(kind, reason, __STACKTRACE__)
    :erlang.raise(kind, reason, __STACKTRACE__)
end

enabled?()

@spec enabled?() :: boolean()

Returns whether error capture is currently enabled.