feat(opentelemetry_nebulex): add database semantic convention attributes (#600)

Adds OpenTelemetry semantic convention attributes for better cache operation observability:
- db.system: The database/cache backend system (e.g., :ets)
- db.operation.name: The cache operation being performed (e.g., :get, :put)
- db.query.text: Human-readable query showing the cache key being accessed

This provides standardized attributes following OTel SemConv v1.27+ and improves debugging by making cache keys visible in traces.

Author: yordis

instrumentation/opentelemetry_nebulex/lib/opentelemetry_nebulex.ex

@@ -4,6 +4,9 @@ defmodule OpentelemetryNebulex do
   from Nebulex command events.
   """
 
+  alias OpenTelemetry.SemConv.Incubating.DBAttributes
+  alias OpentelemetryNebulex.NebulexAttributes
+
   @tracer_id __MODULE__
 
   @doc """
@@ -66,11 +69,13 @@ defmodule OpentelemetryNebulex do
 
     attributes =
       %{
-        "nebulex.cache": metadata.adapter_meta.cache
+        NebulexAttributes.nebulex_cache() => metadata.adapter_meta.cache,
+        DBAttributes.db_system() => metadata.adapter_meta[:backend],
+        DBAttributes.db_operation_name() => db_operation(metadata),
+        DBAttributes.db_query_text() => db_statement(metadata)
       }
-      |> maybe_put(:"nebulex.backend", metadata.adapter_meta[:backend])
-      |> maybe_put(:"nebulex.keyslot", metadata.adapter_meta[:keyslot])
-      |> maybe_put(:"nebulex.model", metadata.adapter_meta[:model])
+      |> maybe_put(NebulexAttributes.nebulex_keyslot(), metadata.adapter_meta[:keyslot])
+      |> maybe_put(NebulexAttributes.nebulex_model(), metadata.adapter_meta[:model])
 
     OpentelemetryTelemetry.start_telemetry_span(@tracer_id, span_name, metadata, %{
       attributes: attributes
@@ -82,7 +87,7 @@ defmodule OpentelemetryNebulex do
     ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, metadata)
 
     if action = extract_action(metadata) do
-      OpenTelemetry.Span.set_attribute(ctx, :"nebulex.action", action)
+      OpenTelemetry.Span.set_attribute(ctx, NebulexAttributes.nebulex_action(), action)
     end
 
     OpentelemetryTelemetry.end_telemetry_span(@tracer_id, metadata)
@@ -108,4 +113,11 @@ defmodule OpentelemetryNebulex do
 
   defp format_error(exception) when is_exception(exception), do: Exception.message(exception)
   defp format_error(error), do: inspect(error)
+
+  defp db_operation(%{function_name: operation}), do: operation
+  defp db_operation(_), do: nil
+
+  defp db_statement(%{function_name: :get, args: [key]}), do: "GET #{inspect(key)}"
+  defp db_statement(%{function_name: :put, args: [key | _tail]}), do: "PUT #{inspect(key)}"
+  defp db_statement(_), do: nil
 end

instrumentation/opentelemetry_nebulex/lib/opentelemetry_nebulex/nebulex_attributes.ex

@@ -0,0 +1,34 @@
+defmodule OpentelemetryNebulex.NebulexAttributes do
+  @moduledoc false
+
+  # Nebulex-specific OpenTelemetry Semantic Conventions attributes.
+  #
+  # Naming Conventions:
+  # - Prefix with `nebulex.` to avoid conflicts with standard OTel attributes
+  # - Use `snake_case` for attribute names
+  # - Use dot notation for namespacing (e.g., `nebulex.cache`)
+
+  @doc """
+  The name of the Nebulex cache being accessed.
+  """
+  @spec nebulex_cache() :: :"nebulex.cache"
+  def nebulex_cache, do: :"nebulex.cache"
+
+  @doc """
+  The keyslot module used for partitioned caches.
+  """
+  @spec nebulex_keyslot() :: :"nebulex.keyslot"
+  def nebulex_keyslot, do: :"nebulex.keyslot"
+
+  @doc """
+  The cache model used by multilevel caches.
+  """
+  @spec nebulex_model() :: :"nebulex.model"
+  def nebulex_model, do: :"nebulex.model"
+
+  @doc """
+  The result of a cache operation (`:hit` or `:miss`).
+  """
+  @spec nebulex_action() :: :"nebulex.action"
+  def nebulex_action, do: :"nebulex.action"
+end

instrumentation/opentelemetry_nebulex/mix.exs

@@ -60,6 +60,7 @@ defmodule OpentelemetryNebulex.MixProject do
       {:opentelemetry, "~> 1.5", only: [:dev, :test]},
       {:opentelemetry_api, "~> 1.4"},
       {:opentelemetry_exporter, "~> 1.8", only: [:dev, :test]},
+      {:opentelemetry_semantic_conventions, "~> 1.27"},
       {:opentelemetry_telemetry, "~> 1.1"},
       {:telemetry, "~> 1.0"}
     ]

instrumentation/opentelemetry_nebulex/mix.lock

@@ -17,6 +17,7 @@
   "opentelemetry": {:hex, :opentelemetry, "1.5.0", "7dda6551edfc3050ea4b0b40c0d2570423d6372b97e9c60793263ef62c53c3c2", [:rebar3], [{:opentelemetry_api, "~> 1.4", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}], "hexpm", "cdf4f51d17b592fc592b9a75f86a6f808c23044ba7cf7b9534debbcc5c23b0ee"},
   "opentelemetry_api": {:hex, :opentelemetry_api, "1.4.0", "63ca1742f92f00059298f478048dfb826f4b20d49534493d6919a0db39b6db04", [:mix, :rebar3], [], "hexpm", "3dfbbfaa2c2ed3121c5c483162836c4f9027def469c41578af5ef32589fcfc58"},
   "opentelemetry_exporter": {:hex, :opentelemetry_exporter, "1.8.0", "5d546123230771ef4174e37bedfd77e3374913304cd6ea3ca82a2add49cd5d56", [:rebar3], [{:grpcbox, ">= 0.0.0", [hex: :grpcbox, repo: "hexpm", optional: false]}, {:opentelemetry, "~> 1.5.0", [hex: :opentelemetry, repo: "hexpm", optional: false]}, {:opentelemetry_api, "~> 1.4.0", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}, {:tls_certificate_check, "~> 1.18", [hex: :tls_certificate_check, repo: "hexpm", optional: false]}], "hexpm", "a1f9f271f8d3b02b81462a6bfef7075fd8457fdb06adff5d2537df5e2264d9af"},
+  "opentelemetry_semantic_conventions": {:hex, :opentelemetry_semantic_conventions, "1.27.0", "acd0194a94a1e57d63da982ee9f4a9f88834ae0b31b0bd850815fe9be4bbb45f", [:mix, :rebar3], [], "hexpm", "9681ccaa24fd3d810b4461581717661fd85ff7019b082c2dff89c7d5b1fc2864"},
   "opentelemetry_telemetry": {:hex, :opentelemetry_telemetry, "1.1.2", "410ab4d76b0921f42dbccbe5a7c831b8125282850be649ee1f70050d3961118a", [:mix, :rebar3], [{:opentelemetry_api, "~> 1.3", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}, {:telemetry, "~> 1.1", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "641ab469deb181957ac6d59bce6e1321d5fe2a56df444fc9c19afcad623ab253"},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.7", "354c321cf377240c7b8716899e182ce4890c5938111a1296add3ec74cf1715df", [:make, :mix, :rebar3], [], "hexpm", "fe4c190e8f37401d30167c8c405eda19469f34577987c76dde613e838bbc67f8"},
   "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},

instrumentation/opentelemetry_nebulex/test/opentelemetry_nebulex_test.exs

@@ -67,8 +67,10 @@ defmodule OpentelemetryNebulexTest do
 
     assert %{
              "nebulex.action": :miss,
-             "nebulex.backend": :ets,
-             "nebulex.cache": OpentelemetryNebulexTest.Local
+             "nebulex.cache": OpentelemetryNebulexTest.Local,
+             "db.system": :ets,
+             "db.operation.name": :get,
+             "db.query.text": "GET :my_key"
            } = :otel_attributes.map(attributes)
 
     # write
@@ -77,8 +79,10 @@ defmodule OpentelemetryNebulexTest do
     assert_receive {:span, span(name: "nebulex put", kind: :internal, attributes: attributes)}
 
     assert %{
-             "nebulex.backend": :ets,
-             "nebulex.cache": OpentelemetryNebulexTest.Local
+             "nebulex.cache": OpentelemetryNebulexTest.Local,
+             "db.system": :ets,
+             "db.operation.name": :put,
+             "db.query.text": "PUT :my_key"
            } = :otel_attributes.map(attributes)
 
     # hit
@@ -88,8 +92,10 @@ defmodule OpentelemetryNebulexTest do
 
     assert %{
              "nebulex.action": :hit,
-             "nebulex.backend": :ets,
-             "nebulex.cache": OpentelemetryNebulexTest.Local
+             "nebulex.cache": OpentelemetryNebulexTest.Local,
+             "db.system": :ets,
+             "db.operation.name": :get,
+             "db.query.text": "GET :my_key"
            } = :otel_attributes.map(attributes)
   end
 
@@ -106,7 +112,7 @@ defmodule OpentelemetryNebulexTest do
 
     assert %{
              "nebulex.action": :miss,
-             "nebulex.backend": :ets,
+             "db.system": :ets,
              "nebulex.cache": OpentelemetryNebulexTest.Partitioned.Primary
            } = :otel_attributes.map(attributes)
 
@@ -124,7 +130,7 @@ defmodule OpentelemetryNebulexTest do
     assert_receive {:span, span(name: "nebulex put", kind: :internal, attributes: attributes)}
 
     assert %{
-             "nebulex.backend": :ets,
+             "db.system": :ets,
              "nebulex.cache": OpentelemetryNebulexTest.Partitioned.Primary
            } = :otel_attributes.map(attributes)
 
@@ -142,7 +148,7 @@ defmodule OpentelemetryNebulexTest do
 
     assert %{
              "nebulex.action": :hit,
-             "nebulex.backend": :ets,
+             "db.system": :ets,
              "nebulex.cache": OpentelemetryNebulexTest.Partitioned.Primary
            } = :otel_attributes.map(attributes)
 
@@ -176,7 +182,7 @@ defmodule OpentelemetryNebulexTest do
     assert_receive {:span, span(name: "nebulex put", kind: :internal, attributes: attributes)}
 
     assert %{
-             "nebulex.backend": :ets,
+             "db.system": :ets,
              "nebulex.cache": OpentelemetryNebulexTest.Multilevel.L1
            } = :otel_attributes.map(attributes)
 
@@ -200,7 +206,7 @@ defmodule OpentelemetryNebulexTest do
 
     assert %{
              "nebulex.action": :hit,
-             "nebulex.backend": :ets,
+             "db.system": :ets,
              "nebulex.cache": OpentelemetryNebulexTest.Multilevel.L1
            } = :otel_attributes.map(attributes)