Enable Vault Prometheus

doc/ARCHITECTURE.md

@@ -250,7 +250,9 @@ over the local interface, and hence doesn't work remotely.
 
 ## Prometheus
 
-pgagroal has support for [Prometheus](https://prometheus.io/) when the `metrics` port is specified.
+pgagroal has support for [Prometheus](https://prometheus.io/) when the `metrics` port is specified. 
+
+**Note:** It is crucial to carefully initialize Prometheus memory in any program files for example functions like `pgagroal_init_prometheus()` and `pgagroal_init_prometheus_cache()` should only be invoked if `metrics` is greater than 0.
 
 The module serves two endpoints
 

doc/VAULT.md

@@ -27,6 +27,10 @@ The available keys and their accepted values are reported in the table below.
 |----------|---------|------|----------|-------------|
 | host | | String | Yes | The bind address for pgagroal-vault |
 | port | | Int | Yes | The bind port for pgagroal-vault |
+| metrics | 0 | Int | No | The metrics port (disable = 0) |
+| metrics_cache_max_age | 0 | String | No | The number of seconds to keep in cache a Prometheus (metrics) response. If set to zero, the caching will be disabled. Can be a string with a suffix, like `2m` to indicate 2 minutes |
+| metrics_cache_max_size | 256k | String | No | The maximum amount of data to keep in cache when serving Prometheus responses. Changes require restart. This parameter determines the size of memory allocated for the cache even if `metrics_cache_max_age` or `metrics` are disabled. Its value, however, is taken into account only if `metrics_cache_max_age` is set to a non-zero value. Supports suffixes: 'B' (bytes), the default if omitted, 'K' or 'KB' (kilobytes), 'M' or 'MB' (megabytes), 'G' or 'GB' (gigabytes).|
+| authentication_timeout | 5 | Int | No | The number of seconds the process will wait for valid credentials |
 | log_type | console | String | No | The logging type (console, file, syslog) |
 | log_level | info | String | No | The logging level, any of the (case insensitive) strings `FATAL`, `ERROR`, `WARN`, `INFO` and `DEBUG` (that can be more specific as `DEBUG1` thru `DEBUG5`). Debug level greater than 5 will be set to `DEBUG5`. Not recognized values will make the log_level be `INFO` |
 | log_path | pgagroal.log | String | No | The log file location. Can be a strftime(3) compatible string. |
@@ -36,6 +40,7 @@ The available keys and their accepted values are reported in the table below.
 | log_mode | append | String | No | Append to or create the log file (append, create) |
 | log_connections | `off` | Bool | No | Log connects |
 | log_disconnections | `off` | Bool | No | Log disconnects |
+| hugepage | `try` | String | No | Huge page support (`off`, `try`, `on`) |
 
 ## [main]
 

doc/man/pgagroal_vault.conf.5.rst

@@ -33,6 +33,22 @@ host
 port
   The bind port for pgagroal-vault. Mandatory
 
+metrics
+  The metrics port. Default is 0 (disabled)
+
+metrics_cache_max_age
+  The number of seconds to keep in cache a Prometheus (metrics) response.
+  If set to zero, the caching will be disabled. Can be a string with a suffix, like ``2m`` to indicate 2 minutes.
+  Default is 0 (disabled)
+
+metrics_cache_max_size
+  The maximum amount of data to keep in cache when serving Prometheus responses. Changes require restart.
+  This parameter determines the size of memory allocated for the cache even if ``metrics_cache_max_age`` or
+  ``metrics`` are disabled. Its value, however, is taken into account only if ``metrics_cache_max_age`` is set
+  to a non-zero value. Supports suffixes: ``B`` (bytes), the default if omitted, ``K`` or ``KB`` (kilobytes),
+  ``M`` or ``MB`` (megabytes), ``G`` or ``GB`` (gigabytes).
+  Default is 256k
+
 log_type
   The logging type (console, file, syslog). Default is console
 
@@ -67,6 +83,12 @@ log_connections
 log_disconnections
   Log disconnects. Default is off
 
+authentication_timeout
+  The number of seconds the process will wait for valid credentials. Default is 5
+
+hugepage
+  Huge page support. Default is try
+
 The options for the main section are
 
 host

doc/manual/dev-02-architecture.md

@@ -254,6 +254,8 @@ over the local interface, and hence doesn't work remotely.
 
 pgagroal has support for [Prometheus](https://prometheus.io/) when the `metrics` port is specified.
 
+**Note:** It is crucial to carefully initialize Prometheus memory in any program files for example functions like `pgagroal_init_prometheus()` and `pgagroal_init_prometheus_cache()` should only be invoked if `metrics` is greater than 0.
+
 The module serves two endpoints
 
 * `/` - Overview of the functionality (`text/html`)

doc/manual/user-11-prometheus.md

@@ -233,3 +233,29 @@ Number of sockets the client used
 ## pgagroal_self_sockets
 
 Number of sockets used by pgagroal itself
+
+[**pgagroal-vault**][pgagroal-vault] has the following [Prometheus][prometheus] metrics.
+
+## pgagroal_vault_logging_info
+
+The number of INFO statements
+
+## pgagroal_vault_logging_warn
+
+The number of WARN statements
+
+## pgagroal_vault_logging_error
+
+The number of ERROR statements
+
+## pgagroal_vault_logging_fatal
+
+The number of FATAL statements
+
+## pgagroal_vault_client_sockets
+
+Number of sockets the client used
+
+## pgagroal_vault_self_sockets
+
+Number of sockets used by pgagroal-vault itself

doc/manual/user-12-vault.md

@@ -29,6 +29,9 @@ The available keys and their accepted values are reported in the table below.
 |----------|---------|------|----------|-------------|
 | host | | String | Yes | The bind address for pgagroal-vault |
 | port | | Int | Yes | The bind port for pgagroal-vault |
+| metrics | 0 | Int | No | The metrics port (disable = 0) |
+| metrics_cache_max_age | 0 | String | No | The number of seconds to keep in cache a Prometheus (metrics) response. If set to zero, the caching will be disabled. Can be a string with a suffix, like `2m` to indicate 2 minutes |
+| metrics_cache_max_size | 256k | String | No | The maximum amount of data to keep in cache when serving Prometheus responses. Changes require restart. This parameter determines the size of memory allocated for the cache even if `metrics_cache_max_age` or `metrics` are disabled. Its value, however, is taken into account only if `metrics_cache_max_age` is set to a non-zero value. Supports suffixes: 'B' (bytes), the default if omitted, 'K' or 'KB' (kilobytes), 'M' or 'MB' (megabytes), 'G' or 'GB' (gigabytes).|
 | log_type | console | String | No | The logging type (console, file, syslog) |
 | log_level | info | String | No | The logging level, any of the (case insensitive) strings `FATAL`, `ERROR`, `WARN`, `INFO` and `DEBUG` (that can be more specific as `DEBUG1` thru `DEBUG5`). Debug level greater than 5 will be set to `DEBUG5`. Not recognized values will make the log_level be `INFO` |
 | log_path | pgagroal.log | String | No | The log file location. Can be a strftime(3) compatible string. |
@@ -38,6 +41,8 @@ The available keys and their accepted values are reported in the table below.
 | log_mode | append | String | No | Append to or create the log file (append, create) |
 | log_connections | `off` | Bool | No | Log connects |
 | log_disconnections | `off` | Bool | No | Log disconnects |
+| authentication_timeout | 5 | Int | No | The number of seconds the process will wait for valid credentials |
+| hugepage | `try` | String | No | Huge page support (`off`, `try`, `on`) |
 
 ## [main]
 

doc/tutorial/04_prometheus.md

@@ -59,3 +59,44 @@ It is also possible to get an explaination of what is the meaning of each metric
 ```
 http://localhost:2346/
 ```
+
+## Prometheus metrics for pgagroal-vault
+This tutorial will show you how to do basic  [Prometheus](https://prometheus.io/){:target="_blank"} setup  for [**pgagroal-vault**](https://github.com/agroal/pgagroal).
+
+**pgagroal-vault** is able to provide a set of metrics about what it is happening within the vault, so that a Prometheus instance can collect them and help you monitor the vault activities.
+
+### Change the pgagroal-vault configuration
+
+In order to enable to export of the metrics, you need to add the `metrics` option in the main `pgagroal_vault.conf` configuration. The value of this setting is the TCP/IP port number that Prometheus will use to grab the exported metrics.
+
+Add a line like the following to `/etc/pgagroal/pgagroal_vault.conf` by editing such file with your editor of choice:
+
+```
+metrics = 2501
+```
+
+Place it within the `[pgagroal-vault]` section, like
+
+```
+[pgagroal-vault]
+...
+metrics = 2501
+```
+
+This will bind the TCP/IP port number `2501` to the metrics export.
+
+See [the pgagroal-vault configuration settings](https://github.com/agroal/pgagroal/blob/master/doc/VAULT.md#pgagroal-vault) with particular regard to `metrics`, `metrics_cache_max_age` and `metrics_cache_max_size` for more details.
+
+### Get Prometheus metrics
+
+Once **pgagroal-vault** is running you can access the metrics with a browser at the pgagroal-vault address, specifying the `metrics` port number and routing to the `/metrics` page. For example, point your web browser at:
+
+```
+http://localhost:2501/metrics
+```
+
+It is also possible to get an explaination of what is the meaning of each metric by pointing your web browser at:
+
+```
+http://localhost:2501/
+```

src/include/pgagroal.h

@@ -371,10 +371,28 @@ struct prometheus_cache
 } __attribute__ ((aligned (64)));
 
 /** @struct
- * Defines the Prometheus metrics
+ * Defines the common Prometheus metrics
  */
 struct prometheus
 {
+   // logging
+   atomic_ulong logging_info;          /**< Logging: INFO */
+   atomic_ulong logging_warn;          /**< Logging: WARN */
+   atomic_ulong logging_error;         /**< Logging: ERROR */
+   atomic_ulong logging_fatal;         /**< Logging: FATAL */
+
+   // internal connections
+   atomic_int client_sockets;          /**< The number of sockets the client used */
+   atomic_int self_sockets;            /**< The number of sockets used by pgagroal itself */
+
+} __attribute__ ((aligned (64)));
+
+/** @struct
+ * Defines the Main Prometheus metrics
+ */
+struct main_prometheus
+{
+   struct prometheus prometheus_base;            /**< Common base class */
    atomic_ulong session_time[HISTOGRAM_BUCKETS]; /**< The histogram buckets */
    atomic_ulong session_time_sum;                /**< Total session time */
 
@@ -390,11 +408,6 @@ struct prometheus
    atomic_ulong connection_flush;              /**< The number of flush calls */
    atomic_ulong connection_success;            /**< The number of success calls */
 
-   atomic_ulong logging_info;  /**< Logging: INFO */
-   atomic_ulong logging_warn;  /**< Logging: WARN */
-   atomic_ulong logging_error; /**< Logging: ERROR */
-   atomic_ulong logging_fatal; /**< Logging: FATAL */
-
    /**< The number of connection awaiting due to `blocking_timeout` */
    atomic_ulong connections_awaiting[NUMBER_OF_LIMITS];
    atomic_ulong connections_awaiting_total;
@@ -413,15 +426,20 @@ struct prometheus
    atomic_ullong network_sent;          /**< The bytes sent by clients */
    atomic_ullong network_received;      /**< The bytes received from servers */
 
-   atomic_int client_sockets;          /**< The number of sockets the client used */
-   atomic_int self_sockets;            /**< The number of sockets used by pgagroal itself */
-
    atomic_ulong server_error[NUMBER_OF_SERVERS]; /**< The number of errors for a server */
    atomic_ulong failed_servers;                  /**< The number of failed servers */
    struct prometheus_connection prometheus_connections[];  /**< The number of prometheus connections (FMA) */
 
 } __attribute__ ((aligned (64)));
 
+/** @struct
+ * Defines the Vault Prometheus metrics
+ */
+struct vault_prometheus
+{
+   struct prometheus prometheus_base;
+} __attribute__ ((aligned (64)));
+
 /** @struct
  * Defines the common configurations between pgagroal and vault
  */
@@ -430,6 +448,7 @@ struct configuration
    char configuration_path[MAX_PATH]; /**< The configuration path */
    char host[MISC_LENGTH];            /**< The host */
    int port;                          /**< The port */
+   int authentication_timeout;        /**< The authentication timeout in seconds */
 
    // Logging
    int log_type;                       /**< The logging type */
@@ -443,6 +462,12 @@ struct configuration
    char log_line_prefix[MISC_LENGTH];  /**< The logging prefix */
    atomic_schar log_lock;              /**< The logging lock */
    char default_log_path[MISC_LENGTH]; /**< The default logging path */
+
+   // Prometheus
+   unsigned char hugepage;              /**< Huge page support */
+   int metrics;                         /**< The metrics port */
+   unsigned int metrics_cache_max_age;  /**< Number of seconds to cache the Prometheus response */
+   unsigned int metrics_cache_max_size; /**< Number of bytes max to cache the Prometheus response */
 };
 
 /** @struct
@@ -469,9 +494,6 @@ struct main_configuration
    char admins_path[MAX_PATH];        /**< The admins path */
    char superuser_path[MAX_PATH];     /**< The superuser path */
 
-   int metrics;            /**< The metrics port */
-   unsigned int metrics_cache_max_age;      /**< Number of seconds to cache the Prometheus response */
-   unsigned int metrics_cache_max_size;     /**< Number of bytes max to cache the Prometheus response */
    int management;         /**< The management port */
    bool gracefully;        /**< Is pgagroal in gracefully mode */
 
@@ -503,7 +525,6 @@ struct main_configuration
    int validation;               /**< Validation mode */
    int background_interval;      /**< Background validation timer in seconds */
    int max_retries;              /**< The maximum number of retries */
-   int authentication_timeout;   /**< The authentication timeout in seconds */
    int disconnect_client;        /**< Disconnect client if idle for more than the specified seconds */
    bool disconnect_client_force; /**< Force a disconnect client if active for more than the specified seconds */
    char pidfile[MAX_PATH];       /**< File containing the PID */
@@ -514,7 +535,6 @@ struct main_configuration
    bool nodelay;            /**< Use NODELAY */
    bool non_blocking;       /**< Use non blocking */
    int backlog;             /**< The backlog for listen */
-   unsigned char hugepage;  /**< Huge page support */
    bool tracker;            /**< Tracker support */
    bool track_prepared_statements; /**< Track prepared statements (transaction pooling) */
 

src/include/prometheus.h

@@ -64,12 +64,25 @@ extern "C" {
 void
 pgagroal_prometheus(int fd);
 
+/**
+ * Create a prometheus instance for vault
+ * @param fd The client descriptor
+ */
+void
+pgagroal_vault_prometheus(int fd);
+
 /**
  * Initialize prometheus shmem
  */
 int
 pgagroal_init_prometheus(size_t* p_size, void** p_shmem);
 
+/**
+ * Initialize prometheus shmem for vault
+ */
+int
+pgagroal_vault_init_prometheus(size_t* p_size, void** p_shmem);
+
 /**
  * Add session time information
  * @param time The time