Improve SSL certificate logging (#2284)

This PR improves the SSL verification failure logging from:

```
2025-08-14T00:46:33Z app[48e4199b764518] iad level=notice msg="TLS :server: In state :certify at ssl_handshake.erl:2201 generated SERVER ALERT: Fatal - Handshake Failure - :unknown_ca" depth=20 report_cb=&:ssl_logger.format/1
```

to

```
2025-08-14T00:45:50Z app[48e4199b764518] iad level=info msg="SSL certificate verification failed" reason=":unknown_ca" event="nerves_hub.ssl.fail" cert_serial="1234" cert_subject="blah"
```

It involves some log filtering of messages from the Erlang SSL
application, and then hooking into some telemetry we already send.

Author: joshk

.cspell.json

@@ -130,6 +130,7 @@
     "sockname",
     "spex",
     "ssljson",
+    "statename",
     "statsd",
     "strftime",
     "stylesheet",

lib/nerves_hub/application.ex

@@ -13,13 +13,7 @@ defmodule NervesHub.Application do
     end
 
     setup_open_telemetry()
-
-    _ =
-      :logger.add_handler(:my_sentry_handler, Sentry.LoggerHandler, %{
-        config: %{metadata: [:file, :line]}
-      })
-
-    NervesHub.Logger.attach()
+    setup_logging()
 
     children =
       [{Finch, name: Swoosh.Finch}] ++
@@ -48,6 +42,18 @@ defmodule NervesHub.Application do
     Supervisor.start_link(children, opts)
   end
 
+  defp setup_logging() do
+    :ok =
+      :logger.add_handler(:sentry_handler, Sentry.LoggerHandler, %{
+        config: %{metadata: [:file, :line]}
+      })
+
+    :ok =
+      :logger.add_primary_filter(:filter_ssl_handshake, {&NervesHub.Logger.ssl_log_filter/2, []})
+
+    NervesHub.Logger.attach()
+  end
+
   defp setup_open_telemetry() do
     if System.get_env("ECTO_IPV6") do
       :ok = :httpc.set_option(:ipfamily, :inet6fb4)

lib/nerves_hub/logger.ex

@@ -35,7 +35,8 @@ defmodule NervesHub.Logger do
       [:nerves_hub, :devices, :update, :successful],
       [:nerves_hub, :managed_deployments, :set_deployment_group, :none_found],
       [:nerves_hub, :managed_deployments, :set_deployment_group, :one_found],
-      [:nerves_hub, :managed_deployments, :set_deployment_group, :multiple_found]
+      [:nerves_hub, :managed_deployments, :set_deployment_group, :multiple_found],
+      [:nerves_hub, :ssl, :fail]
     ]
 
     Enum.each(events, fn event ->
@@ -165,6 +166,40 @@ defmodule NervesHub.Logger do
     )
   end
 
+  def log_event([:nerves_hub, :ssl, :fail], _, metadata, _) do
+    Logger.info("SSL certificate verification failed",
+      event: "nerves_hub.ssl.fail",
+      reason: metadata[:reason],
+      cert_serial: metadata[:cert_serial],
+      cert_subject: metadata[:cert_subject]
+    )
+  end
+
+  @doc """
+  The Erlang SSL application will log issues or failures related to verification of certificates.
+
+  This filter is designed to ignore SSL handshake errors that occur during the `:certify` state that are not helpful or hard to understand.
+
+  eg. TLS :server: In state :certify at ssl_handshake.erl:2201 generated SERVER ALERT: Fatal - Handshake Failure - :unknown_ca
+  """
+  def ssl_log_filter(log_event, _opts) do
+    case log_event do
+      %{
+        msg:
+          {:report,
+           %{
+             alert: {:alert, _, _, %{file: ~c"ssl_handshake.erl"}, _, _},
+             role: :server,
+             statename: :certify
+           }}
+      } ->
+        :stop
+
+      _ ->
+        :ignore
+    end
+  end
+
   # Helper functions
 
   defp ignore_list() do

lib/nerves_hub/ssl.ex

@@ -85,24 +85,16 @@ defmodule NervesHub.SSL do
         {:valid, state}
 
       {:error, {:bad_cert, reason}} ->
-        :telemetry.execute([:nerves_hub, :ssl, :fail], %{count: 1})
-
-        {:fail, reason}
+        verify_failed(reason, otp_cert)
 
       {:error, _} ->
-        :telemetry.execute([:nerves_hub, :ssl, :fail], %{count: 1})
-
-        {:fail, :registration_failed}
+        verify_failed(:registration_failed, otp_cert)
 
       reason when is_atom(reason) ->
-        :telemetry.execute([:nerves_hub, :ssl, :fail], %{count: 1})
-
-        {:fail, reason}
+        verify_failed(reason, otp_cert)
 
       _ ->
-        :telemetry.execute([:nerves_hub, :ssl, :fail], %{count: 1})
-
-        {:fail, :unknown_server_error}
+        verify_failed(:unknown_server_error, otp_cert)
     end
   end
 
@@ -283,4 +275,17 @@ defmodule NervesHub.SSL do
       ski: Certificate.get_ski(otp_cert)
     }
   end
+
+  defp verify_failed(reason, otp_cert) do
+    cert_serial = Certificate.get_serial_number(otp_cert)
+    cert_subject = Certificate.get_common_name(otp_cert)
+
+    :telemetry.execute([:nerves_hub, :ssl, :fail], %{count: 1}, %{
+      reason: reason,
+      cert_serial: cert_serial,
+      cert_subject: cert_subject
+    })
+
+    {:fail, reason}
+  end
 end