Comprehensive telemetry and metrics collection for Phoenix.ReactServer runtimes.
This module provides production-ready telemetry capabilities including performance metrics, health checks, runtime status monitoring, and comprehensive error tracking with structured logging.
Features
- Performance Metrics: Track render times, success rates, and throughput
- Health Checks: Monitor runtime process health and responsiveness
- Error Tracking: Detailed error logging and categorization
- Telemetry Integration:
:telemetryevents for observability - Runtime Status: Monitor JavaScript runtime process states
- Cache Metrics: Track cache hit/miss ratios and performance
- Structured Logging: Enhanced log formatting with render duration
Telemetry Events
The following telemetry events are emitted:
[:phoenix, :react, :render]- Fired after each component render- Measurements:
%{duration: duration_ms} - Metadata:
%{component: component, method: method, result: result, timestamp: timestamp}
- Measurements:
[:phoenix, :react, :runtime_startup]- Fired when runtime starts- Metadata:
%{runtime: runtime_name, port: port, timestamp: timestamp}
- Metadata:
[:phoenix, :react, :runtime_shutdown]- Fired when runtime stops- Metadata:
%{runtime: runtime_name, reason: reason, timestamp: timestamp}
- Metadata:
[:phoenix, :react, :cache, :hit]- Fired on cache hits- Metadata:
%{component: component, method: method, timestamp: timestamp}
- Metadata:
[:phoenix, :react, :cache, :miss]- Fired on cache misses- Metadata:
%{component: component, method: method, timestamp: timestamp}
- Metadata:
[:phoenix, :react, :file_change]- Fired on component file changes- Metadata:
%{path: path, action: action, timestamp: timestamp}
- Metadata:
[:phoenix, :react, :build]- Fired after build operations- Measurements:
%{duration: duration_ms} - Metadata:
%{runtime: runtime_name, result: result, timestamp: timestamp}
- Measurements:
Usage
Attach telemetry handlers to monitor performance:
:telemetry.attach_many(
"phoenix-react-telemetry",
[
[:phoenix, :react, :render],
[:phoenix, :react, :cache, :hit],
[:phoenix, :react, :cache, :miss]
],
&MyApp.Telemetry.handle_event/4,
%{}
)Health Checks
Use for health monitoring endpoints and alerts:
# Check runtime health
case Phoenix.ReactServer.Telemetry.health_check("Bun", 5225) do
{:ok, metadata} -> :healthy
{:error, reason} -> :unhealthy
endPerformance Monitoring
Track component performance over time:
- Average render times per component
- Error rates and failure patterns
- Cache efficiency metrics
- Runtime resource usage
Logging
The module provides structured logging for all operations:
- Render duration:
[Phoenix.ReactServer] Rendered <component> in <duration>ms (method: <method>, result: <result>) - Runtime events:
[Phoenix.ReactServer] Runtime <runtime> started on port <port> - Cache events:
[Phoenix.ReactServer] Cache <hit/miss> for <component>
Summary
Functions
Gets runtime statistics.
Performs a health check on the runtime.
Measures execution time of a function and records it with telemetry.
Records a build event with duration.
Records a cache hit event.
Records a cache miss event.
Records a file change event.
Records a render request with timing information and logs the render duration.
Records a runtime shutdown event.
Records a runtime startup event.
Functions
Gets runtime statistics.
@spec health_check(String.t(), non_neg_integer()) :: {:ok, map()} | {:error, term()}
Performs a health check on the runtime.
Measures execution time of a function and records it with telemetry.
This function wraps the execution of a given function, measures its duration, and emits telemetry events with the timing information.
Parameters
operation_name- Descriptive name for the operation being measuredtelemetry_event- Telemetry event name (list of atoms)fun- Zero-arity function to execute and measure
Returns
The result of executing fun
Examples
iex> Phoenix.ReactServer.Telemetry.measure("render_chart", [:phoenix, :react, :render], fn ->
...> :timer.sleep(10)
...> {:ok, "<div>Chart</div>"}
...> end)
{:ok, "<div>Chart</div>"}@spec record_build(String.t(), non_neg_integer(), :ok | :error) :: :ok
Records a build event with duration.
Parameters
runtime_name- Name of the runtime (e.g., "Bun", "Deno")duration_ms- Build duration in millisecondsresult- Build result (:okor:error)
Records a cache hit event.
Parameters
component- Component namemethod- Rendering method
Records a cache miss event.
Parameters
component- Component namemethod- Rendering method
Records a file change event.
@spec record_render(String.t(), atom(), non_neg_integer(), :ok | :error) :: :ok
Records a render request with timing information and logs the render duration.
Parameters
component- Component namemethod- Rendering method (:render_to_string,:render_to_static_markup, or:render_to_readable_stream)duration_ms- Render duration in millisecondsresult- Result status (:okor:error)
Examples
iex> Phoenix.ReactServer.Telemetry.record_render("chart", :render_to_string, 45, :ok)
:okRecords a runtime shutdown event.
Parameters
runtime_name- Name of the runtime (e.g., "Bun", "Deno")reason- Shutdown reason
@spec record_runtime_startup(String.t(), non_neg_integer()) :: :ok
Records a runtime startup event.
Parameters
runtime_name- Name of the runtime (e.g., "Bun", "Deno")port- Port number the runtime is listening on