From 49fd99c1c0d25296282537454ece6642a6d9be85 Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Tue, 16 Jun 2026 07:53:17 -0700 Subject: [PATCH] feat: catch up on docs --- docs/configuration/pgdog.toml/otel.md | 3 + .../control_plane/installation.md | 46 ++++++++++++++ docs/features/metrics.md | 60 +++++++++++++++---- 3 files changed, 99 insertions(+), 10 deletions(-) diff --git a/docs/configuration/pgdog.toml/otel.md b/docs/configuration/pgdog.toml/otel.md index c5eaae5b..39eae335 100644 --- a/docs/configuration/pgdog.toml/otel.md +++ b/docs/configuration/pgdog.toml/otel.md @@ -30,6 +30,9 @@ the authentication header. To obtain a Datadog API key, go to your Organization settings / API keys. +!!! note "Kubernetes" + If deploying with Kubernetes, you can source the API key from a `Secret` instead of setting it directly. See [Using a Secret](../../features/metrics.md#using-a-secret). + ### `namespace` By default, all metrics will be sent under the `pgdog` namespace, e.g.: `pgdog.sv_idle`. diff --git a/docs/enterprise_edition/control_plane/installation.md b/docs/enterprise_edition/control_plane/installation.md index 77144192..5c31d9ed 100644 --- a/docs/enterprise_edition/control_plane/installation.md +++ b/docs/enterprise_edition/control_plane/installation.md @@ -131,6 +131,52 @@ The client secret can be alternatively set as an environment variable: | GitHub| `GITHUB_CLIENT_SECRET` | | Google | `GOOGLE_CLIENT_SECRET` | +### Using a Secret + +To keep the client OAuth2 secret out of the `ConfigMap`, you can reference an existing Kubernetes `Secret` instead. The chart will mount it into the environment automatically. + +#### Create Secret + +The `Secret` resource should be in the same namespace as the chart release: + +=== "GitHub" + ```bash title="kubectl" + kubectl create secret generic pgdog-oauth-secrets \ + --namespace pgdog \ + --from-literal=github-client-secret=shhh + ``` +=== "Google" + ```bash title="kubectl" + kubectl create secret generic pgdog-oauth-secrets \ + --namespace pgdog \ + --from-literal=google-client-secret=shhh + ``` + +The secret can then be referenced in `values.yaml`: + +=== "GitHub" + ```yaml title="values.yaml" + github: + client_id: Iv1.0123456789abcdef + allowed_orgs: + - acme-corp + secret: + name: pgdog-oauth-secrets + clientSecretKey: github-client-secret + ``` +=== "Google" + ```yaml title="values.yaml" + google: + client_id: 0123456789-abc.apps.googleusercontent.com + allowed_domains: + - acme.com + secret: + name: pgdog-oauth-secrets + clientSecretKey: google-client-secret + ``` + +The same method can be used to store the `client_id` (using `clientIdKey` as key). + ### Access control `allowed_orgs` (GitHub) and `allowed_domains` (Google) restrict logins to members of those organizations or email domains. If left empty, anyone who can authenticate with the provider is allowed in. diff --git a/docs/features/metrics.md b/docs/features/metrics.md index fbda6c94..16b200bc 100644 --- a/docs/features/metrics.md +++ b/docs/features/metrics.md @@ -41,10 +41,15 @@ and available from an HTTP endpoint. The endpoint is disabled by default. You can enable it by configuring which port it should run on: -```toml -[general] -openmetrics_port = 9090 -``` +=== "pgdog.toml" + ```toml + [general] + openmetrics_port = 9090 + ``` +=== "Helm chart" + ```yaml + openMetricsPort: 9090 + ``` This setting can only be configured on startup. Once configured, the endpoint will be available on `http://0.0.0.0:9090` and can be queried with any HTTP client, for example: @@ -56,14 +61,20 @@ curl http://127.0.0.1:9090/metrics To avoid name conflicts between PgDog's metrics and your own, you can namespace these metrics with a configurable prefix: -```toml -[general] -openmetrics_namespace = "pgdog_" -``` +=== "pgdog.toml" + ```toml + [general] + openmetrics_namespace = "pgdog_" + ``` +=== "Helm chart" + ```yaml + openMetricsNamespace: pgdog_ + ``` !!! note "Prefix format" - Some OpenMetrics implementations don't support special characters in the metric name (e.g., periods, commas, etc.). In that case, - you can use an underscore (`_`) instead. + Some OpenMetrics implementations don't support special characters in the metric name (e.g., periods, commas, etc.) while others prefer a period (`.`, e.g. Datadog). + + To make these metrics display correctly when collected with the Datadog agent, set `openmetrics_namespace` to `"pgdog."` instead. ## OTEL @@ -88,6 +99,28 @@ See [`[otel]` configuration](../configuration/pgdog.toml/otel.md) for the full l endpoint: "https://otlp.us5.datadoghq.com/v1/metrics" ``` +#### Using a Secret + +If deploying with Kubernetes, you can keep the Datadog API key out of the config by referencing an existing Kubernetes `Secret` instead. The chart injects it as the `DD_API_KEY` environment variable. + +The `Secret` resource should be in the same namespace as the chart release: + +```bash title="kubectl" +kubectl create secret generic my-datadog \ + --namespace pgdog \ + --from-literal=dd-api-key= +``` + +The secret can then be referenced in `values.yaml`: + +```yaml title="values.yaml" +otel: + endpoint: "https://otlp.us5.datadoghq.com/v1/metrics" + datadogApiKeySecret: + name: my-datadog + key: dd-api-key +``` + #### Namespace All metrics by default will be pushed to the `pgdog` namespace. For example, `sv_active` will be reported as `pgdog.sv_active`. The namespace is configurable, for example: @@ -167,3 +200,10 @@ The following metrics are exported via the OpenMetrics endpoint: | `avg_cleaned` | Average number of times server connections were cleaned from client parameters. | `gauge` | | `query_cache_limit` | Maximum number of queries that can be stored in the cache. | `gauge` | | `query_cache_parse_time` | Time spent parsing queries due to cache misses. | `counter` | +| `query_cache_fingerprints` | Number of query fingerprints calculated. | `counter` | +| `total_auth_attempts` | Total number of server authentication attempts. | `counter` | +| `avg_auth_attempts` | Average number of server authentication attempts per statistics period. | `gauge` | +| `pub_sub_listeners` | Current number of clients listening on a pub/sub channel. | `gauge` | +| `pub_sub_listener_received` | Total number of notifications received by pub/sub listeners. | `counter` | +| `pub_sub_listener_dropped` | Total number of notifications dropped by lagging pub/sub listeners. | `counter` | +| `two_pc_recovered_total` | Total number of in-flight 2PC transactions restored from the WAL during recovery. | `counter` |