Ths module contains functions to create transactions and time the execution of code. It’s used to add instrumentation to an Elixir app.

Scout’s instrumentation is divided into 2 areas:

1. Transactions: these wrap around a flow of work, like a web request or a GenServer call. The UI groups data under transactions. Use @transaction module attributes and the transaction/4 macro.
2. Timing: these measure individual pieces of work, like an HTTP request to an outside service or an Ecto query. Use @timing module attributes and the timing/4 macro.

Recording transactions

There are 2 ways to define transactions:

1. deftransaction macro
2. Wrapping blocks of code with the transaction/4 macro.

Deprecated:

• @transaction module attributes

Transaction types

A transaction may be one of two types:

1. web: a transaction that impacts the main app experience, like a Phoenix controller action.
2. background: a transaction that isn’t in the main app flow, like a GenServer call or Exq background job.

If you are instrumenting a stand-alone Elixir app, treat all transactions as web. Data from these transactions appear in the App overview charts.

deftransaction Macro Example

Replace your function def with deftransaction to instrument it. You can override the name and type by setting the @transaction_opts attribute right before the function.

defmodule CampWaitlist.Web.HtmlChannel do
  use Phoenix.Channel
  import ScoutApm.Tracing

  # Will appear under "Web" in the UI, named "CampWaitlist.Web.HtmlChannel.join".
  @transaction_opts [type: "web"]
  deftransaction join("topic:html", _message, socket) do
    {:ok, socket}
  end

Module Attribute Example

This is deprecated due to a number of gotchas around the macro that implements this. The deftransaction macro more reliably sets up the instrumentation.

defmodule CampWaitlist.Web.HtmlChannel do
  use Phoenix.Channel
  use ScoutApm.Tracing

  # Will appear under "Web" in the UI, named "CampWaitlist.Web.HtmlChannel.join".
  @transaction(type: "web")
  def join("topic:html", _message, socket) do
    {:ok, socket}
  end

We treat this as a web transaction as it impacts the user experience.

An example treating a GenServer function as a background job:

defmodule CampWaitlist.AvailChecker do
  use GenServer
  use ScoutApm.Tracing

  # Will appear under "Background Jobs" in the UI, named "CampWaitlist.AvailChecker.handle_call".
  @transaction(type: "background")
  def handle_call({:check, campground}, _from, state) do
    # Do work...
  end

  # Will appear under "Background Jobs" in the UI, named "AvailChecker.status".
  @transaction(type: "background", name: "AvailChecker.status")
  def handle_call({:status, campground}, _from, state) do
    # Do work...
  end

Timing Code

There are 2 ways to time the execution of code:

1. deftiming macro
2. Wrapping blocks of code with the timing/4 macro.

Deprecated:

• @timing module attributes

deftiming Macro Example

defmodule Searcher do
  import ScoutApm.Tracing

  # Time associated with this function will appear under "Hound" in timeseries charts.
  # The function will appear as `Hound/open_search` in transaction traces.
  @timing_opts [category: "Hound"]
  deftiming open_search(url) do
    navigate_to(url)
  end

  # Time associated with this function will appear under "Hound" in timeseries charts.
  # The function will appear as `Hound/search` in transaction traces.
  @timing_opts [name: "search", category: "Hound"]
  deftiming open_search(url) do
    navigate_to(url)
  end

Module Attribute Example

This is deprecated due to a number of gotchas around the macro that implements this. The deftracing macro more reliably sets up the instrumentation.

defmodule Searcher do
  use ScoutApm.Tracing

  # Time associated with this function will appear under "Hound" in timeseries charts.
  # The function will appear as `Hound/open_search` in transaction traces.
  @timing(category: "Hound")
  def open_search(url) do
    navigate_to(url)
  end

  # Time associated with this function will appear under "Hound" in timeseries charts.
  # The function will appear as `Hound/search` in transaction traces.
  @timing(category: "Hound", name: "search")
  def open_search(url) do
    navigate_to(url)
  end

Category limitations

We limit the arity of category. These are displayed in charts throughput the UI. These should not be generated dynamically and should be limited to higher-level categories (ie Postgres, Redis, HTTP, etc).

use vs. import

To utilize the deftransaction and deftiming macros, import this module:

defmodule YourModule
  import ScoutApm.Tracing

To utilize the module attributes (@transaction and @timing), inject this module via the use macro:

defmodule YourModule
  use ScoutApm.Tracing

You can then call transaction/4 and timing/4 via the following qualified module name, ie:

ScoutApm.Tracing.timing("HTTP", "GitHub", do: ...)

To drop the full module name, you’ll need to use the import macro. The following is valid:

defmodule YourModule
  use ScoutApm.Tracing
  import ScoutApm.Tracing