Merge pull request #77 from aerosol/update-docs

Document telemetry events

README.md

@@ -148,7 +148,7 @@ In addition, you can manually renew item's ttl:
 ConCache.touch(:my_cache, :key)
 ```
 
-If you would like to set a custom ttl for specific key, you can pass a `Concache.Item`` struct instead of a raw value:
+If you would like to set a custom ttl for specific key, you can pass a `Concache.Item` struct instead of a raw value:
 
 ```elixir
 ConCache.put(:my_cache, :key, %ConCache.Item{value: "value", ttl: :timer.seconds(25)})
@@ -181,6 +181,33 @@ If needed, you may also pass false to `ttl_check_interval`. This effectively sto
 ]}
 ```
 
+### Telemetry
+
+As of 1.1.0, ConCache emits [telemetry](https://github.com/beam-telemetry/telemetry) events. This allows the user to instrument their application to collect metrics about cache utilization.
+
+Currently, ConCache emits the following events:
+
+ - `[:con_cache, :stats, :hit]` - when cache key lookup succeeds
+ - `[:con_cache, :stats, :miss]` - when cache key is not found
+
+Each event comes with `%ConCache{}` struct within its metadata.
+
+Example handler:
+
+```elixir
+defmodule MyApp.HitMissRatioTracker do
+  require Logger
+
+  def handle_event([:con_cache, :stats, :hit], _measurements, %{cache: %{name: cache_name}}, _config) do
+    # ... aggregate hits
+  end
+
+  def handle_event([:con_cache, :stats, :miss], _measurements, %{cache: %{name: cache_name}}, _config) do
+    # ... aggregate misses
+  end
+end
+```
+
 ## Supervision
 
 A call to `ConCache.start_link` (or `start`) creates the so called _cache owner process_. This is the process that is the owner of the underlying ETS table and also the process where TTL checks are performed. No other operation (such as get or put) runs in this process.

lib/con_cache.ex

@@ -222,6 +222,9 @@ defmodule ConCache do
   A read is always "dirty", meaning it doesn't block while someone is updating
   the item under the same key. A read doesn't expire TTL of the item, unless
   `touch_on_read` option is set while starting the cache.
+
+  Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, 
+  and `[:con_cache, :stats, :miss]` otherwise.
   """
   @spec get(t, key) :: value
   def get(cache_id, key) do
@@ -326,6 +329,9 @@ defmodule ConCache do
 
   Note: if the item is already in the cache, this function amounts to a simple get
   without any locking, so you can expect it to be fairly fast.
+
+  Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, 
+  and `[:con_cache, :stats, :miss]` otherwise.
   """
   @spec get_or_store(t, key, store_fun) :: value
   def get_or_store(cache_id, key, store_fun),
@@ -353,6 +359,9 @@ defmodule ConCache do
 
   Note: if the item is already in the cache, this function amounts to a simple get
   without any locking, so you can expect it to be fairly fast.
+
+  Emits `[:con_cache, :stats, :hit]` telemetry event if the item is found, 
+  and `[:con_cache, :stats, :miss]` otherwise.
   """
   @spec fetch_or_store(t, key, fetch_or_store_fun) :: {:ok, value} | {:error, any}
   def fetch_or_store(cache_id, key, fetch_or_store_fun),