Document the new Telemetry integration

Author: tompave

CHANGELOG.md

@@ -4,8 +4,9 @@
 
 * Add support for Elixir 1.18. Drop support for Elixir 1.15. Elixir >= 1.16 is now required. Dropping support for older versions of Elixir simply means that this package is no longer tested with them in CI, and that compatibility issues are not considered bugs.
 * Drop support for Erlang/OTP 24, and Erlang/OTP >= 25 is now required. Dropping support for older versions of Erlang/OTP simply means that this package is not tested with them in CI, and that no compatibility issues are considered bugs.
+* Instrument the package with [Telemetry](https://hex.pm/packages/telemetry): FunWithFlags now emits Telemetry events for persistence operations. ([pull/197](https://github.com/tompave/fun_with_flags/pull/197), and thanks [Kasse-Dembele](https://github.com/Kasse-Dembele) for suggesting the feature and sharing his work in [pull/176](https://github.com/tompave/fun_with_flags/pull/176))
 * Improve how the change-notification Phoenix.PubSub adapter manages its connection and readiness status. ([pull/191](https://github.com/tompave/fun_with_flags/pull/191))
-* Adding a suite of synthetic benchmark scripts for the package. ([pull/193](https://github.com/tompave/fun_with_flags/pull/193))
+* Add a suite of synthetic benchmark scripts for the package. ([pull/193](https://github.com/tompave/fun_with_flags/pull/193))
 
 ## v1.12.0
 

README.md

@@ -42,6 +42,7 @@ It stores flag information in Redis or a relational DB (PostgreSQL, MySQL, or SQ
   - [PubSub Adapters](#pubsub-adapters)
 * [Extensibility](#extensibility)
   - [Custom Persistence Adapters](#custom-persistence-adapters)
+* [Telemetry](#telemetry)
 * [Application Start Behaviour](#application-start-behaviour)
 * [Testing](#testing)
 * [Development](#development)
@@ -705,6 +706,11 @@ And then configure the library to use it:
 ```elixir
 config :fun_with_flags, :persistence, adapter: MyApp.MyAlternativeFlagStore
 ```
+## Telemetry
+
+FunWithFlags is instrumented with [Telemetry](https://hex.pm/packages/telemetry) and emits events at runtime. Please refer to the [Telemetry docs](https://hexdocs.pm/telemetry/readme.html) for detailed instructions on how to consume the emitted events.
+
+The full list of events emitted by FunWithFlags are documented in the [FunWithFlags.Telemetry](https://hexdocs.pm/fun_with_flags/FunWithFlags.Telemetry.html) module.
 
 ## Application Start Behaviour
 

lib/fun_with_flags/telemetry.ex

@@ -2,22 +2,83 @@ defmodule FunWithFlags.Telemetry do
   @moduledoc """
   Telemetry events for FunWithFlags.
 
-  This module is responsible for emitting [Telemetry](https://hex.pm/packages/telemetry) events for FunWithFlags.
+  This module centralizes the emission of all [Telemetry](https://hexdocs.pm/telemetry/readme.html)
+  events for the package.
 
   ## Events
 
+  The common prefix for all events is `:fun_with_flags`, followed by a logical
+  scope (e.g. `:persistence`) and the event name.
+
+  Events are simple "point in time" events rather than span events (that is,
+  there is no distinct `:start` and `:stop` events with a duration measurement).
 
   ### Persistence
 
-  * `[:fun_with_flags, :persistence, :read]`
-  * `[:fun_with_flags, :persistence, :read_all_flags]`
-  * `[:fun_with_flags, :persistence, :read_all_flag_names]`
-  * `[:fun_with_flags, :persistence, :write]`
-  * `[:fun_with_flags, :persistence, :delete_flag]`
-  * `[:fun_with_flags, :persistence, :delete_gate]`
-  * `[:fun_with_flags, :persistence, :reload]`
-  * `[:fun_with_flags, :persistence, :error]`
+  Events for CRUD operations on the persistent datastore.
+
+  All events contain the same measurement:
+  * `system_time` (integer), which is the current system time in the
+    `:native` time unit. See `:erlang.system_time/0`.
+
+  Events:
+
+  * `[:fun_with_flags, :persistence, :read]`, emitted when a flag is read from
+    the DB. Crucially, this event is not emitted when the cache is enabled and
+    there is a cache hit, and it's emitted only when retrieving a flag reads
+    from the persistent datastore. Therefore, when the cache is disabled, this
+    event is always emitted every time a flag is queried.
+
+    Metadata:
+    * `flag_name` (string), the name of the flag being read.
+
+  * `[:fun_with_flags, :persistence, :read_all_flags]`, emitted when all flags
+    are read from the DB. No extra metadata.
+
+  * `[:fun_with_flags, :persistence, :read_all_flag_names]`, emitted when all
+    flags names are read from the DB. No extra metadata.
+
+  * `[:fun_with_flags, :persistence, :write]`, emitted when writing a flag to
+    the DB. In practive, what is written is one of the gates of the flag, which
+    is always upserted.
+
+    Metadata:
+    * `flag_name` (string), the name of the flag being written.
+    * `gate` (`FunWithFlags.Gate`), the gate being upserted.
+
+  * `[:fun_with_flags, :persistence, :delete_flag]`, emitted when an entire flag
+    is deleted from the DB.
+
+    Metadata:
+    * `flag_name` (string), the name of the flag being deleted.
+
+  * `[:fun_with_flags, :persistence, :delete_gate]`, emitted when one of the flag's
+    gates is deleted from the DB.
+
+    Metadata:
+    * `flag_name` (string), the name of the flag whose gate is being deleted.
+    * `gate` (`FunWithFlags.Gate`), the gate being deleted.
+
+  * `[:fun_with_flags, :persistence, :reload]`, emitted when a flag is reloaded
+    from the DB. This typically happens when the node has received a change
+    notification for a flag, which results in the cache being invalidated and
+    the flag being reloaded from the DB.
+
+    Metadata:
+    * `flag_name` (string), the name of the flag being reloaded.
+
+  * `[:fun_with_flags, :persistence, :error]`, emitted for erorrs in any of the
+    above operations.
 
+    Metadata:
+    * `error` (any), the error that occurred. This is typically a string or any
+      appropriate error term returned by the underlying persistence adapters.
+    * `original_event` (atom), the name of the original event that failed, e.g.
+      `:read`, `:write`, `:delete_gate`, etc.
+    * `flag_name` (string), the name of the flag being operated on, if supported
+      by the original event.
+    * `gate` (`FunWithFlags.Gate`), the gate being operated on, if supported by
+      the original event.
   """
 
   require Logger