diff --git a/docs/references/admin.rst b/docs/references/admin.rst index de1075594..0084c5f40 100644 --- a/docs/references/admin.rst +++ b/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 `_ header by setting :ref:`server-timing-enabled` on. -This header provides timing information about the different phases of the request-response cycle. - -.. code:: bash - - server-timing-header = "on" +You can enable the `Server-Timing `_ header by setting :ref:`server-timing-enabled` on. +This header communicates metrics of the different phases in the request-response cycle. .. 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: diff --git a/docs/references/api/url_grammar.rst b/docs/references/api/url_grammar.rst index c562f0a75..0fdb50f14 100644 --- a/docs/references/api/url_grammar.rst +++ b/docs/references/api/url_grammar.rst @@ -2,6 +2,8 @@ This page is a work in progress. +.. _url_grammar: + URL Grammar =========== diff --git a/docs/references/auth.rst b/docs/references/auth.rst index 379fc17f5..f2a3a69f1 100644 --- a/docs/references/auth.rst +++ b/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 ~~~~~~~~~~~~~~ diff --git a/postgrest.dict b/postgrest.dict index dc9281688..8bc7b5059 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -25,6 +25,7 @@ cors CORS cryptographically CSV +durations DDL DOM DevOps