Centralize metric and logging docs (phoenixframework#3666)

lib/phoenix/endpoint.ex

@@ -88,7 +88,7 @@ defmodule Phoenix.Endpoint do
       with a 500 error during a HTML request, `render("500.html", assigns)`
       will be called in the view given to `:render_errors`. Defaults to:
 
-          [view: MyApp.ErrorView, accepts: ~w(html), layout: false]
+          [view: MyApp.ErrorView, accepts: ~w(html), layout: false, log: :debug]
 
       The default format is used when none is set in the connection
 
@@ -215,52 +215,14 @@ defmodule Phoenix.Endpoint do
 
     * for handling paths and URLs: `c:struct_url/0`, `c:url/0`, `c:path/1`,
       `c:static_url/0`,`c:static_path/1`, and `c:static_integrity/1`
+
     * for broadcasting to channels: `c:broadcast/3`, `c:broadcast!/3`,
       `c:broadcast_from/4`, `c:broadcast_from!/4`, `c:local_broadcast/3`,
       and `c:local_broadcast_from/4`
-    * for configuration: `c:start_link/0`, `c:config/2`, and `c:config_change/2`
-    * as required by the `Plug` behaviour: `c:Plug.init/1` and `c:Plug.call/2`
-
-  ## Instrumentation
-
-  Phoenix uses the `:telemetry` library for instrumentation. The following events
-  are published by Phoenix with the following measurements and metadata:
-
-    * `[:phoenix, :endpoint, :start]` - dispatched by `Plug.Telemetry` in your
-      endpoint at the beginning of every request.
-      * Measurement: `%{time: System.monotonic_time}`
-      * Metadata: `%{conn: Plug.Conn.t}`
-
-    * `[:phoenix, :endpoint, :stop]` - dispatched by `Plug.Telemetry` in your
-      endpoint whenever the response is sent
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{conn: Plug.Conn.t}`
 
-    * `[:phoenix, :router_dispatch, :start]` - dispatched by `Phoenix.Router`
-      before dispatching to a matched route
-      * Measurement: `%{time: System.monotonic_time}`
-      * Metadata: `%{conn: Plug.Conn.t, route: binary, plug: module, plug_opts: term, path_params: map, pipe_through: [atom]}`
-
-    * `[:phoenix, :router_dispatch, :stop]` - dispatched by `Phoenix.Router`
-      after successfully dispatching to a matched route
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{conn: Plug.Conn.t, route: binary, plug: module, plug_opts: term, path_params: map, pipe_through: [atom]}`
-
-    * `[:phoenix, :error_rendered]` - dispatched at the end of an error view being rendered
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{status: Plug.Conn.status, kind: Exception.kind, reason: term, stacktrace: Exception.stacktrace}`
-
-    * `[:phoenix, :socket_connected]` - dispatched at the end of a socket connection
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{endpoint: atom, transport: atom, params: term, connect_info: map, vsn: binary, user_socket: atom, result: :ok | :error, serializer: atom}`
-
-    * `[:phoenix, :channel_joined]` - dispatched at the end of a channel join
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{params: term, socket: Phoenix.Socket.t}`
+    * for configuration: `c:start_link/0`, `c:config/2`, and `c:config_change/2`
 
-    * `[:phoenix, :channel_handled_in]` - dispatched at the end of a channel handle in
-      * Measurement: `%{duration: native_time}`
-      * Metadata: `%{event: binary, params: term, socket: Phoenix.Socket.t}`
+    * as required by the `Plug` behaviour: `c:Plug.init/1` and `c:Plug.call/2`
 
   """
 

lib/phoenix/endpoint/render_errors.ex

@@ -9,6 +9,8 @@ defmodule Phoenix.Endpoint.RenderErrors do
   #
   #   * `:view` - the name of the view we render templates against
   #   * `:format` - the format to use when none is available from the request
+  #   * `:accepts` - list of accepted formats errors will be rendered for
+  #   * `:log` - the `t:Logger.level/0` or `false` to disable logging rendered errors
   #
   @moduledoc false
 

lib/phoenix/logger.ex

@@ -1,6 +1,58 @@
 defmodule Phoenix.Logger do
   @moduledoc """
   Instrumenter to handle logging of various instrumentation events.
+  
+  ## Instrumentation
+
+  Phoenix uses the `:telemetry` library for instrumentation. The following events
+  are published by Phoenix with the following measurements and metadata:
+
+    * `[:phoenix, :endpoint, :start]` - dispatched by `Plug.Telemetry` in your
+      endpoint at the beginning of every request.
+      * Measurement: `%{time: System.monotonic_time}`
+      * Metadata: `%{conn: Plug.Conn.t, options: Keyword.t}`
+      * Options: `%{log: Logger.level | false}`
+      * Disable logging: In your endpoint `plug Plug.Telemetry, ..., options: [log: false]`
+
+    * `[:phoenix, :endpoint, :stop]` - dispatched by `Plug.Telemetry` in your
+      endpoint whenever the response is sent
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{conn: Plug.Conn.t, options: Keyword.t}`
+      * Options: `%{log: Logger.level | false}`
+      * Disable logging: In your endpoint `plug Plug.Telemetry, ..., options: [log: false]`
+
+    * `[:phoenix, :router_dispatch, :start]` - dispatched by `Phoenix.Router`
+      before dispatching to a matched route
+      * Measurement: `%{time: System.monotonic_time}`
+      * Metadata: `%{conn: Plug.Conn.t, route: binary, plug: module, plug_opts: term, path_params: map, pipe_through: [atom], log: Logger.level | false}`
+      * Disable logging: Pass `log: false` to the router macro, for example: `get("/page", PageController, :index, log: false)`
+
+    * `[:phoenix, :router_dispatch, :stop]` - dispatched by `Phoenix.Router`
+      after successfully dispatching to a matched route
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{conn: Plug.Conn.t, route: binary, plug: module, plug_opts: term, path_params: map, pipe_through: [atom], log: Logger.level | false}`
+      * Disable logging: This event is not logged
+
+    * `[:phoenix, :error_rendered]` - dispatched at the end of an error view being rendered
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{status: Plug.Conn.status, kind: Exception.kind, reason: term, stacktrace: Exception.stacktrace}`
+      * Disable logging: Set `render_errors: [log: false]` on your endpoint configuration
+
+    * `[:phoenix, :socket_connected]` - dispatched by `Phoenix.Socket`, at the end of a socket connection
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{endpoint: atom, transport: atom, params: term, connect_info: map, vsn: binary, user_socket: atom, result: :ok | :error, serializer: atom, log: Logger.level | false}`
+      * Disable logging: `use Phoenix.Socket, log: false`
+
+    * `[:phoenix, :channel_joined]` - dispatched at the end of a channel join
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{params: term, socket: Phoenix.Socket.t}`
+      * Disable logging: This event cannot be disabled
+  
+    * `[:phoenix, :channel_handled_in]` - dispatched at the end of a channel handle in
+      * Measurement: `%{duration: native_time}`
+      * Metadata: `%{event: binary, params: term, socket: Phoenix.Socket.t}`
+      * Disable logging: This event cannot be disabled
+
 
   ## Parameter filtering
 
@@ -152,7 +204,7 @@ defmodule Phoenix.Logger do
   defp error_banner(:error, %type{}), do: inspect(type)
   defp error_banner(_kind, reason), do: inspect(reason)
 
-  ## Event: [:phoenix, :routed, *]
+  ## Event: [:phoenix, :router_dispatch, :start]
 
   defp phoenix_router_dispatch_start(_, _, %{log: false}, _), do: :ok