feat(caching): add decorator context to telemetry metadata (#248)

Author: cabol

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v3.0.0](https://github.com/elixir-nebulex/nebulex/tree/v3.0.0) (2026-02-17)
+## [v3.0.0](https://github.com/elixir-nebulex/nebulex/tree/v3.0.0) (2026-02-21)
 > [Full Changelog](https://github.com/elixir-nebulex/nebulex/compare/v3.0.0-rc.2...v3.0.0)
 
 ### Enhancements
@@ -21,6 +21,19 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   decorator level, with decorator-level settings overriding module-level
   defaults.
   [#248](https://github.com/elixir-nebulex/nebulex/issues/248).
+- [Nebulex.Caching.Decorators] Decorator-invoked cache operations
+  (`cacheable`, `cache_put`, `cache_evict`) now automatically inject the
+  `:decorator_context` into the `:telemetry_metadata` option. This enables
+  telemetry handlers to identify which decorated function triggered each
+  cache operation. The `:decorator_context` map includes `:decorator`,
+  `:module`, `:function_name`, and `:arity`.
+  [#251](https://github.com/elixir-nebulex/nebulex/issues/251).
+- [Nebulex.Caching.Decorators] The `cache_evict` decorator now properly
+  passes `opts` through all eviction paths (`delete`, `delete_all`),
+  ensuring telemetry metadata propagates consistently.
+- [Nebulex.Adapter] The `:telemetry_metadata` and `:telemetry_event`
+  options are now extracted from `opts` before passing them to the adapter
+  callback, keeping adapter args clean.
 - [Nebulex.Adapters.Coherent] Added new coherent cache adapter to
   `nebulex_distributed`. The coherent adapter provides a "local cache with
   distributed invalidation" pattern where each node maintains its own
@@ -129,8 +142,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   `use Nebulex.Caching` (instead of adding them to every single decorated
   function): `:cache`, `:on_error`, `:match`, and `:opts`.
 
-[q_spec]: http://hexdocs.pm/nebulex/3.0.0-rc.1/Nebulex.Cache.html#c:get_all/2-query-specification
-[match_ref]: http://hexdocs.pm/nebulex/3.0.0-rc.1/Nebulex.Caching.Decorators.html#cacheable/3-the-match-function-on-references
+[q_spec]: https://hexdocs.pm/nebulex/Nebulex.Cache.html#c:get_all/2-query-specification
+[match_ref]: https://hexdocs.pm/nebulex/Nebulex.Caching.Decorators.html#cacheable/3-the-match-function-on-references
 
 ### Backwards incompatible changes
 

lib/nebulex/adapter.ex

@@ -147,19 +147,24 @@ defmodule Nebulex.Adapter do
       ) do
     opts = Options.validate_runtime_shared_opts!(opts)
     {telemetry?, opts} = Keyword.pop_first(opts, :telemetry, telemetry?)
-    args = args ++ [opts]
 
     if telemetry? do
+      {telemetry_metadata, opts} = Keyword.pop_first(opts, :telemetry_metadata, %{})
+
+      {telemetry_event, opts} =
+        Keyword.pop_first(opts, :telemetry_event, telemetry_prefix ++ [:command])
+
+      args = args ++ [opts]
+
       metadata = %{
         adapter_meta: adapter_meta,
         command: command,
         args: args,
-        extra_metadata: Keyword.get(opts, :telemetry_metadata, %{})
+        extra_metadata: telemetry_metadata
       }
 
-      opts
-      |> Keyword.get(:telemetry_event, telemetry_prefix ++ [:command])
-      |> Telemetry.span(
+      Telemetry.span(
+        telemetry_event,
         metadata,
         fn ->
           result = apply(adapter, command, [adapter_meta | args])
@@ -168,7 +173,7 @@ defmodule Nebulex.Adapter do
         end
       )
     else
-      apply(adapter, command, [adapter_meta | args])
+      apply(adapter, command, [adapter_meta | args ++ [opts]])
     end
   end
 

lib/nebulex/cache.ex

@@ -144,7 +144,7 @@ defmodule Nebulex.Cache do
       first one, since the adapter's metadata is available in the event's
       metadata.
     * `:extra_metadata` - Additional metadata through the runtime option
-      `:telemetry_metadata.`
+      `:telemetry_metadata`.
 
   Example event data:
 
@@ -176,7 +176,7 @@ defmodule Nebulex.Cache do
       first one, since the adapter's metadata is available in the event's
       metadata.
     * `:extra_metadata` - Additional metadata through the runtime option
-      `:telemetry_metadata.`
+      `:telemetry_metadata`.
     * `:result` - The command's result.
 
   Example event data:
@@ -211,7 +211,7 @@ defmodule Nebulex.Cache do
       first one, since the adapter's metadata is available in the event's
       metadata.
     * `:extra_metadata` - Additional metadata through the runtime option
-      `:telemetry_metadata.`
+      `:telemetry_metadata`.
     * `:kind` - The type of the error: `:error`, `:exit`, or `:throw`.
     * `:reason` - The reason of the error.
     * `:stacktrace` - Exception's stack trace.

lib/nebulex/caching/decorators.ex

@@ -1784,14 +1784,14 @@ if Code.ensure_loaded?(Decorator.Define) do
         opts = unquote(opts_var)
 
         # Push the decorator context onto the stack
-        Context.push(unquote(context))
+        _ignore = Context.push(unquote(context))
 
         try do
           # Execute the decorated function's code block
           unquote(action_block)
         after
           # Pop the decorator context from the stack
-          Context.pop()
+          _ignore = Context.pop()
         end
       end
     end
@@ -1917,6 +1917,7 @@ if Code.ensure_loaded?(Decorator.Define) do
         Runtime.eval_cache_evict(
           cache,
           unquote(key),
+          opts,
           unquote(before_invocation?),
           unquote(all_entries?),
           unquote(on_error),
@@ -1970,8 +1971,6 @@ if Code.ensure_loaded?(Decorator.Define) do
       end
     end
 
-    ## Private functions
-
     defp on_error_opt(attrs, default) do
       get_option(attrs, :on_error, ":raise or :nothing", &(&1 in [:raise, :nothing]), default)
     end

lib/nebulex/caching/decorators/runtime.ex

@@ -21,18 +21,20 @@ defmodule Nebulex.Caching.Decorators.Runtime do
     context = Context.get()
     cache = eval_cache(cache, context)
     key = eval_key(key, context)
+    opts = add_telemetry_metadata(opts, context)
 
     do_eval_cacheable(cache, key, references, opts, match, on_error, block_fun)
   end
 
   @doc false
-  @spec eval_cache_evict(any(), any(), boolean(), boolean(), atom(), fun()) :: any()
-  def eval_cache_evict(cache, key, before?, all_entries?, on_error, block_fun) do
+  @spec eval_cache_evict(any(), any(), keyword(), boolean(), boolean(), atom(), fun()) :: any()
+  def eval_cache_evict(cache, key, opts, before?, all_entries?, on_error, block_fun) do
     context = Context.get()
     cache = eval_cache(cache, context)
     key = eval_key(key, context)
+    opts = add_telemetry_metadata(opts, context)
 
-    do_eval_cache_evict(cache, key, before?, all_entries?, on_error, block_fun)
+    do_eval_cache_evict(cache, key, opts, before?, all_entries?, on_error, block_fun)
   end
 
   @doc false
@@ -41,6 +43,7 @@ defmodule Nebulex.Caching.Decorators.Runtime do
     context = Context.get()
     cache = eval_cache(cache, context)
     key = eval_key(key, context)
+    opts = add_telemetry_metadata(opts, context)
 
     do_eval_cache_put(cache, key, value, opts, on_error, match)
   end
@@ -145,7 +148,7 @@ defmodule Nebulex.Caching.Decorators.Runtime do
       fn value ->
         with false <- do_eval_cache_put(ref_cache, ref_key, value, opts, on_error, match) do
           # The match returned `false`, remove the parent's key reference
-          _ignore = do_apply(cache, :delete, [key])
+          _ignore = do_apply(cache, :delete, [key, Keyword.take(opts, [:telemetry_metadata])])
 
           false
         end
@@ -154,7 +157,7 @@ defmodule Nebulex.Caching.Decorators.Runtime do
         case eval_function(match, value) do
           false ->
             # Remove the parent's key reference
-            _ignore = do_apply(cache, :delete, [key])
+            _ignore = do_apply(cache, :delete, [key, Keyword.take(opts, [:telemetry_metadata])])
 
             block_fun.()
 
@@ -227,48 +230,48 @@ defmodule Nebulex.Caching.Decorators.Runtime do
     raise reason
   end
 
-  defp do_eval_cache_evict(cache, key, true, all_entries?, on_error, block_fun) do
-    _ignore = do_evict(all_entries?, cache, key, on_error)
+  defp do_eval_cache_evict(cache, key, opts, true, all_entries?, on_error, block_fun) do
+    _ignore = do_evict(all_entries?, cache, key, opts, on_error)
 
     block_fun.()
   end
 
-  defp do_eval_cache_evict(cache, key, false, all_entries?, on_error, block_fun) do
+  defp do_eval_cache_evict(cache, key, opts, false, all_entries?, on_error, block_fun) do
     result = block_fun.()
 
-    _ignore = do_evict(all_entries?, cache, key, on_error)
+    _ignore = do_evict(all_entries?, cache, key, opts, on_error)
 
     result
   end
 
-  defp do_evict(false, cache, {:in, keys}, on_error) do
+  defp do_evict(false, cache, {:in, keys}, opts, on_error) do
     keys
     |> group_by_cache(cache)
     |> Enum.each(fn
       {cache, [key]} ->
-        run_cmd(cache, :delete, [key, []], on_error)
+        run_cmd(cache, :delete, [key, opts], on_error)
 
       {cache, keys} ->
-        run_cmd(cache, :delete_all, [[in: keys]], on_error)
+        run_cmd(cache, :delete_all, [[in: keys], opts], on_error)
     end)
   end
 
-  defp do_evict(false, cache, {:query, _} = q, on_error) do
-    run_cmd(cache, :delete_all, [[q]], on_error)
+  defp do_evict(false, cache, {:query, _} = q, opts, on_error) do
+    run_cmd(cache, :delete_all, [[q], opts], on_error)
   end
 
-  defp do_evict(false, cache, {:query, q, k}, on_error) do
-    _ignore = run_cmd(cache, :delete_all, [[{:query, q}]], on_error)
+  defp do_evict(false, cache, {:query, q, k}, opts, on_error) do
+    _ignore = run_cmd(cache, :delete_all, [[query: q], opts], on_error)
 
-    do_evict(false, cache, k, on_error)
+    do_evict(false, cache, k, opts, on_error)
   end
 
-  defp do_evict(false, cache, key, on_error) do
-    run_cmd(cache, :delete, [key, []], on_error)
+  defp do_evict(false, cache, key, opts, on_error) do
+    run_cmd(cache, :delete, [key, opts], on_error)
   end
 
-  defp do_evict(true, cache, _key, on_error) do
-    run_cmd(cache, :delete_all, [], on_error)
+  defp do_evict(true, cache, _key, opts, on_error) do
+    run_cmd(cache, :delete_all, [[query: nil], opts], on_error)
   end
 
   defp do_eval_cache_put(
@@ -354,6 +357,25 @@ defmodule Nebulex.Caching.Decorators.Runtime do
     )
   end
 
+  defp add_telemetry_metadata(opts, %Context{
+         decorator: decorator,
+         module: m,
+         function_name: f,
+         arity: a
+       }) do
+    ctx = %{
+      decorator: decorator,
+      module: m,
+      function_name: f,
+      arity: a
+    }
+
+    Keyword.update(opts, :telemetry_metadata, %{decorator_context: ctx}, fn
+      meta when is_map(meta) -> Map.put(meta, :decorator_context, ctx)
+      meta -> meta
+    end)
+  end
+
   @compile inline: [raise_invalid_cache: 1]
   @spec raise_invalid_cache(any()) :: no_return()
   defp raise_invalid_cache(cache) do

test/nebulex/caching_test.exs

@@ -245,6 +245,14 @@ defmodule Nebulex.CachingTest do
       refute Cache.get!(1)
     end
 
+    test "with invalid opts" do
+      assert_raise NimbleOptions.ValidationError,
+                   ~r"invalid value for :telemetry_metadata option: expected map, got: :invalid",
+                   fn ->
+                     get_with_invalid_opts(1)
+                   end
+    end
+
     test "with match function" do
       refute Cache.get!(:x)
       assert get_with_match(:x) == :x
@@ -751,6 +759,13 @@ defmodule Nebulex.CachingTest do
       refute Cache.get!(:b)
       refute Cache.get!(:e)
     end
+
+    test "with opts" do
+      assert set_keys(x: 1, y: 2, z: 3) == :ok
+
+      assert evict_with_opts(:x) == :x
+      refute Cache.get!(:x)
+    end
   end
 
   describe "option :key with a custom key generator in annotation" do
@@ -1063,11 +1078,19 @@ defmodule Nebulex.CachingTest do
     {x, y * 2}
   end
 
-  @decorate cacheable(cache: &__MODULE__.target_cache/0, opts: [ttl: 1000])
+  @decorate cacheable(
+              cache: &__MODULE__.target_cache/0,
+              opts: [ttl: 1000, telemetry_metadata: %{foo: :bar}]
+            )
   def get_with_opts(x) do
     x
   end
 
+  @decorate cacheable(opts: [ttl: 1000, telemetry_metadata: :invalid])
+  def get_with_invalid_opts(x) do
+    x
+  end
+
   @decorate cacheable()
   def get_false_with_side_effect(v) do
     _ = Cache.update!("side-effect", 1, &(&1 + 1))
@@ -1127,7 +1150,11 @@ defmodule Nebulex.CachingTest do
     end
   end
 
-  @decorate cache_put(cache: dynamic_cache(Cache, Cache), key: {:in, [x]}, opts: [ttl: 1000])
+  @decorate cache_put(
+              cache: dynamic_cache(Cache, Cache),
+              key: {:in, [x]},
+              opts: [ttl: 1000, telemetry_metadata: %{foo: :bar}]
+            )
   def update_with_opts(x) do
     x
   end
@@ -1164,6 +1191,11 @@ defmodule Nebulex.CachingTest do
     x
   end
 
+  @decorate cache_evict(key: x, opts: [telemetry_metadata: %{foo: :bar}])
+  def evict_with_opts(x) do
+    x
+  end
+
   @decorate cacheable(key: x)
   def multiple_clauses(x, y \\ 0)