refactor: improve event handling tests with realistic UUIDs and updated attributes

Enhanced the OpenTelemetry event handler tests by replacing hardcoded values with realistic UUIDs for event IDs, stream IDs, causation, and correlation IDs. Updated attribute assertions to reflect the new structure and naming conventions for projectors. Improved error handling tests to simulate realistic scenarios, ensuring better coverage and accuracy in telemetry data.

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

guides/howtos/setting-up-opentelemetry-tracing.md

@@ -44,20 +44,20 @@ Choose one of the following span relationship modes when calling `setup/1`:
 
 ```elixir
 # Create span links to the original command dispatch (default)
-Commanded.OpenTelemetry.setup(tracing: [span_relationship: :link])
+Commanded.OpenTelemetry.setup(event_handler: [span_relationship: :link])
 
 # Make event handler spans children of the command span
-Commanded.OpenTelemetry.setup(tracing: [span_relationship: :child])
+Commanded.OpenTelemetry.setup(event_handler: [span_relationship: :child])
 
 # No span propagation between commands and event handlers
-Commanded.OpenTelemetry.setup(tracing: [span_relationship: :none])
+Commanded.OpenTelemetry.setup(event_handler: [span_relationship: :none])
 ```
 
 Note: `setup/1` should only be called once during application startup.
 
 ## Disable Event Handler Tracing
 
 ```elixir
-Commanded.OpenTelemetry.setup(tracing: [event_handler: false])
+Commanded.OpenTelemetry.setup(event_handler: false)
 ```
 

lib/commanded/middleware/trace_context_propagator.ex

@@ -61,7 +61,6 @@ if Code.ensure_loaded?(:otel_propagator_text_map) do
       end
     end
 
-    @spec maybe_assign(%Pipeline{}, String.t(), {String.t(), String.t()} | nil) :: %Pipeline{}
     defp maybe_assign(pipeline, _key, nil), do: pipeline
 
     defp maybe_assign(pipeline, key, {_, value}),

lib/commanded/opentelemetry.ex

@@ -30,46 +30,44 @@ defmodule Commanded.OpenTelemetry do
 
         # ... your command routes
       end
+
+  ## Types
+
+  See `t:span_relationship/0` for available span relationship modes.
   """
 
   alias Commanded.OpenTelemetry.EventHandler
 
-  @schema [
-    tracer: [
-      type: :keyword_list,
-      default: [],
-      doc: "Tracer configuration",
-      keys: [
-        name: [
-          type: :atom,
-          default: :commanded,
-          doc: "Application name for OpenTelemetry tracer registration"
-        ]
-      ]
-    ],
-    tracing: [
-      type: :keyword_list,
-      default: [],
-      doc: "Tracing configuration",
-      keys: [
-        event_handler: [
-          type: :boolean,
-          default: true,
-          doc: "Trace event handling operations"
-        ],
-        span_relationship: [
-          type: {:in, [:link, :child, :none]},
-          default: :link,
-          doc: """
-          How event handlers relate to command spans:
-          * `:link` - Create span links to the original command dispatch (default)
-          * `:child` - Attach event handler spans as children of command span
-          * `:none` - No span propagation between commands and event handlers
-          """
-        ]
-      ]
-    ]
-  ]
+  @typedoc """
+  Determines how event handler spans relate to command dispatch spans.
+
+  * `:link` - Create span links to the original command dispatch (default).
+    Best for event-driven architectures where events are processed independently.
+  * `:child` - Attach event handler spans as children of the command span.
+    Best when you want a single trace tree for the entire command lifecycle.
+  * `:none` - No span propagation between commands and event handlers.
+    Best when events should start fresh traces.
+  """
+  @type span_relationship :: :link | :child | :none
+
+  @nimble_schema NimbleOptions.new!(
+                   event_handler: [
+                     type:
+                       {:or,
+                        [
+                          {:in, [:disabled]},
+                          keyword_list: [
+                            span_relationship: [
+                              type: {:in, [:link, :child, :none]},
+                              type_doc: "`t:span_relationship/0`",
+                              default: :link
+                            ]
+                          ]
+                        ]},
+                     default: [],
+                     doc: "Event handler tracing configuration. Use `:disabled` to disable."
+                   ]
+                 )
 
   @doc """
   Set up OpenTelemetry tracing for Commanded.
@@ -78,52 +76,27 @@ defmodule Commanded.OpenTelemetry do
 
   ## Options
 
-  #{NimbleOptions.docs(@schema)}
+  #{NimbleOptions.docs(@nimble_schema)}
 
   ## Examples
 
