fix server-timing header section

Also link it to jwt caching

docs/references/admin.rst

@@ -145,15 +145,11 @@ You can enable tracing HTTP requests by setting :ref:`server-trace-header`. Spec
 
 .. _server-timing_header:
 
-`Server-Timing` Header
+Server-Timing Header
-----------------------
+--------------------
 
-You can enable the `Server-Timing <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing>`_ header by setting :ref:`server-timing-enabled` on. 
+You can enable the `Server-Timing <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing>`_ header by setting :ref:`server-timing-enabled` on.
-This header provides timing information about the different phases of the request-response cycle.
+This header communicates metrics of the different phases in the request-response cycle.
-
-.. code:: bash
-
-  server-timing-header = "on"
 
 .. tabs::
 
@@ -163,12 +159,24 @@ This header provides timing information about the different phases of the reques
 
   .. code-tab:: bash Curl
 
-    curl "http://localhost:3000/users"
+    curl "http://localhost:3000/users" -i
-  
+
 .. code::
 
   HTTP/1.1 200 OK
-  Server-Timing: jwt;dur=16.0, render;dur=8.8, plan;dur=16956.1, query;dur=763.5
+
+  Server-Timing: jwt;dur=14.9, parse;dur=71.1, plan;dur=109.0, transaction;dur=353.2, response;dur=4.4
+
+- All the durations (``dur``) are in milliseconds.
+- The ``jwt`` stage is when :ref:`jwt_impersonation` is done. This duration can be lowered with :ref:`jwt_caching`.
+- On the ``parse`` stage, the :ref:`url_grammar` is parsed.
+- On the ``plan`` stage, the :ref:`schema_cache` is used to generate the :ref:`main_query` of the transaction.
+- The ``transaction`` stage corresponds to the database transaction. See :ref:`transactions`.
+- The ``response`` stage is where the response status and headers are computed.
+
+.. note::
+
+  We're working on lowering the duration of the ``parse`` and ``plan`` stages on https://github.com/PostgREST/postgrest/issues/2816.
 
 .. _explain_plan:
 

docs/references/api/url_grammar.rst

@@ -2,6 +2,8 @@
 
   This page is a work in progress.
 
+.. _url_grammar:
+
 URL Grammar
 ===========
 

docs/references/auth.rst

@@ -109,6 +109,10 @@ PostgREST validates ``JWTs`` on every request. We can cache ``JWTs`` to avoid th
 
 To enable JWT caching, the config :code:`jwt-cache-max-lifetime` is to be set. It is the maximum number of seconds for which the cache stores the JWT validation results. The cache uses the :code:`exp` claim to set the cache entry lifetime. If the JWT does not have an :code:`exp` claim, it uses the config value. See :ref:`jwt-cache-max-lifetime` for more details.
 
+.. note::
+
+  You can use the :ref:`server-timing_header` to see the effect of JWT caching.
+
 Symmetric Keys
 ~~~~~~~~~~~~~~
 

postgrest.dict

@@ -25,6 +25,7 @@ cors
 CORS
 cryptographically
 CSV
+durations
 DDL
 DOM
 DevOps