feat: rename Monitoring to Telemetry with enhanced logging and render duration tracking

BREAKING CHANGE: `Phoenix.React.Monitoring` has been renamed to `Phoenix.React.Telemetry`

- Rename Phoenix.React.Monitoring module to Phoenix.React.Telemetry for better clarity
- Add structured logging with visual indicators (✓/✗) for success/error states
- Implement comprehensive render duration tracking across all render methods
- Add cache hit/miss telemetry events with automatic tracking in Cache module
- Enhance all logging with [Phoenix.React] prefix for better log filtering
- Add new telemetry functions: record_cache_hit/2 and record_cache_miss/2
- Improve measure/3 function with better error logging and duration tracking
- Update Server module to track and log render duration for all three methods:
  - render_to_readable_stream
  - render_to_string
  - render_to_static_markup
- Add comprehensive telemetry documentation to CLAUDE.md with examples
- Update all references in Deno runtime and integration tests
- Maintain backward compatibility for telemetry event names

Log format examples:
- Render: "[Phoenix.React] ✓ Rendered 'chart' in 45ms (method: render_to_string, result: ok)"
- Runtime: "[Phoenix.React] Runtime Bun started on port 5225"
- Cache: "[Phoenix.React] Cache hit for 'my_component' (method: render_to_string)"
- Build: "[Phoenix.React] ✓ Build completed for Bun in 1234ms (result: ok)"

Author: GSMLG-BOT

CLAUDE.md

@@ -24,7 +24,7 @@ The system consists of three main layers:
 - `Phoenix.React.Cache` - ETS-based caching layer with TTL support
 - `Phoenix.React.Helper` - Phoenix.Component integration with multiple rendering modes
 - `Phoenix.React.Config` - Centralized configuration management
-- `Phoenix.React.Monitoring` - Telemetry and performance monitoring
+- `Phoenix.React.Telemetry` - Telemetry and performance monitoring with structured logging
 - `Phoenix.React.Runtime.FileWatcher` - File watching for development hot reload
 
 ### Rendering Flow
@@ -247,6 +247,111 @@ hydrateRoot(container, <MyComponent data={window.data} />);
 - Cache can be disabled by setting `cache_ttl: 0`
 - ETS-based in-memory caching with automatic garbage collection
 - Cache invalidation occurs on component file changes in development
