From 3eff4670f07bec5da0b2c47ea458b816d6e49e72 Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Tue, 23 Apr 2024 18:44:35 -0500
Subject: [PATCH] docs: metrics for schema cache and connection pool

---
 docs/references/admin_server.rst  | 13 +++++
 docs/references/observability.rst | 97 ++++++++++++++++++++++++++++++-
 2 files changed, 107 insertions(+), 3 deletions(-)

diff --git a/docs/references/admin_server.rst b/docs/references/admin_server.rst
index 425d31072..df9161f46 100644
--- a/docs/references/admin_server.rst
+++ b/docs/references/admin_server.rst
@@ -39,3 +39,16 @@ Ready
 -----
 
 In addition, the ``ready`` endpoint checks the state of the :ref:`connection_pool` and the :ref:`schema_cache`. A request will return ``200 OK`` if both are good or ``503`` if not.
+
+.. code-block:: bash
+
+  curl -I "http://localhost:3001/ready"
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+
+Metrics
+=======
+
+Provides :ref:`metrics`.
diff --git a/docs/references/observability.rst b/docs/references/observability.rst
index a89adf23a..efa389b78 100644
--- a/docs/references/observability.rst
+++ b/docs/references/observability.rst
@@ -3,10 +3,15 @@
 Observability
 #############
 
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: none
+
 .. _pgrst_logging:
 
-Logging
--------
+Logs
+====
 
 PostgREST logs basic request information to ``stdout``, including the authenticated user if available, the requesting IP address and user agent, the URL requested, and HTTP response status.
 
@@ -40,7 +45,7 @@ For diagnostic information about the server itself, PostgREST logs to ``stderr``
 Currently PostgREST doesn't log the SQL commands executed against the underlying database.
 
 Database Logs
-~~~~~~~~~~~~~
+-------------
 
 To find the SQL operations, you can watch the database logs. By default PostgreSQL does not keep these logs, so you'll need to make the configuration changes below.
 
@@ -81,6 +86,92 @@ Restart the database and watch the log file in real-time to understand how HTTP
     docker run -v "$(pwd)/init.sh":"/docker-entrypoint-initdb.d/init.sh" -d postgres
     docker logs -f <container-id>
 
+.. _metrics:
+
+Metrics
+=======
+
+The ``metrics`` endpoint on the :ref:`admin_server` endpoint provides metrics in `Prometheus text format <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`_.
+
+.. code-block:: bash
+
+  curl "http://localhost:3001/metrics"
+
+  # HELP pgrst_schema_cache_query_time_seconds The query time in seconds of the last schema cache load
+  # TYPE pgrst_schema_cache_query_time_seconds gauge
+  pgrst_schema_cache_query_time_seconds 1.5937927e-2
+  # HELP pgrst_schema_cache_loads_total The total number of times the schema cache was loaded
+  # TYPE pgrst_schema_cache_loads_total counter
+  pgrst_schema_cache_loads_total 1.0
+  ...
+
+Schema Cache Metrics
+--------------------
+
+Metrics related to the :ref:`schema_cache`.
+
+pgrst_schema_cache_query_time_seconds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Gauge
+======== =======
+
+The query time in seconds of the last schema cache load.
+
+pgrst_schema_cache_loads_total
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Counter
+======== =======
+
+The total number of times the schema cache was loaded.
+
+Connection Pool Metrics
+-----------------------
+
+Metrics related to the :ref:`connection_pool`.
+
+pgrst_db_pool_timeouts_total
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Counter
+======== =======
+
+The total number of pool connection timeouts.
+
+pgrst_db_pool_available
+~~~~~~~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Gauge
+======== =======
+
+Available connections in the pool.
+
+pgrst_db_pool_waiting
+~~~~~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Gauge
+======== =======
+
+Requests waiting to acquire a pool connection
+
+pgrst_db_pool_max
+~~~~~~~~~~~~~~~~~
+
+======== =======
+**Type** Gauge
+======== =======
+
+Max pool connections.
+
+Traces
+======
+
 Server Version
 --------------