Skip to content

feat: document datadog integration #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
levkk merged 1 commit into from
May 1, 2026
+46 −25
Merged

feat: document datadog integration #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 2 additions & 20 deletions docs/client-drivers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ Some drivers have known compatibility or performance issues, [documented below](
| `asyncpg` (Python) | :material-check-circle-outline: | None. |
| `ruby-pg` (Ruby) | :material-check-circle-outline: | None. |
| `node-postgres` (Node) | :material-check-circle-outline: | None. |
| Postgres.js (Node) | :material-check-circle-outline: | Needs [additional configuration](#postgresjs) for prepared statements to work correctly. |
| Postgres.js (Node) | :material-check-circle-outline: | None. |
| Prisma (Node) | :material-check-circle-outline: | Generates a lot of unique prepared statements, consider limiting the [prepared statements cache](#prisma). |
| Sequelize (Node) | :material-check-circle-outline: | Uses `node-postgres` under the hood, no limitations. |
| PDO (PHP) | :material-check-circle-outline: | None. |
| SQLx (Rust) | :material-check-circle-outline: | None. |
| `tokio_postgres` (Rust) | :material-check-circle-outline: | None. |
| `pgx` (Go) | :material-check-circle-outline: | None. |
| `lib/pq` (Go) | :material-check-circle-outline: | Needs [additional configuration](#libpq) for prepared statements to work correctly. |
| `lib/pq` (Go) | :material-check-circle-outline: | None. |
| `sqlx` (Go) | :material-check-circle-outline: | Uses `pgx` under the hood, no limitations. |
| `libpq` (C/C++) | :material-check-circle-outline: | None. |
| JDBC (Java) | :material-check-circle-outline: | [Manual routing](features/load-balancer/manual-routing.md) requires a bit of [tweaking](#jdbc). |
Expand Down Expand Up @@ -57,15 +57,6 @@ query_parser_engine = "pg_query_raw"

We benchmarked this to be 5 times faster than normal `pg_query` parsing, which should help.

### Postgres.js

`postgres` Node driver uses a combination of named and unnamed prepared statements. For [load balancing](features/load-balancer/index.md) or [sharding](features/sharding/index.md) to work correctly, PgDog needs to cache all prepared statements, including unnamed ones (we call them "anonymous"). This is not the default behavior and requires the following setting:

```toml
[general]
prepared_statements = "extended_anonymous"
```

### Prisma

Prisma doesn't correctly use the `IN` clause with arrays, causing it to generate a very large number of unique prepared statements. This is not a big problem, but if left unchecked, can cause heavy memory usage in PgDog. Consider setting a lower prepared statements [cache limit](features/prepared-statements.md#cache-limit):
Expand All @@ -74,12 +65,3 @@ Prisma doesn't correctly use the `IN` clause with arrays, causing it to generate
[general]
prepared_statements_limit = 1_000
```

### lib/pq

`lib/pq` (Go) uses unnamed prepared statements which PgDog has to cache for [load balancing](features/load-balancer/index.md) or [sharding](features/sharding/index.md) to work correctly. This is not the default behavior and requires the following setting:

```toml
[general]
prepared_statements = "extended_anonymous"
```
8 changes: 4 additions & 4 deletions docs/examples/control_plane/docker-compose.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ services:
- redis_data:/data

migrate:
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-06
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-30
environment:
<<: *control-env
command: control migrate
Expand All @@ -33,7 +33,7 @@ services:
condition: service_healthy

init:
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-06
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-30
environment:
<<: *control-env
command: control onboard --email demo@pgdog.dev --password demopass --token 644b527c-b9d6-4fb2-9861-703bad871ec0 --name Demo
Expand All @@ -42,7 +42,7 @@ services:
condition: service_completed_successfully

control:
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-06
image: ghcr.io/pgdogdev/pgdog-enterprise/control:v2026-04-30
ports:
- "8099:8080"
environment:
Expand All @@ -55,7 +55,7 @@ services:
condition: service_started

pgdog:
image: ghcr.io/pgdogdev/pgdog-enterprise:v2026-04-06
image: ghcr.io/pgdogdev/pgdog-enterprise:v2026-04-30
command: ["pgdog", "--config", "/etc/pgdog/pgdog.toml", "--users", "/etc/secrets/pgdog/users.toml"]
ports:
- "6432:6432"
Expand Down
41 changes: 40 additions & 1 deletion docs/features/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@ icon: material/chart-line
---
# Metrics

PgDog exposes real-time metrics and statistics about clients, servers, connection pools, and more. They are available via two media:
PgDog exposes real-time metrics and statistics about clients, servers, connection pools, and more. They are available via three media:

1. The [admin database](../administration/index.md)
2. OpenMetrics (e.g., Prometheus) endpoint
3. OTEL exporter

## Admin database

Expand Down Expand Up @@ -64,6 +65,44 @@ openmetrics_namespace = "pgdog_"
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.

## OTEL

OTEL is a standard for publishing metrics to compatible systems, like Grafana, Prometheus and other providers like Datadog. PgDog can export metrics to a configured endpoint on an interval, making metrics collection work out of the box.

### Configuration

OTEL export is disabled by default. To enable it, configure the collector endpoint and the necessary credentials. If you're using Datadog, you can set the API key as a separate setting:

=== "pgdog.toml"
```toml
[otel]
datadog_api_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
endpoint = "https://otlp.us5.datadoghq.com/v1/metrics"
```
=== "Helm chart"
```yaml
otel:
datadogApiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
endpoint: "https://otlp.us5.datadoghq.com/v1/metrics"
```

#### 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:

=== "pgdog.toml"
```toml
[otel]
endpoint = "https://otlp.us5.datadoghq.com/v1/metrics"
namespace = "namespace"
```
=== "Helm chart"
```yaml
otel:
endpoint: "https://otlp.us5.datadoghq.com/v1/metrics"
namespace: "namespace"
```

## Available metrics

The following metrics are exported via the OpenMetrics endpoint:
Expand Down
Loading