+- Cache hits/misses are automatically tracked via telemetry events
+
+## Telemetry and Monitoring
+
+Phoenix.React includes comprehensive telemetry support via `Phoenix.React.Telemetry` for monitoring performance and tracking events.
+
+### Telemetry Events
+
+The following telemetry events are emitted automatically:
+
+**Render Events** - `[:phoenix, :react, :render]`
+- Measurements: `%{duration: duration_ms}`
+- Metadata: `%{component: component, method: method, result: result, timestamp: timestamp}`
+- Logged as: `[Phoenix.React] ✓ Rendered 'chart' in 45ms (method: render_to_string, result: ok)`
+
+**Cache Events**
+- `[:phoenix, :react, :cache, :hit]` - Fired on cache hits
+- `[:phoenix, :react, :cache, :miss]` - Fired on cache misses
+- Metadata: `%{component: component, method: method, timestamp: timestamp}`
+
+**Runtime Events**
+- `[:phoenix, :react, :runtime_startup]` - Fired when runtime starts
+- `[:phoenix, :react, :runtime_shutdown]` - Fired when runtime stops
+- Metadata: `%{runtime: runtime_name, port: port, timestamp: timestamp}`
+
+**Build Events** - `[:phoenix, :react, :build]`
+- Measurements: `%{duration: duration_ms}`
+- Metadata: `%{runtime: runtime_name, result: result, timestamp: timestamp}`
+
+**File Change Events** - `[:phoenix, :react, :file_change]`
+- Metadata: `%{path: path, action: action, timestamp: timestamp}`
+
+### Attaching Telemetry Handlers
+
+Attach handlers in your application's telemetry module:
+
+```elixir
+defmodule MyApp.Telemetry do
+  def attach_handlers do
+    :telemetry.attach_many(
+      "phoenix-react-telemetry",
+      [
+        [:phoenix, :react, :render],
+        [:phoenix, :react, :cache, :hit],
+        [:phoenix, :react, :cache, :miss],
+        [:phoenix, :react, :runtime_startup],
+        [:phoenix, :react, :build]
+      ],
+      &handle_event/4,
+      %{}
+    )
+  end
+
+  def handle_event([:phoenix, :react, :render], %{duration: duration}, metadata, _config) do
+    # Send to your metrics system (Prometheus, StatsD, etc.)
+    MyMetrics.histogram("phoenix_react.render.duration", duration,
+      tags: ["component:#{metadata.component}", "method:#{metadata.method}"]
+    )
+  end
+
+  def handle_event([:phoenix, :react, :cache, :hit], _measurements, metadata, _config) do
+    MyMetrics.increment("phoenix_react.cache.hits",
+      tags: ["component:#{metadata.component}"]
+    )
+  end
+
+  # ... other handlers
+end
+```
+
+### Structured Logging
+
+All telemetry events are automatically logged with structured formatting:
+
+- **Render Duration**: `[Phoenix.React] ✓ Rendered 'my_component' in 45ms (method: render_to_string, result: ok)`
+- **Runtime Startup**: `[Phoenix.React] Runtime Bun started on port 5225`
+- **Cache Events**: `[Phoenix.React] Cache hit for 'my_component' (method: render_to_string)`
+- **Build Events**: `[Phoenix.React] ✓ Build completed for Bun in 1234ms (result: ok)`
+
+### Health Checks
+
+Use telemetry for runtime health monitoring:
+
+```elixir
+case Phoenix.React.Telemetry.health_check("Bun", 5225) do
+  {:ok, metadata} ->
+    # Runtime is healthy
+    Logger.info("Runtime healthy: #{metadata.response_time_ms}ms")
+
+  {:error, reason} ->
+    # Runtime is unhealthy
+    Logger.error("Runtime unhealthy: #{inspect(reason)}")
+end
+```
+
+### Custom Measurements
+
+Wrap operations with telemetry measurements:
+
+```elixir
+Phoenix.React.Telemetry.measure("custom_operation", [:my_app, :custom], fn ->
+  # Your operation here
+  do_expensive_work()
+end)
+```
 
 ## File Structure
 

lib/phoenix/react/cache.ex

@@ -115,7 +115,15 @@ defmodule Phoenix.React.Cache do
   """
   @spec get(String.t(), map(), cache_method()) :: String.t() | nil
   def get(component, props, method) do
-    lookup(component, props, method)
+    case lookup(component, props, method) do
+      nil ->
+        Phoenix.React.Telemetry.record_cache_miss(component, method)
+        nil
+
+      result ->
+        Phoenix.React.Telemetry.record_cache_hit(component, method)
+        result
+    end
   end
 
   @doc """

lib/phoenix/react/runtime/deno.ex

@@ -113,7 +113,7 @@ defmodule Phoenix.React.Runtime.Deno do
       "Deno.Server started on port: #{inspect(port)} and OS pid: #{get_port_os_pid(port)}"
     )
 
-    Phoenix.React.Monitoring.record_runtime_startup("Deno", config()[:port])
+    Phoenix.React.Telemetry.record_runtime_startup("Deno", config()[:port])
 
     Phoenix.React.Server.set_runtime_process(self())
 
@@ -265,16 +265,16 @@ defmodule Phoenix.React.Runtime.Deno do
     server_port = config()[:port]
     timeout = state.render_timeout
 
