Overall improvements

cabol · Jul 5, 2020 · 3ccf5fb · 3ccf5fb
1 parent 3a7e0d4
commit 3ccf5fb
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -183,7 +183,7 @@ end
 
  * [Getting Started](http://hexdocs.pm/nebulex/getting-started.html)
  * [Documentation](http://hexdocs.pm/nebulex/Nebulex.html)
- * [Cache Usage Patterns via Nebulex.Caching](http://hexdocs.pm/nebulex/cache-usage-patterns.html)
+ * [Cache Usage Patterns](http://hexdocs.pm/nebulex/cache-usage-patterns.html)
  * [Instrumenting the Cache with Telemetry](http://hexdocs.pm/nebulex/telemetry.html)
  * [Migrating to v2.x](http://hexdocs.pm/nebulex/migrating-to-v2.html)
  * [Examples](https://github.com/cabol/nebulex_examples)
@@ -235,13 +235,12 @@ alongside new or changed code.
 
 Before to submit a PR it is highly recommended to run:
 
- * `mix test` to run tests
+ * `mix format` to format the code properly.
+ * `MIX_ENV=test mix credo --strict` to find code style issues.
  * `mix coveralls.html && open cover/excoveralls.html` to run tests and check
    out code coverage (expected 100%).
- * `mix format && mix credo --strict` to format your code properly and find code
-   style issues
- * `mix dialyzer` to run dialyzer for type checking; might take a while on the
-   first invocation
+ * `MIX_ENV=test mix dialyzer` to run dialyzer for type checking; might take a
+   while on the first invocation.
 
 ## Copyright and License
 

diff --git a/guides/telemetry.md b/guides/telemetry.md
@@ -84,11 +84,11 @@ defmodule MyApp.Telemetry do
   defp metrics do
     [
       # Nebulex Stats Metrics
-      last_value("my_app.cache.stats.hits"),
-      last_value("my_app.cache.stats.misses"),
-      last_value("my_app.cache.stats.writes"),
-      last_value("my_app.cache.stats.evictions"),
-      last_value("my_app.cache.stats.expirations"),
+      last_value("nebulex.cache.stats.hits", tags: [:cache]),
+      last_value("nebulex.cache.stats.misses", tags: [:cache]),
+      last_value("nebulex.cache.stats.writes", tags: [:cache]),
+      last_value("nebulex.cache.stats.evictions", tags: [:cache]),
+      last_value("nebulex.cache.stats.expirations", tags: [:cache]),
 
       # VM Metrics
       summary("vm.memory.total", unit: {:byte, :kilobyte}),
@@ -122,36 +122,49 @@ children = [
 Now start an IEx session and call the server:
 
 ```
-iex(1)> MyApp.Cache.put 1, 1
+iex(1)> MyApp.Cache.get 1
+nil
+iex(2)> MyApp.Cache.put 1, 1, ttl: 10
+:ok
+iex(3)> MyApp.Cache.get 1
+1
+iex(4)> MyApp.Cache.put 2, 2
+:ok
+iex(5)> MyApp.Cache.delete 2
+:ok
+iex(6)> Process.sleep(20)
+:ok
+iex(7)> MyApp.Cache.get 1
+nil
 ```
 
 and you should see something like the following output:
 
 ```
 [Telemetry.Metrics.ConsoleReporter] Got new event!
-Event name: my_app.cache.stats
-All measurements: %{evictions: 0, expirations: 0, hits: 0, misses: 0, writes: 1}
+Event name: nebulex.cache.stats
+All measurements: %{evictions: 2, expirations: 1, hits: 1, misses: 2, writes: 2}
 All metadata: %{cache: MyApp.Cache}
 
 Metric measurement: :hits (last_value)
-With value: 0
-Tag values: %{}
+With value: 1
+Tag values: %{cache: MyApp.Cache}
 
 Metric measurement: :misses (last_value)
-With value: 0
-Tag values: %{}
+With value: 2
+Tag values: %{cache: MyApp.Cache}
 
 Metric measurement: :writes (last_value)
-With value: 1
-Tag values: %{}
+With value: 2
+Tag values: %{cache: MyApp.Cache}
 
 Metric measurement: :evictions (last_value)
-With value: 0
-Tag values: %{}
+With value: 2
+Tag values: %{cache: MyApp.Cache}
 
 Metric measurement: :expirations (last_value)
-With value: 0
-Tag values: %{}
+With value: 1
+Tag values: %{cache: MyApp.Cache}
 ```
 
 ## Adding other custom metrics
@@ -172,7 +185,7 @@ defmodule MyApp.Cache do
 
   def dispatch_cache_size do
     :telemetry.execute(
-      [:my_app, :cache, :size],
+      [:nebulex, :cache, :size],
       %{value: size()},
       %{cache: __MODULE__}
     )
@@ -198,14 +211,14 @@ Metrics:
 defp metrics do
   [
     # Nebulex Stats Metrics
-    last_value("my_app.cache.stats.hits"),
-    last_value("my_app.cache.stats.misses"),
-    last_value("my_app.cache.stats.writes"),
-    last_value("my_app.cache.stats.evictions"),
-    last_value("my_app.cache.stats.expirations"),
+    last_value("nebulex.cache.stats.hits", tags: [:cache]),
+    last_value("nebulex.cache.stats.misses", tags: [:cache]),
+    last_value("nebulex.cache.stats.writes", tags: [:cache]),
+    last_value("nebulex.cache.stats.evictions", tags: [:cache]),
+    last_value("nebulex.cache.stats.expirations", tags: [:cache]),
 
     # Nebulex custom Metrics
-    last_value("my_app.cache.size.value"),
+    last_value("nebulex.cache.size.value", tags: [:cache]),
 
     # VM Metrics
     summary("vm.memory.total", unit: {:byte, :kilobyte}),
@@ -220,11 +233,11 @@ If you start an IEx session like previously, you should see the new metric too:
 
 ```
 [Telemetry.Metrics.ConsoleReporter] Got new event!
-Event name: my_app.cache.size
+Event name: nebulex.cache.size
 All measurements: %{value: 0}
 All metadata: %{cache: MyApp.Cache}
 
 Metric measurement: :value (last_value)
 With value: 0
-Tag values: %{}
+Tag values: %{cache: MyApp.Cache}
 ```
diff --git a/lib/nebulex/cache/cluster.ex b/lib/nebulex/cache/cluster.ex
@@ -3,6 +3,7 @@ defmodule Nebulex.Cache.Cluster do
   # distributed caching functionality.
   # TODO: Use pg when depending on Erlang/OTP 23+, since the pg2 module is
   #       deprecated as of OTP 23 and scheduled for removal in OTP 24.
+  #       Nebulex v2 will support both.
   @moduledoc false
 
   @doc """

diff --git a/lib/nebulex/cache/stats.ex b/lib/nebulex/cache/stats.ex
@@ -59,7 +59,7 @@ defmodule Nebulex.Cache.Stats do
 
       MyApp.Cache.dispatch_stats()
 
-      MyApp.Cache.dispatch_stats(telemetry_prefix: [:my_cache, :stats])
+      MyApp.Cache.dispatch_stats(event_prefix: [:my_cache, :stats])
 
   By calling this injected helper, the function `Nebulex.Cache.Stats.dispatch/2`
   is called under-the-hood, but the cache name is resolved automatically.
@@ -78,7 +78,8 @@ defmodule Nebulex.Cache.Stats do
         measurements: [
           {MyApp.Cache, :dispatch_stats, []},
         ],
-        period: :timer.seconds(10), # configure sampling period - default is :timer.seconds(5)
+        # configure sampling period - default is :timer.seconds(5)
+        period: :timer.seconds(10),
         name: :my_cache_stats_poller
       )
 
@@ -247,18 +248,16 @@ defmodule Nebulex.Cache.Stats do
 
     The telemetry `:metadata` map will include the following fields:
 
-      * `:cache` - Cache module or name.
+      * `:cache` - The cache module, or the name (if an explicit name has been
+        given to the cache).
 
     Additionally, you can add your own metadata fields by given the option
     `:metadata`.
 
     ## Options
 
-      * `:telemetry_prefix` – By default, the telemetry prefix is based on the
-        cache name, so if your cache module is called `MyApp.Cache`, the prefix
-        will be `[:my_app, :cache]`. But, if you have set an explicit name to
-        your cache, like for example `:my_cache_name`, the default prefix will
-        be `[:my_cache_name]`.
+      * `:event_prefix` – The prefix of the telemetry event.
+        Defaults to `[:nebulex, :cache]`.
 
       * `:metadata` – A map with additional metadata fields. Defaults to `%{}`.
 
@@ -269,7 +268,7 @@ defmodule Nebulex.Cache.Stats do
 
         iex> Nebulex.Cache.Stats.dispatch(
         ...>   MyCache,
-        ...>   telemetry_prefix: [:my_event],
+        ...>   event_prefix: [:my_cache],
         ...>   metadata: %{tag: "tag1"}
         ...> )
         :ok
@@ -278,21 +277,13 @@ defmodule Nebulex.Cache.Stats do
     def dispatch(cache_or_name, opts \\ []) do
       if info = __MODULE__.info(cache_or_name) do
         :telemetry.execute(
-          Keyword.get(opts, :telemetry_prefix, telemetry_prefix(cache_or_name)) ++ [:stats],
+          Keyword.get(opts, :event_prefix, [:nebulex, :cache]) ++ [:stats],
           Map.from_struct(info),
           opts |> Keyword.get(:metadata, %{}) |> Map.put(:cache, cache_or_name)
         )
       else
         :ok
       end
     end
-
-    defp telemetry_prefix(cache_or_name) do
-      cache_or_name
-      |> Module.split()
-      |> Enum.map(&(&1 |> Macro.underscore() |> String.to_atom()))
-    rescue
-      ArgumentError -> [cache_or_name]
-    end
   end
 end
diff --git a/test/nebulex/cache/stats_test.exs b/test/nebulex/cache/stats_test.exs
@@ -163,7 +163,7 @@ defmodule Nebulex.Cache.StatsTest do
 
         assert called(
                  :telemetry.execute(
-                   [:nebulex, :cache, :stats_test, :cache, :stats],
+                   [:nebulex, :cache, :stats],
                    %{hits: 0, misses: 0, writes: 0, evictions: 0, expirations: 0},
                    %{cache: Nebulex.Cache.StatsTest.Cache}
                  )
@@ -175,23 +175,9 @@ defmodule Nebulex.Cache.StatsTest do
   describe "dispatch_stats with dynamic cache" do
     setup_with_dynamic_cache(Cache, :stats_with_dispatch, [stats: true] ++ @config)
 
-    test "emits a telemetry event when called" do
-      with_mock :telemetry, [], execute: fn _, _, _ -> :ok end do
-        :ok = Cache.dispatch_stats()
-
-        assert called(
-                 :telemetry.execute(
-                   [:stats_with_dispatch, :stats],
-                   %{hits: 0, misses: 0, writes: 0, evictions: 0, expirations: 0},
-                   %{cache: :stats_with_dispatch}
-                 )
-               )
-      end
-    end
-
     test "emits a telemetry event with custom telemetry_prefix when called" do
       with_mock :telemetry, [], execute: fn _, _, _ -> :ok end do
-        :ok = Cache.dispatch_stats(telemetry_prefix: [:my_event], metadata: %{tag: "tag1"})
+        :ok = Cache.dispatch_stats(event_prefix: [:my_event], metadata: %{tag: "tag1"})
 
         assert called(
                  :telemetry.execute(