feat: enhance telemetry system with comprehensive event logging

- Replace Logger.debug calls with structured telemetry events throughout the system
- Add new telemetry events for worker lifecycle, session management, and cleanup operations
- Implement TelemetryLogger module for backward-compatible logging behavior
- Add helper functions for session module detection and enhanced metadata collection
- Provide configurable event handlers for different logging levels and event types

Author: GSMLG-BOT

lib/phoenix/session_process/cleanup.ex

@@ -97,7 +97,8 @@ defmodule Phoenix.SessionProcess.Cleanup do
   @impl true
   def handle_info({:cleanup_session, session_id}, state) do
     if Phoenix.SessionProcess.ProcessSupervisor.session_process_started?(session_id) do
-      Logger.debug("Auto-cleanup expired session: #{session_id}")
+      session_pid = Phoenix.SessionProcess.ProcessSupervisor.session_process_pid(session_id)
+      Phoenix.SessionProcess.Telemetry.emit_auto_cleanup_event(session_id, Phoenix.SessionProcess.Helpers.get_session_module(session_pid), session_pid)
       Phoenix.SessionProcess.terminate(session_id)
     end
 

lib/phoenix/session_process/helpers.ex

@@ -177,4 +177,15 @@ defmodule Phoenix.SessionProcess.Helpers do
         {:error, reason}
     end
   end
+
+  @doc """
+  Gets the session module for a given process PID.
+  """
+  @spec get_session_module(pid()) :: module()
+  def get_session_module(pid) do
+    case Registry.lookup(Phoenix.SessionProcess.Registry, pid) do
+      [{_, module}] -> module
+      _ -> Phoenix.SessionProcess.Config.session_process()
+    end
+  end
 end

lib/phoenix/session_process/process_superviser.ex

@@ -126,7 +126,7 @@ defmodule Phoenix.SessionProcess.ProcessSupervisor do
   """
   def start_child(worker, worker_arg) do
     worker_spec = {worker, worker_arg}
-    Logger.debug("Start Child Worker: #{inspect(worker_spec)}")
+    Phoenix.SessionProcess.Telemetry.emit_worker_start(worker_spec)
     DynamicSupervisor.start_child(__MODULE__, worker_spec)
   end
 
@@ -143,7 +143,7 @@ defmodule Phoenix.SessionProcess.ProcessSupervisor do
   - `{:error, reason}` - Failed to terminate child process
   """
   def terminate_child(pid) do
-    Logger.debug("Terminating Child Worker: #{inspect(pid)}")
+    Phoenix.SessionProcess.Telemetry.emit_worker_terminate(pid)
     DynamicSupervisor.terminate_child(__MODULE__, pid)
   end
 
@@ -255,7 +255,7 @@ defmodule Phoenix.SessionProcess.ProcessSupervisor do
   """
   @spec terminate_session(binary()) :: :ok | {:error, :not_found}
   def terminate_session(session_id) do
-    Logger.debug("End Session: #{inspect(session_id)}")
+    Phoenix.SessionProcess.Telemetry.emit_session_end_event(session_id)
     start_time = System.monotonic_time()
 
     case session_process_pid(session_id) do
@@ -360,7 +360,7 @@ defmodule Phoenix.SessionProcess.ProcessSupervisor do
 
     with :ok <- validate_session_id(session_id),
          :ok <- check_session_limits() do
-      Logger.debug("Start Session: #{inspect(session_id)}")
+      Phoenix.SessionProcess.Telemetry.emit_session_start_event(session_id)
 
       worker_args =
         if arg, do: [name: child_name(session_id), arg: arg], else: [name: child_name(session_id)]

lib/phoenix/session_process/telemetry.ex

@@ -19,14 +19,24 @@ defmodule Phoenix.SessionProcess.Telemetry do
   - `[:phoenix, :session_process, :cast]` - When a cast is made to a session
   - `[:phoenix, :session_process, :communication_error]` - When communication fails
 
+  ### Process Management
+  - `[:phoenix, :session_process, :worker_start]` - When a worker process starts
+  - `[:phoenix, :session_process, :worker_terminate]` - When a worker process terminates
+  - `[:phoenix, :session_process, :session_start]` - When a session process starts
+  - `[:phoenix, :session_process, :session_end]` - When a session process ends
+
   ### Cleanup
+  - `[:phoenix, :session_process, :auto_cleanup]` - When a session is auto-cleaned up
   - `[:phoenix, :session_process, :cleanup]` - When a session is cleaned up
   - `[:phoenix, :session_process, :cleanup_error]` - When cleanup fails
 
   All events include the following metadata:
-  - `session_id` - The session ID
+  - `session_id` - The session ID (when applicable)
   - `module` - The session module
   - `pid` - The process PID (when applicable)
+  - `worker_spec` - Worker specification details (for worker events)
+  - `operation` - Operation type (for error events)
+  - `reason` - Error reason (for error events)
   - `measurements` - Performance measurements
   """
 
@@ -171,4 +181,64 @@ defmodule Phoenix.SessionProcess.Telemetry do
         :erlang.raise(kind, reason, __STACKTRACE__)
     end
   end
+
+  @doc """
+  Emits a telemetry event for worker process start.
+  """
+  @spec emit_worker_start(term(), keyword()) :: :ok
+  def emit_worker_start(worker_spec, measurements \\ []) do
+    :telemetry.execute(
+      [:phoenix, :session_process, :worker_start],
+      Map.new(measurements),
+      %{worker_spec: inspect(worker_spec)}
+    )
+  end
+
+  @doc """
+  Emits a telemetry event for worker process termination.
+  """
+  @spec emit_worker_terminate(pid(), keyword()) :: :ok
+  def emit_worker_terminate(pid, measurements \\ []) do
+    :telemetry.execute(
+      [:phoenix, :session_process, :worker_terminate],
+      Map.new(measurements),
+      %{pid: pid}
+    )
+  end
+
+  @doc """
+  Emits a telemetry event for session process start.
+  """
+  @spec emit_session_start_event(String.t(), atom(), pid(), keyword()) :: :ok
+  def emit_session_start_event(session_id, measurements \\ []) do
+    :telemetry.execute(
+      [:phoenix, :session_process, :session_start],
+      Map.new(measurements),
+      %{session_id: session_id}
+    )
+  end
+
+  @doc """
+  Emits a telemetry event for session process end.
+  """
+  @spec emit_session_end_event(String.t(), atom(), pid(), keyword()) :: :ok
+  def emit_session_end_event(session_id, measurements \\ []) do
+    :telemetry.execute(
+      [:phoenix, :session_process, :session_end],
+      Map.new(measurements),
+      %{session_id: session_id}
+    )
+  end
+
+  @doc """
+  Emits a telemetry event for automatic session cleanup.
+  """
+  @spec emit_auto_cleanup_event(String.t(), atom(), pid(), keyword()) :: :ok
+  def emit_auto_cleanup_event(session_id, module, pid, measurements \\ []) do
+    :telemetry.execute(
+      [:phoenix, :session_process, :auto_cleanup],
+      Map.new(measurements),
+      %{session_id: session_id, module: module, pid: pid}
+    )
+  end
 end