docs and tests

lib/dotcom/application.ex

@@ -26,15 +26,14 @@ defmodule Dotcom.Application do
 
     children =
       [
-        {Application.get_env(:dotcom, :cache, Dotcom.Cache.Multilevel), []},
-        {Dotcom.Telemetry, []},
-        {DotcomWeb.Telemetry, []},
-        {Req.Telemetry, []}
+        {Application.get_env(:dotcom, :cache, Dotcom.Cache.Multilevel), []}
       ] ++
         if Application.get_env(:dotcom, :env) != :test do
           [
-            # We can't run cache telemetry in the test environment because none of the levels are running
+            {Dotcom.Telemetry, []},
             {Dotcom.Cache.Telemetry, []},
+            {DotcomWeb.Telemetry, []},
+            {Req.Telemetry, []},
             # We don't need to run this cache because we are using the local cache for tests
             {Dotcom.Cache.TripPlanFeedback.Cache, []}
           ]

lib/dotcom/telemetry.ex

@@ -1,15 +1,23 @@
 defmodule Dotcom.Telemetry do
   @moduledoc """
+  This Supervisor establishes sends vm stats to the `TelemetryMetricsSplunk` reporter.
+  No polling occurs as these metrics are emitted regularly anyway.
   """
 
   use Supervisor
 
   alias Telemetry.Metrics
 
+  @doc """
+  Starts the supervisor.
+  """
   def start_link(arg) do
     Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
   end
 
+  @doc """
+  Initializes the supervisor.
+  """
   def init(_arg) do
     telemetry_metrics_splunk_config = Application.get_env(:dotcom, :telemetry_metrics_splunk)
 

lib/dotcom_web/telemetry.ex

@@ -1,16 +1,23 @@
 defmodule DotcomWeb.Telemetry do
   @moduledoc """
-  This module is responsible for starting the Telemetry poller and defining the metrics to be collected for Phoenix and the Erlang VM.
+  This Supervisor is responsible for starting the Telemetry poller and defining the metrics to be collected for Phoenix.
+  We poll the metrics every 60 seconds and send them to the `TelemetryMetricsSplunk` reporter.
   """
 
   use Supervisor
 
   alias Telemetry.Metrics
 
+  @doc """
+  Starts the supervisor.
+  """
   def start_link(arg) do
     Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
   end
 
+  @doc """
+  Initializes the supervisor.
+  """
   def init(_arg) do
     telemetry_metrics_splunk_config = Application.get_env(:dotcom, :telemetry_metrics_splunk)
 

lib/req/stats.ex

@@ -14,6 +14,15 @@ defmodule Req.Stats do
     Agent.start_link(fn -> initial_value end, name: __MODULE__)
   end
 
+  @doc """
+  Stops the Agent and detaches from `[:finch, :recv, :stop]` telemetry events.
+  """
+  def stop() do
+    :telemetry.detach("finch-recv-stop")
+
+    Agent.stop(__MODULE__)
+  end
+
   @doc """
   Handles telemetry events and aggregates them by host, path, and status.
   """

lib/telemetry/helper.ex

@@ -37,6 +37,9 @@ defmodule Telemetry.Helper do
     :dbg.tp(:telemetry, :execute, 3, [])
   end
 
+  @doc """
+  Stop the tracer and therefore stop listening for telemetry events.
+  """
   def stop do
     :dbg.stop()
   end

test/dotcom_web/stats_test.exs

@@ -0,0 +1,49 @@
+defmodule DotcomWeb.StatsTest do
+  use ExUnit.Case
+
+  import TelemetryTest
+
+  alias DotcomWeb.Stats
+
+  setup [:telemetry_listen]
+
+  setup do
+    {:ok, _} = Stats.start_link()
+
+    :ok
+  end
+
+  @tag telemetry_listen: [:dotcom_web, :request]
+  test "aggregates and dispatches stats" do
+    # Setup
+    duration = :rand.uniform(1_000_000_000)
+
+    measurement = %{
+      duration: duration
+    }
+
+    metadata = %{
+      conn: %{
+        method: Enum.random(["GET", "POST", "PUT", "DELETE"]),
+        status: Enum.random([200, 404, 500])
+      },
+      route: "/#{Faker.Internet.slug()}/"
+    }
+
+    # Exercise
+    :telemetry.execute([:phoenix, :router_dispatch, :stop], measurement, metadata)
+    :telemetry.execute([:phoenix, :router_dispatch, :stop], measurement, metadata)
+
+    Stats.dispatch_stats()
+
+    # Verify
+    assert_receive {
+      :telemetry_event,
+      %{
+        event: [:dotcom_web, :request],
+        measurements: %{avg: _duration, count: 2},
+        metadata: %{method: _host, path: _path, status: _status}
+      }
+    }
+  end
+end

test/mbta/api/stats_test.exs → test/req/stats_test.exs

@@ -1,9 +1,9 @@
-defmodule MBTA.Api.StatsTest do
+defmodule Req.StatsTest do
   use ExUnit.Case
 
   import TelemetryTest
 
-  alias MBTA.Api.Stats
+  alias Req.Stats
 
   setup [:telemetry_listen]
 
@@ -13,10 +13,9 @@ defmodule MBTA.Api.StatsTest do
     :ok
   end
 
-  @tag telemetry_listen: [:mbta_api, :request]
+  @tag telemetry_listen: [:req, :request]
   test "aggregates and dispatches stats" do
     # Setup
-    # 1 second in nanoseconds
     duration = :rand.uniform(1_000_000_000)
 
     measurement = %{
@@ -25,7 +24,8 @@ defmodule MBTA.Api.StatsTest do
 
     metadata = %{
       request: %{
-        path: "/#{Faker.Team.creature()}/"
+        host: Faker.Internet.domain_name(),
+        path: "/#{Faker.Internet.slug()}/"
       },
       status: Enum.random([200, 404, 500])
     }
@@ -40,9 +40,9 @@ defmodule MBTA.Api.StatsTest do
     assert_receive {
       :telemetry_event,
       %{
-        event: [:mbta_api, :request],
-        measurements: %{avg: ^duration, count: 2},
-        metadata: %{path: _path, status: _status}
+        event: [:req, :request],
+        measurements: %{avg: _duration, count: 2},
+        metadata: %{host: _host, path: _path, status: _status}
       }
     }
   end