-    Phoenix.React.Monitoring.measure(
+    Phoenix.React.Telemetry.measure(
       "render_#{method}_#{component}",
       [:phoenix, :react, :render],
       fn ->
         result = make_http_request(server_port, Atom.to_string(method), component, props, timeout)
 
-        # Record the result for monitoring
+        # Record the result for telemetry
         case result do
-          {:ok, _} -> Phoenix.React.Monitoring.record_render(component, method, 0, :ok)
-          {:error, _} -> Phoenix.React.Monitoring.record_render(component, method, 0, :error)
+          {:ok, _} -> Phoenix.React.Telemetry.record_render(component, method, 0, :ok)
+          {:error, _} -> Phoenix.React.Telemetry.record_render(component, method, 0, :error)
         end
 
         result
@@ -285,7 +285,7 @@ defmodule Phoenix.React.Runtime.Deno do
   @impl true
   def terminate(reason, state) do
     Logger.debug("Deno.Server terminating")
-    Phoenix.React.Monitoring.record_runtime_shutdown("Deno", reason)
+    Phoenix.React.Telemetry.record_runtime_shutdown("Deno", reason)
     cleanup_runtime_process(state.runtime_port, reason)
   end
 end

lib/phoenix/react/server.ex

@@ -164,21 +164,30 @@ defmodule Phoenix.React.Server do
         _from,
         %{runtime_process: runtime_process} = state
       ) do
+    start_time = System.monotonic_time(:millisecond)
+
     reply =
       case Cache.get(component, props, :render_to_readable_stream) do
         nil ->
           render_timeout = config()[:render_timeout]
 
-          case GenServer.call(
-                 runtime_process,
-                 {:render_to_readable_stream, component, props},
-                 render_timeout
-               ) do
+          result =
+            GenServer.call(
+              runtime_process,
+              {:render_to_readable_stream, component, props},
+              render_timeout
+            )
+
+          duration = System.monotonic_time(:millisecond) - start_time
+
+          case result do
             {:ok, html} = reply ->
               Cache.put(component, props, :render_to_readable_stream, html)
+              Phoenix.React.Telemetry.record_render(component, :render_to_readable_stream, duration, :ok)
               reply
 
-            reply ->
+            {:error, _} = reply ->
+              Phoenix.React.Telemetry.record_render(component, :render_to_readable_stream, duration, :error)
               reply
           end
 
@@ -194,21 +203,30 @@ defmodule Phoenix.React.Server do
         _from,
         %{runtime_process: runtime_process} = state
       ) do
+    start_time = System.monotonic_time(:millisecond)
+
     reply =
       case Cache.get(component, props, :render_to_string) do
         nil ->
           render_timeout = config()[:render_timeout]
 
-          case GenServer.call(
-                 runtime_process,
-                 {:render_to_string, component, props},
-                 render_timeout
-               ) do
+          result =
+            GenServer.call(
+              runtime_process,
+              {:render_to_string, component, props},
+              render_timeout
+            )
+
+          duration = System.monotonic_time(:millisecond) - start_time
+
+          case result do
             {:ok, html} = reply ->
               Cache.put(component, props, :render_to_string, html)
+              Phoenix.React.Telemetry.record_render(component, :render_to_string, duration, :ok)
               reply
 
-            reply ->
+            {:error, _} = reply ->
+              Phoenix.React.Telemetry.record_render(component, :render_to_string, duration, :error)
               reply
           end
 
@@ -224,21 +242,30 @@ defmodule Phoenix.React.Server do
         _from,
         %{runtime_process: runtime_process} = state
       ) do
+    start_time = System.monotonic_time(:millisecond)
+
     reply =
       case Cache.get(component, props, :render_to_static_markup) do
         nil ->
           render_timeout = config()[:render_timeout]
 
-          case GenServer.call(
-                 runtime_process,
-                 {:render_to_static_markup, component, props},
-                 render_timeout
-               ) do
+          result =
+            GenServer.call(
+              runtime_process,
+              {:render_to_static_markup, component, props},
+              render_timeout
+            )
+
+          duration = System.monotonic_time(:millisecond) - start_time
+
+          case result do
             {:ok, html} = reply ->
               Cache.put(component, props, :render_to_static_markup, html)
+              Phoenix.React.Telemetry.record_render(component, :render_to_static_markup, duration, :ok)
               reply
 
-            reply ->
+            {:error, _} = reply ->
+              Phoenix.React.Telemetry.record_render(component, :render_to_static_markup, duration, :error)
               reply
           end