feat: Registers telemetry events (quantum-elixir#493)

* feat: Registers telemetry events * refactor: Moves telemetry declarations to a single module * chore: Adds a test of the registered telemetry events * docs: Removes redundant documentation * refactor: Uses top-level module * fix: Removes unused test file
tepadruser · Nov 15, 2021 · 088fb23 · 088fb23
1 parent 1387b53
commit 088fb23
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 60 deletions.
diff --git a/lib/quantum.ex b/lib/quantum.ex
@@ -1,4 +1,51 @@
 defmodule Quantum do
+  use TelemetryRegistry
+
+  telemetry_event(%{
+    event: [:quantum, :job, :add],
+    description: "dispatched when a job is added",
+    measurements: "%{}",
+    metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+  })
+
+  telemetry_event(%{
+    event: [:quantum, :job, :update],
+    description: "dispatched when a job is updated",
+    measurements: "%{}",
+    metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+  })
+
+  telemetry_event(%{
+    event: [:quantum, :job, :delete],
+    description: "dispatched when a job is deleted",
+    measurements: "%{}",
+    metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+  })
+
+  telemetry_event(%{
+    event: [:quantum, :job, :start],
+    description: "dispatched on job execution start",
+    measurements: "%{system_time: integer()}",
+    metadata:
+      "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom()}"
+  })
+
+  telemetry_event(%{
+    event: [:quantum, :job, :stop],
+    description: "dispatched on job execution end",
+    measurements: "%{duration: integer()}",
+    metadata:
+      "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), result: term()}"
+  })
+
+  telemetry_event(%{
+    event: [:quantum, :job, :exception],
+    description: "dispatched on job execution fail",
+    measurements: "%{duration: integer()}",
+    metadata:
+      "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), kind: :throw | :error | :exit, reason: term(), stacktrace: list()}"
+  })
+
   @moduledoc """
   Defines a quantum Scheduler.
 
@@ -70,6 +117,55 @@ defmodule Quantum do
 
     * `:timezone` - Default timezone of new Job
 
+  ## Telemetry
+
+  #{telemetry_docs()}
+
+  ### Examples
+
+      iex(1)> :telemetry_registry.discover_all(:quantum)
+      :ok
+      iex(2)> :telemetry_registry.spannable_events()
+      [{[:quantum, :job], [:start, :stop, :exception]}]
+      iex(3)> :telemetry_registry.list_events
+      [
+        {[:quantum, :job, :add], Quantum,
+         %{
+           description: "dispatched when a job is added",
+           measurements: "%{}",
+           metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+         }},
+        {[:quantum, :job, :delete], Quantum,
+         %{
+           description: "dispatched when a job is deleted",
+           measurements: "%{}",
+           metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+         }},
+        {[:quantum, :job, :exception], Quantum,
+         %{
+           description: "dispatched on job execution fail",
+           measurements: "%{duration: integer()}",
+           metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), kind: :throw | :error | :exit, reason: term(), stacktrace: list()}"
+         }},
+        {[:quantum, :job, :start], Quantum,
+         %{
+           description: "dispatched on job execution start",
+           measurements: "%{system_time: integer()}",
+           metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom()}"
+         }},
+        {[:quantum, :job, :stop], Quantum,
+         %{
+           description: "dispatched on job execution end",
+           measurements: "%{duration: integer()}",
+           metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), result: term()}"
+         }},
+        {[:quantum, :job, :update], Quantum,
+         %{
+           description: "dispatched when a job is updated",
+           measurements: "%{}",
+           metadata: "%{job: Quantum.Job.t(), scheduler: atom()}"
+         }}
+      ]
   """
 
   require Logger

diff --git a/mix.exs b/mix.exs
@@ -76,8 +76,7 @@ defmodule Quantum.Mixfile do
         "pages/configuration.md",
         "pages/runtime-configuration.md",
         "pages/crontab-format.md",
-        "pages/run-strategies.md",
-        "pages/telemetry.md"
+        "pages/run-strategies.md"
       ],
       groups_for_modules: [
         "Run Strategy": [
@@ -104,7 +103,8 @@ defmodule Quantum.Mixfile do
       {:ex_doc, ">= 0.0.0", only: [:dev, :docs], runtime: false},
       {:excoveralls, "~> 0.5", only: [:test], runtime: false},
       {:dialyxir, "~> 1.0-rc", only: [:dev], runtime: false},
-      {:credo, "~> 1.0", only: [:dev], runtime: false}
+      {:credo, "~> 1.0", only: [:dev], runtime: false},
+      {:telemetry_registry, "~> 0.2"}
     ]
   end
 end
diff --git a/pages/telemetry.md b/pages/telemetry.md
diff --git a/test/quantum_test.exs b/test/quantum_test.exs
@@ -0,0 +1,4 @@
+defmodule QuantumTest do
+  use ExUnit.Case
+  doctest Quantum
+end