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. @transaction module attributes
2. Wrapping blocks of code with the transaction/4 macro.

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.

Module Attribute Example

The @transaction module attribute works well for treating GenServer calls as distinct transactions. An example instrumenting a Phoenix channel:

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. @timing module attributes
2. Wrapping blocks of code with the timing/4 macro.

Module Attribute Example

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 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 domain name, you’ll need to use the import macro. The following is valid:

defmodule YourModule
  use ScoutApm.Tracing
  import ScoutApm.Tracing