--- title: "Set up self-managed PostgreSQL | Database Observability documentation" description: "Set up Database Observability for PostgreSQL using Grafana Alloy and send telemetry to Grafana Cloud." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Set up self-managed PostgreSQL Set up Database Observability with Grafana Cloud to collect telemetry from PostgreSQL using Grafana Alloy. You configure your database and Alloy to forward telemetry to Grafana Cloud. If you already use the PostgreSQL integration, Database Observability extends it with query-level telemetry collected by the `database_observability.postgres` Alloy component. ## What you’ll achieve In this article, you: - Configure PostgreSQL for monitoring. - Configure Grafana Alloy with the Database Observability components. - Forward telemetry to Grafana Cloud. - Verify that telemetry appears in Database Observability. ## Setup steps Setting up Database Observability for self-managed PostgreSQL has three steps: 1. [**Set up your database**](#set-up-your-database): Prepare PostgreSQL so Alloy can collect from it. 2. [**Configure Grafana Alloy**](#configure-grafana-alloy): Configure how Alloy collects telemetry and sends it to Grafana Cloud. Self-managed PostgreSQL supports a few methods to choose from. 3. [**Verify telemetry in Grafana Cloud**](#verify-telemetry-in-grafana-cloud): Check telemetry status and confirm that query metrics appear in Database Observability. ## Before you begin To complete this setup, you need: - A self-managed PostgreSQL 14.0 or later database. - Permission to modify your PostgreSQL configuration. - Permission to restart PostgreSQL if configuration changes require it. - A PostgreSQL admin user that can create users and grant privileges. - A planned [Grafana Alloy](/docs/grafana-cloud/observe-and-act/send-data/alloy/) deployment location with network access to the PostgreSQL host. Estimated setup time: 20-40 minutes, excluding any required maintenance window for restarting PostgreSQL. > Note > > Alloy should connect directly to the database host. Avoid connecting Alloy to the database through a load balancer or connection pooler such as PgBouncer as it would limit Alloy’s ability to collect accurate telemetry. ## Set up your database In this step, you’ll prepare PostgreSQL for monitoring by enabling `pg_stat_statements`, creating a monitoring user, and granting the permissions Database Observability needs. Complete this before configuring Alloy. Without it, Alloy can connect to your database, but it won’t be able to collect the telemetry required for Database Observability. ### Configure PostgreSQL settings Enable `pg_stat_statements` and configure query tracking in your PostgreSQL configuration. If you change a startup-only setting, restart PostgreSQL before continuing. #### Required settings Expand table | Setting | Value | Notes | |-----------------------------|----------------------|--------------------------------------------| | `shared_preload_libraries` | `pg_stat_statements` | Requires restart when changed | | `compute_query_id` | `on` | Requires restart when changed | | `pg_stat_statements.track` | `all` | Reload or restart, depending on deployment | | `track_activity_query_size` | `4096` | Requires restart when changed | #### Update PostgreSQL configuration Add or update these settings in `postgresql.conf`: conf ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```conf shared_preload_libraries = 'pg_stat_statements' compute_query_id = on pg_stat_statements.track = all track_activity_query_size = 4096 ``` #### Enable the `pg_stat_statements` extension Create the extension in each database you want to monitor: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- repeat across all logical databases CREATE EXTENSION IF NOT EXISTS pg_stat_statements; ``` ### Create a monitoring user and grant required privileges Create the `db-o11y` user and grant base privileges: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql CREATE USER "db-o11y" WITH PASSWORD ''; GRANT pg_monitor TO "db-o11y"; GRANT pg_read_all_stats TO "db-o11y"; ``` Replace *<DB\_O11Y\_PASSWORD>* with a secure password for the `db-o11y` PostgreSQL user. Alloy must connect as this same user. If you use a name other than `db-o11y`, replace it in every later step, including the disable-tracking SQL. Verify that the user has the correct privileges to query `pg_stat_statements`: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- run with the `db-o11y` user SELECT * FROM pg_stat_statements LIMIT 1; ``` #### Disable tracking of monitoring user queries Prevent tracking of queries executed by the monitoring user itself: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql ALTER ROLE "db-o11y" SET pg_stat_statements.track = 'none'; ``` #### Grant object privileges for detailed data To allow collecting schema details and table information, connect to each logical database and grant access to each schema. For example, for a `payments` database: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- switch to the 'payments' database \c payments -- grant permissions in the 'public' schema GRANT USAGE ON SCHEMA public TO "db-o11y"; GRANT SELECT ON ALL TABLES IN SCHEMA public TO "db-o11y"; -- grant permissions in the 'tests' schema GRANT USAGE ON SCHEMA tests TO "db-o11y"; GRANT SELECT ON ALL TABLES IN SCHEMA tests TO "db-o11y"; ``` Alternatively, if you’re unsure which specific schemas need access, use the predefined role to grant USAGE and SELECT access to all objects: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql GRANT pg_read_all_data TO "db-o11y"; ``` ### Verify PostgreSQL settings Verify that `pg_stat_statements` is loaded: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql SHOW shared_preload_libraries; ``` Expected result: Includes `pg_stat_statements`. Verify the extension is installed in each database you want to monitor: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- Run in each database you want to monitor. SELECT extname FROM pg_extension WHERE extname = 'pg_stat_statements'; ``` Expected result: Returns `pg_stat_statements`. Verify query tracking settings: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql SHOW compute_query_id; SHOW pg_stat_statements.track; SHOW track_activity_query_size; ``` Expected results: - `compute_query_id` is `on`. - `pg_stat_statements.track` is `all`. - `track_activity_query_size` is `4096` or `4kB`. ### Database setup checkpoint Continue to Alloy configuration only after these conditions are true: - `pg_stat_statements` is in `shared_preload_libraries` and the extension is created (`SELECT extname FROM pg_extension WHERE extname = 'pg_stat_statements';` returns `pg_stat_statements`). - `compute_query_id` is `on`, `pg_stat_statements.track` is `all`, and `track_activity_query_size` is `4096` or `4kB`. - The `db-o11y` monitoring user has the required monitoring and object privileges. - The `db-o11y` monitoring user can connect from the network where Alloy will run. - Any configuration changes that required a restart have been applied and the PostgreSQL restart is complete. After these checks pass, PostgreSQL is ready for Database Observability. Next, configure Alloy so it can collect telemetry from the database and send it to Grafana Cloud. ## Configure Grafana Alloy After you set up your database, choose how to configure Alloy. **Pick one:** 1. [**Configuration page (recommended)**](#option-1-configure-alloy-from-the-database-observability-configuration-page-recommended): Database Observability generates the Alloy configuration for you. Then let **Fleet Management** apply it to an enrolled collector, or choose **Manual Configuration** to download the generated file and deploy it yourself. Best for most teams. 2. [**Kubernetes Monitoring Helm chart**](#option-2-configure-alloy-with-the-grafana-kubernetes-monitoring-helm-chart): Set `databaseObservability.enabled` in your `values.yaml`. Best for teams already running Alloy through the k8s-monitoring Helm chart. 3. [**Custom configuration file (advanced)**](#option-3-configure-alloy-with-a-custom-configuration-file-advanced): Write the Alloy configuration yourself. Best for full control, custom components or relabeling, or environments the other paths don’t cover. ### Make sure you’re on a supported Alloy version Alloy `1.17.0` or later is required for Database Observability. Find the latest stable version on [Docker Hub](https://hub.docker.com/r/grafana/alloy/tags). To update, refer to the [Alloy release notes](https://github.com/grafana/alloy/releases). > Note > > New to Alloy? > > [Grafana Alloy](/docs/grafana-cloud/observe-and-act/send-data/alloy/introduction/) is an open source collector that sends your data to Grafana Cloud. Database Observability needs it to collect metrics and query telemetry from your database. > > If you don’t have it installed, refer to [Install Grafana Alloy](/docs/grafana-cloud/observe-and-act/send-data/alloy/set-up/install/) before you continue. ### Option 1: Configure Alloy from the Database Observability Configuration page (recommended) Start here for most deployments. The Configuration page (**Configuration** > **Setup**) generates the Alloy configuration for you, then lets you choose how to deploy it: - **Fleet Management**: Grafana Cloud deploys the configuration to an enrolled Alloy collector and manages it for you, so you don’t edit or ship config files by hand. Best if you want to manage collectors centrally and monitor their health from Grafana Cloud. Refer to [Introduction to Fleet Management](/docs/grafana-cloud/send-data/fleet-management/introduction/). - **Manual Configuration**: Download the generated configuration and deploy it with your own tooling. Best if you can’t use Fleet Management or you already manage Alloy deployment yourself. To start the guided setup flow: 1. Open **Database Observability** in Grafana Cloud. 2. Go to **Configuration**. 3. Open **Setup**. 4. Click **Add database**. 5. Select your database engine. 6. Follow the setup flow and choose **Fleet Management** or **Manual Configuration** when prompted. For an overview of setup methods and what appears in the **Setup** tab, refer to [Configure Alloy from the Configuration page](/docs/grafana-cloud/monitor-applications/database-observability/configure/fleet-management-integration/). ### Option 2: Configure Alloy with the Grafana Kubernetes Monitoring Helm chart Use this method if you already manage Alloy with the k8s-monitoring Helm chart. This path configures Alloy outside the Database Observability setup flow in Grafana Cloud. Extend your `values.yaml` and set `databaseObservability.enabled` to `true` within the PostgreSQL integration. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml integrations: collector: alloy-singleton postgresql: instances: - name: jobLabel: integrations/db-o11y exporter: dataSource: host: port: 5432 database: postgres sslmode: require auth: usernameKey: passwordKey: autoDiscovery: enabled: true collectors: statStatements: enabled: true excludeUsers: ["db-o11y"] databaseObservability: enabled: true secret: create: false name: namespace: postgresql logs: enabled: true labelSelectors: app.kubernetes.io/instance: ``` Replace the placeholders: - `INSTANCE_NAME`: Name for this database instance in Kubernetes. - `DB_HOST`: Hostname or IP address of the database. - `DB_USERNAME_SECRET_KEY`: Kubernetes secret key that holds the database username, for example, `username`. The value must be the monitoring user you created and granted privileges to, for example, `db-o11y`. That username must match `excludeUsers`. - `DB_PASSWORD_SECRET_KEY`: Kubernetes secret key containing database password. To see the full set of values, refer to the k8s-monitoring Helm chart [documentation](https://github.com/grafana/k8s-monitoring-helm/blob/main/charts/k8s-monitoring/charts/feature-integrations/docs/integrations/postgresql.md#database-observability) or the [example configuration](https://github.com/grafana/k8s-monitoring-helm/tree/main/charts/k8s-monitoring/docs/examples/features/database-observability/postgresql). ### Option 3: Configure Alloy with a custom configuration file (advanced) Use this method if you manage Alloy configuration outside Grafana Cloud or need custom relabeling. This path configures Alloy outside the Database Observability setup flow in Grafana Cloud. #### Add the PostgreSQL configuration blocks Add these blocks to Alloy for each PostgreSQL instance. Replace *<DB\_NAME>*. Create a `local.file` with the Data Source Name string, for example, `"postgresql://:@:/?sslmode=require"`: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy local.file "postgres_secret_" { filename = "/var/lib/alloy/postgres_secret_" is_secret = true } prometheus.exporter.postgres "postgres_" { data_source_names = [local.file.postgres_secret_.content] enabled_collectors = ["stat_statements"] stat_statements { exclude_users = ["db-o11y"] } autodiscovery { enabled = true } } database_observability.postgres "postgres_" { data_source_name = local.file.postgres_secret_.content forward_to = [loki.relabel.database_observability_postgres_.receiver] targets = prometheus.exporter.postgres.postgres_.targets enable_collectors = ["query_details", "query_samples", "schema_details", "explain_plans"] } loki.relabel "database_observability_postgres_" { forward_to = [loki.write.logs_service.receiver] // OPTIONAL: add any additional relabeling rules; must be consistent with rules in "discovery.relabel" rule { target_label = "instance" replacement = "" } rule { target_label = "" replacement = "" } } discovery.relabel "database_observability_postgres_" { targets = database_observability.postgres.postgres_.targets rule { target_label = "job" replacement = "integrations/db-o11y" } // OPTIONAL: add any additional relabeling rules; must be consistent with rules in "loki.relabel" // OPTIONAL: relabel `instance` to `dsn` before overwriting `instance`; // the `dsn` label is used in the integration with the knowledge graph rule { source_labels = ["instance"] target_label = "dsn" } rule { target_label = "instance" replacement = "" } rule { target_label = "" replacement = "" } } prometheus.scrape "database_observability_postgres_" { targets = discovery.relabel.database_observability_postgres_.output forward_to = [prometheus.remote_write.metrics_service.receiver] } ``` Replace the placeholders: - `DB_NAME`: Database name Alloy uses in component identifiers (appears in component names and secret filenames). - `INSTANCE_LABEL`: Value that sets the `instance` label on logs and metrics (optional). - `CUSTOM_LABEL_1`, `CUSTOM_VALUE_1`: Optional custom label key and value you attach to logs and metrics. - Secret file content example: `"postgresql://DB_USER:DB_PASSWORD@DB_HOST:DB_PORT/DB_DATABASE?sslmode=require"`. - `DB_USER`: The monitoring user you created and granted privileges to, for example, `db-o11y`. This name must also appear in `exclude_users`. - `DB_PASSWORD`: Password for the database user. - `DB_HOST`: Hostname or IP address of the database. - `DB_PORT`: Database port number. - `DB_DATABASE`: Logical database name in the DSN (recommended: use `postgres`). Find more about the options supported by the `database_observability.postgres` component in the [reference](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/) documentation. #### Add processing of PostgreSQL logs (optional) Add processing of PostgreSQL logs to gather detailed metrics about query and server errors. The `logs` collector processes PostgreSQL logs received through the `logs_receiver` entry point and exports Prometheus metrics for query and server errors. ##### Configure `log_line_prefix` The database must be configured with the following `log_line_prefix` value: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- Set log format (run as superuser) ALTER SYSTEM SET log_line_prefix = '%m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a:'; -- Reload configuration SELECT pg_reload_conf(); ``` Verify the that the setting has been applied correctly: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql SHOW log_line_prefix; ``` Expected value: `%m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a:` Example log line: text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text 2026-02-19 11:36:.767 GMT:172.18.0.3(35058):user@dbname:[151]:326:40001:2026-02-19 11:35:11 GMT:24/106:0:6996f56f.97:[unknown]ERROR: could not serialize access due to concurrent update ``` ##### Add logs processing configuration Add the logs file processing configuration block: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy loki.source.file "database_observability_postgres_" { targets = [{ __path__ = "/var/log/postgresql/postgresql-*.log", job = "postgres_logs", }] forward_to = [database_observability.postgres.postgres_.logs_receiver] } ``` > Note > > **Persistent storage:** The data path (`--storage.path`) must be persisted across restarts to maintain `loki.source.file` positions file. #### Add Prometheus and Loki write configuration Add the Prometheus remote write and Loki write configuration. From Grafana Cloud, open your stack to get the URLs and generate API tokens: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy prometheus.remote_write "metrics_service" { endpoint { url = sys.env("GCLOUD_HOSTED_METRICS_URL") basic_auth { password = sys.env("GCLOUD_RW_API_KEY") username = sys.env("GCLOUD_HOSTED_METRICS_ID") } } } loki.write "logs_service" { endpoint { url = sys.env("GCLOUD_HOSTED_LOGS_URL") basic_auth { password = sys.env("GCLOUD_RW_API_KEY") username = sys.env("GCLOUD_HOSTED_LOGS_ID") } } } ``` Replace the placeholders: - `GCLOUD_HOSTED_METRICS_URL`: Your Grafana Cloud Prometheus remote write URL. - `GCLOUD_HOSTED_METRICS_ID`: Your Grafana Cloud Prometheus instance ID (username). - `GCLOUD_HOSTED_LOGS_URL`: Your Grafana Cloud Loki write URL. - `GCLOUD_HOSTED_LOGS_ID`: Your Grafana Cloud Loki instance ID (username). - `GCLOUD_RW_API_KEY`: Grafana Cloud API token with write permissions. ## Verify telemetry in Grafana Cloud After Alloy starts, verify that Database Observability is receiving telemetry. 1. In Grafana Cloud, open **Database Observability**. 2. Go to **Configuration**. 3. Select your database instance. 4. Confirm that telemetry status checks pass. 5. Open **Queries Overview** and confirm that query metrics appear. After telemetry appears, the database instance should be visible and Queries Overview should show query metrics. Additional data such as query samples, wait events, schema details, and explain plans becomes available as Alloy collects it and as the database engine supports it. Telemetry can take a few minutes to appear. For detailed status checks, refer to [Verify telemetry status](/docs/grafana-cloud/monitor-applications/database-observability/configure/verify-telemetry-status/). ## Troubleshoot first-run issues If data doesn’t appear after setup: - If the database instance doesn’t appear in Database Observability, check Alloy connectivity and labels. - If telemetry status checks fail, use the Configuration page to identify the failed requirement. - If query metrics appear but samples, schema details, or explain plans are missing, check database privileges and `pg_stat_statements` settings. - If Alloy can’t connect to the database, check network and firewall settings, DNS, and the monitoring user’s host restrictions. For detailed guidance, refer to [Troubleshoot Alloy](/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/alloy/) or [Troubleshoot PostgreSQL](/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/postgres/). ## Next steps - [View query performance](/docs/grafana-cloud/monitor-applications/database-observability/monitor/view-query-performance/) - [Find your application’s queries](/docs/grafana-cloud/monitor-applications/database-observability/monitor/find-application-queries/) - [Link traces and queries](/docs/grafana-cloud/monitor-applications/database-observability/monitor/link-traces/) - [Analyze explain plans](/docs/grafana-cloud/monitor-applications/database-observability/investigate/analyze-explain-plans/)