-      # Default setup
+      # Default setup (uses :link relationship)
       Commanded.OpenTelemetry.setup()
 
-      # With custom tracer name
-      Commanded.OpenTelemetry.setup(tracer: [name: :my_app])
-
       # Disable event handler tracing
-      Commanded.OpenTelemetry.setup(tracing: [event_handler: false])
+      Commanded.OpenTelemetry.setup(event_handler: :disabled)
 
       # Use parent-child relationships for event handlers
-      Commanded.OpenTelemetry.setup(tracing: [span_relationship: :child])
+      Commanded.OpenTelemetry.setup(event_handler: [span_relationship: :child])
 
   """
-  @spec setup(keyword()) :: :ok | {:error, :already_exists}
+  @spec setup(keyword()) :: :ok
   def setup(opts \\ []) do
-    opts = NimbleOptions.validate!(opts, @schema)
-
-    if opts[:tracing][:event_handler] do
-      case EventHandler.setup(
-             tracer_name: opts[:tracer][:name],
-             span_relationship: opts[:tracing][:span_relationship]
-           ) do
-        :ok -> :ok
-        {:error, :already_exists} = error -> error
-      end
-    else
-      :ok
-    end
-  end
+    opts = NimbleOptions.validate!(opts, @nimble_schema)
 
-  @doc """
-  Detach all OpenTelemetry telemetry handlers.
-
-  Use this to clean up handlers, for example in tests or when reconfiguring.
-
-  ## Example
-
-      Commanded.OpenTelemetry.detach()
-
-  """
-  @spec detach() :: :ok
-  def detach do
-    EventHandler.detach()
+    case opts[:event_handler] do
+      :disabled -> :ok
+      config -> EventHandler.setup(config)
+    end
   end
 end

lib/commanded/opentelemetry/event_handler.ex

@@ -7,25 +7,17 @@ defmodule Commanded.OpenTelemetry.EventHandler do
   alias OpenTelemetry.SemConv.Incubating.MessagingAttributes
   alias OpenTelemetry.Span
 
-  @default_tracer_id __MODULE__
+  @tracer_id __MODULE__
 
-  @typedoc "Span relationship configuration"
-  @type span_relationship :: :link | :child | :none
-
-  @typedoc "Setup options"
-  @type setup_opts :: [tracer_name: atom(), span_relationship: span_relationship()]
-
-  @typedoc "Handler configuration stored in telemetry handler config"
-  @type handler_config :: %{tracer_id: atom(), span_relationship: span_relationship()}
-
-  @doc false
-  @spec setup(setup_opts()) :: :ok | {:error, :already_exists}
   def setup(opts \\ []) do
-    tracer_name = opts[:tracer_name] || @default_tracer_id
-    span_relationship = opts[:span_relationship] || :link
-    config = %{tracer_id: tracer_name, span_relationship: span_relationship}
+    span_relationship = Keyword.get(opts, :span_relationship, :link)
+    config = %{span_relationship: span_relationship}
+
+    :ok = attach_handle_handlers(config)
+    :ok = attach_batch_handlers(config)
+  end
 
-    # Single event handlers
+  defp attach_handle_handlers(config) do
     :telemetry.attach_many(
       {__MODULE__, :handle},
       [
@@ -36,8 +28,9 @@ defmodule Commanded.OpenTelemetry.EventHandler do
       &__MODULE__.handle_telemetry_event/4,
       config
     )
+  end
 
-    # Batch event handlers
+  defp attach_batch_handlers(config) do
     :telemetry.attach_many(
       {__MODULE__, :batch},
       [
@@ -50,22 +43,6 @@ defmodule Commanded.OpenTelemetry.EventHandler do
     )
   end
 
-  @doc false
-  @spec detach() :: :ok
-  def detach do
-    :telemetry.detach({__MODULE__, :handle})
-    :telemetry.detach({__MODULE__, :batch})
-    :ok
-  end
-
-  # Single event handler dispatcher
-  @doc false
-  @spec handle_telemetry_event(
-          :telemetry.event_name(),
-          :telemetry.event_measurements(),
-          :telemetry.event_metadata(),
-          handler_config()
-        ) :: OpenTelemetry.span_ctx() | :ok
   def handle_telemetry_event([:commanded, :event, :handle, :start], measurements, meta, config),
     do: handle_start(measurements, meta, config)
 
@@ -80,14 +57,6 @@ defmodule Commanded.OpenTelemetry.EventHandler do
       ),
       do: handle_exception(measurements, meta, config)
 
-  # Batch event handler dispatcher
-  @doc false
-  @spec batch_telemetry_event(
-          :telemetry.event_name(),
-          :telemetry.event_measurements(),
-          :telemetry.event_metadata(),
-          handler_config()
-        ) :: OpenTelemetry.span_ctx() | :ok
   def batch_telemetry_event([:commanded, :event, :batch, :start], measurements, meta, config),
     do: batch_start(measurements, meta, config)
 
@@ -158,8 +127,6 @@ defmodule Commanded.OpenTelemetry.EventHandler do
     # TODO: Add last_seen_event attribute when available in Commanded telemetry
     # "event.last_seen": meta.last_seen_event
 
-    tracer_id = config.tracer_id
-
     span_opts = %{
       kind: :consumer,
       attributes: attributes
@@ -173,31 +140,29 @@ defmodule Commanded.OpenTelemetry.EventHandler do
       end
 
     OpentelemetryTelemetry.start_telemetry_span(
-      tracer_id,
+      @tracer_id,
       "commanded.event.handle",
       meta,
       span_opts
     )
   end
 
-  defp handle_stop(_measurements, meta, config) do
-    tracer_id = config.tracer_id
-    ctx = OpentelemetryTelemetry.set_current_telemetry_span(tracer_id, meta)
+  defp handle_stop(_measurements, meta, _config) do
+    ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)
 
     if error = meta[:error] do
       Span.set_status(ctx, OpenTelemetry.status(:error, inspect(error)))
     end
 
-    OpentelemetryTelemetry.end_telemetry_span(tracer_id, meta)
+    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
   end
 
   defp handle_exception(
          _measurements,
          %{kind: kind, reason: reason, stacktrace: stacktrace} = meta,
-         config
+         _config
        ) do
-    tracer_id = config.tracer_id
-    ctx = OpentelemetryTelemetry.set_current_telemetry_span(tracer_id, meta)
+    ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)
 
     # Add exception kind as attribute for better debugging
     Span.set_attribute(ctx, :"exception.kind", kind)
@@ -209,12 +174,12 @@ defmodule Commanded.OpenTelemetry.EventHandler do
     Span.record_exception(ctx, exception, stacktrace)
     Span.set_status(ctx, OpenTelemetry.status(:error, inspect(reason)))
 
-    OpentelemetryTelemetry.end_telemetry_span(tracer_id, meta)
+    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
   end
 
   # Batch event handlers
 
-  defp batch_start(_measurements, meta, config) do
+  defp batch_start(_measurements, meta, _config) do
     # Note: Batch telemetry metadata does not include individual recorded_events,
     # only first_event_id, last_event_id, and event_count. Therefore, we cannot
     # create span links to individual command dispatch traces for batch events.
@@ -247,39 +212,35 @@ defmodule Commanded.OpenTelemetry.EventHandler do
       {CommandedAttributes.commanded_batch_last_event_id(), meta.last_event_id}
     ]
 
-    tracer_id = config.tracer_id
-
     span_opts = %{
       kind: :consumer,
       attributes: attributes
     }
 
     OpentelemetryTelemetry.start_telemetry_span(
-      tracer_id,
+      @tracer_id,
       "commanded.event.batch",
       meta,
       span_opts
     )
   end
 
-  defp batch_stop(_measurements, meta, config) do
-    tracer_id = config.tracer_id
-    ctx = OpentelemetryTelemetry.set_current_telemetry_span(tracer_id, meta)
+  defp batch_stop(_measurements, meta, _config) do
+    ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)
 
     if error = meta[:error] do
       Span.set_status(ctx, OpenTelemetry.status(:error, inspect(error)))
     end
 
-    OpentelemetryTelemetry.end_telemetry_span(tracer_id, meta)
+    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
   end
 
   defp batch_exception(
          _measurements,
          %{kind: kind, reason: reason, stacktrace: stacktrace} = meta,
-         config
+         _config
        ) do
-    tracer_id = config.tracer_id
-    ctx = OpentelemetryTelemetry.set_current_telemetry_span(tracer_id, meta)
+    ctx = OpentelemetryTelemetry.set_current_telemetry_span(@tracer_id, meta)
 
     # Add exception kind as attribute for better debugging
     Span.set_attribute(ctx, :"exception.kind", kind)
@@ -291,6 +252,6 @@ defmodule Commanded.OpenTelemetry.EventHandler do
     Span.record_exception(ctx, exception, stacktrace)
     Span.set_status(ctx, OpenTelemetry.status(:error, inspect(reason)))
 
-    OpentelemetryTelemetry.end_telemetry_span(tracer_id, meta)
+    OpentelemetryTelemetry.end_telemetry_span(@tracer_id, meta)
   end
 end