Documentation Grafana Cloud Monitor applications Database Observability Set up PostgreSQL Amazon RDS

Set up Amazon RDS for PostgreSQL

Set up Database Observability with Grafana Cloud to collect telemetry from Amazon RDS for PostgreSQL instances using Grafana Alloy. You configure your RDS instance 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 Amazon RDS for PostgreSQL parameter groups for monitoring.
• Create monitoring users with required privileges.
• Configure 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 Amazon RDS for PostgreSQL has three steps:

1. Set up your database: Prepare your Amazon RDS instance so Alloy can collect from it.
2. Configure Grafana Alloy: Configure how Alloy collects telemetry and sends it to Grafana Cloud. RDS supports a few methods to choose from.
3. 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:

• An Amazon RDS for PostgreSQL 14.0 or later instance.
• Permission to modify the Amazon RDS parameter group.
• Permission to reboot the Amazon RDS instance if parameter changes require it.
• A PostgreSQL admin user that can create users and grant privileges.
• A planned Grafana Alloy deployment location with network access to your Amazon RDS instance endpoint.

Estimated setup time: 20-40 minutes, excluding any required maintenance window for restarting the instance.

Set up your database

In this step, you’ll prepare your Amazon RDS for PostgreSQL instance 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 the DB parameter group

Enable pg_stat_statements and configure query tracking by adding parameters to your Amazon RDS for PostgreSQL parameter group. These parameters require an instance restart to take effect.

Required parameters

Use the Amazon RDS console

1. Open the RDS Console and navigate to Parameter groups.
2. Create a new parameter group or modify an existing one with family postgres14.
3. Set the parameters listed above.
4. Apply the parameter group to your RDS instance.
5. Reboot the instance to apply changes.

For detailed console instructions, refer to Working with parameter groups in the AWS documentation.

Use Terraform

Using Terraform with aws_db_parameter_group:

hcl Copy

resource "aws_db_parameter_group" "rds_postgres_monitoring" {
  name   = "<INSTANCE_NAME>-monitoring-params"
  family = "postgres14"

  parameter {
    name         = "shared_preload_libraries"
    value        = "pg_stat_statements"
    apply_method = "pending-reboot"
  }

  parameter {
    name         = "pg_stat_statements.track"
    value        = "all"
    apply_method = "pending-reboot"
  }

  parameter {
    name         = "track_activity_query_size"
    value        = "4096"
    apply_method = "pending-reboot"
  }
}

Replace <INSTANCE_NAME> with your RDS instance name.

After applying the parameter group to your instance and restarting, enable the extension in each database you want to monitor:

SQL Copy

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Verify the extension is installed:

SQL Copy

SELECT * FROM pg_stat_statements LIMIT 1;

Create a monitoring user and grant required privileges

Connect to your Amazon RDS for PostgreSQL instance as an administrator and create the monitoring user:

Create the db-o11y user and grant base privileges:

SQL Copy

CREATE USER "db-o11y" WITH PASSWORD '<DB_O11Y_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.

Verify that the user has the correct privileges to query pg_stat_statements:

SQL Copy

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

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

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

GRANT pg_read_all_data TO "db-o11y";

Verify parameter group settings

Verify that the parameter settings were applied correctly after restarting:

SQL Copy

SHOW pg_stat_statements.track;

Expected result: Value is all.

SQL Copy

SHOW track_activity_query_size;

Expected result: Value is 4096.

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 * FROM pg_stat_statements LIMIT 1; runs without error).
• pg_stat_statements.track is all and track_activity_query_size is 4096.
• 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 parameter changes that required a reboot have been applied and the instance restart is complete.

After these checks pass, your RDS instance is ready for Database Observability. Next, configure Alloy so it can collect telemetry from the RDS instance endpoint 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): 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: Set databaseObservability.enabled in your values.yaml. Best for teams already running Alloy through the k8s-monitoring Helm chart.
3. 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

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.
• 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.

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

integrations:
  collector: alloy-singleton
  postgresql:
    instances:
      - name: <INSTANCE_NAME>
        exporter:
          dataSource:
            host: <INSTANCE_ENDPOINT>
            port: 5432
            database: postgres
            sslmode: require
            auth:
              usernameKey: username
              passwordKey: password
          collectors:
            statStatements: true
        databaseObservability:
          enabled: true
          extraConfig: |
            exclude_databases = ["rdsadmin"]
            cloud_provider {
              aws {
                arn = "<AWS_RDS_INSTANCE_ARN>"
              }
            }
          collectors:
            queryDetails:
              enabled: true
            querySamples:
              enabled: true
            schemaDetails:
              enabled: true
            explainPlans:
              enabled: true
        secret:
          create: false
          name: <SECRET_NAME>
          namespace: <NAMESPACE>
        logs:
          enabled: true
          labelSelectors:
            app.kubernetes.io/instance: <INSTANCE_NAME>

Replace the placeholders:

• INSTANCE_NAME: Name for this database instance in Kubernetes.
• INSTANCE_ENDPOINT: RDS instance endpoint hostname.
• AWS_RDS_INSTANCE_ARN: Amazon RDS instance ARN for cloud provider integration.
• SECRET_NAME: Name of the Kubernetes secret containing database credentials.
• NAMESPACE: Kubernetes namespace where the secret exists.

To see the full set of values, refer to the k8s-monitoring Helm chart documentation or the example configuration.

Configure AWS Secrets Manager and Kubernetes (optional)

If you use AWS Secrets Manager with External Secrets Operator to manage database credentials, configure them as follows.

Secret path convention

Store monitoring credentials in AWS Secrets Manager at a path following this convention:

Copy

/kubernetes/rds/<INSTANCE_NAME>/monitoring

PostgreSQL secret format

Store the secret as JSON with the following format:

JSON Copy

{
  "username": "db-o11y",
  "password": "<DB_O11Y_PASSWORD>",
  "engine": "postgres",
  "host": "<INSTANCE_ENDPOINT>.rds.amazonaws.com",
  "port": 5432,
  "dbInstanceIdentifier": "<INSTANCE_NAME>",
  "database": "postgres"
}

Replace the placeholders:

• DB_O11Y_PASSWORD: Password for the db-o11y PostgreSQL user.
• INSTANCE_ENDPOINT: RDS instance endpoint hostname.
• INSTANCE_NAME: RDS instance name.

Create the secret with the AWS CLI

Bash Copy

aws secretsmanager create-secret \
  --name "/kubernetes/rds/<INSTANCE_NAME>/monitoring" \
  --description "Alloy monitoring credentials for Amazon RDS for PostgreSQL instance" \
  --secret-string '{"username":"db-o11y","password":"<DB_O11Y_PASSWORD>","engine":"postgres","host":"<INSTANCE_ENDPOINT>.rds.amazonaws.com","port":5432,"dbInstanceIdentifier":"<INSTANCE_NAME>","database":"postgres"}'

Kubernetes External Secrets configuration

Use the External Secrets Operator to sync the AWS secret into Kubernetes:

YAML Copy

---
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: <INSTANCE_NAME>-db-monitoring-secretstore
spec:
  provider:
    aws:
      service: SecretsManager
      region: <AWS_REGION>
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: <INSTANCE_NAME>-db-monitoring-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: <INSTANCE_NAME>-db-monitoring-secretstore
  dataFrom:
    - extract:
        conversionStrategy: Default
        decodingStrategy: None
        key: /kubernetes/rds/<INSTANCE_NAME>/monitoring
        metadataPolicy: None
        version: AWSCURRENT

Replace the placeholders:

• INSTANCE_NAME: RDS instance name.
• AWS_REGION: AWS region where the secret is stored.

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 Amazon RDS for PostgreSQL configuration blocks

Add these blocks to Alloy for Amazon RDS for PostgreSQL. Replace <DB_NAME>. Create a local.file with the Data Source Name string, for example, "postgresql://<DB_USER>:<DB_PASSWORD>@<INSTANCE_ENDPOINT>:<DB_PORT>/<DB_DATABASE>?sslmode=require":

Alloy Copy

local.file "postgres_secret_<DB_NAME>" {
  filename  = "/var/lib/alloy/postgres_secret_<DB_NAME>"
  is_secret = true
}

prometheus.exporter.postgres "postgres_<DB_NAME>" {
  data_source_names  = [local.file.postgres_secret_<DB_NAME>.content]
  enabled_collectors = ["stat_statements"]

  stat_statements {
    exclude_users      = ["db-o11y", "rdsadmin"]
    exclude_databases  = ["rdsadmin"]
  }

  autodiscovery {
    enabled = true

    // Exclude the rdsadmin database on RDS
    database_denylist = ["rdsadmin"]
  }
}

database_observability.postgres "postgres_<DB_NAME>" {
  data_source_name  = local.file.postgres_secret_<DB_NAME>.content
  forward_to        = [loki.relabel.database_observability_postgres_<DB_NAME>.receiver]
  targets           = prometheus.exporter.postgres.postgres_<DB_NAME>.targets
  enable_collectors = ["query_details", "query_samples", "schema_details", "explain_plans"]
  exclude_users     = ["db-o11y", "rdsadmin"]
  exclude_databases = ["rdsadmin"]

  cloud_provider {
    aws {
      arn = "<AWS_RDS_INSTANCE_ARN>"
    }
  }
}

loki.relabel "database_observability_postgres_<DB_NAME>" {
  forward_to = [loki.write.logs_service.receiver]

  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
}

discovery.relabel "database_observability_postgres_<DB_NAME>" {
  targets = database_observability.postgres.postgres_<DB_NAME>.targets

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }

  // 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  = "<INSTANCE_LABEL>"
  }
}

prometheus.scrape "database_observability_postgres_<DB_NAME>" {
  targets    = discovery.relabel.database_observability_postgres_<DB_NAME>.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).
• AWS_RDS_INSTANCE_ARN: Amazon RDS instance ARN for cloud provider integration.
• INSTANCE_LABEL: Value that sets the instance label on logs and metrics (optional).
• Secret file content example: "postgresql://DB_USER:DB_PASSWORD@INSTANCE_ENDPOINT:DB_PORT/DB_DATABASE?sslmode=require".
  • DB_USER: Database user Alloy uses to connect (for example, db-o11y).
  • DB_PASSWORD: Password for the database user.
  • INSTANCE_ENDPOINT: RDS instance endpoint hostname.
  • DB_PORT: Database port number (default: 5432).
  • DB_DATABASE: Logical database name in the DSN (recommend: use postgres).

Find more about the options supported by the database_observability.postgres component in the reference 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

Configure log_line_prefix via RDS parameter groups:

1. Open the Amazon RDS console → Parameter Groups
2. Create or modify your parameter group
3. Set log_line_prefix to: %m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a:
4. Apply the parameter group to your RDS instance

AWS Credentials

The otelcol.receiver.awscloudwatch component requires AWS credentials. Configure with:

• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
• Docker: Mount ~/.aws credentials or pass environment variables
• Kubernetes: Use IAM Roles for Service Accounts (IRSA) or Kubernetes secrets

Required IAM permissions:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "logs:FilterLogEvents",
      "logs:GetLogEvents",
      "logs:DescribeLogGroups",
      "logs:DescribeLogStreams"
    ],
    "Resource": "arn:aws:logs:*:*:log-group:/aws/rds/instance/*" // Place your log-group arn(s) here
  }]
}

Add logs processing configuration

Add the logs file processing configuration block with otelcol.receiver.awscloudwatch. Replace <AWS_REGION>, <RDS_INSTANCE_NAME>, <INSTANCE_LABEL>, and <DB_NAME> (matching the database name used in the main configuration above):

Alloy Copy

// Storage for CloudWatch state persistence
otelcol.storage.file "cloudwatch" {
  directory = "/var/lib/alloy/storage"
}

// Fetch logs from CloudWatch
otelcol.receiver.awscloudwatch "rds_logs" {
  region  = "<AWS_REGION>"
  storage = otelcol.storage.file.cloudwatch.handler

  logs {
    poll_interval = "1m"
    start_from = "2026-02-01T00:00:00Z" // Set this date to the closest possible to when you want to account logs from

    groups {
      named {
         // Insert your Postgres RDS Cloudwatch log group here
        group_name = "/aws/rds/instance/<RDS_INSTANCE_NAME>/postgresql"
      }
    }
  }

  output {
    logs = [otelcol.processor.transform.rds_logs.input]
  }
}

// Set labels so the Loki exporter promotes them correctly
otelcol.processor.transform "rds_logs" {
  log_statements {
    context = "log"
    statements = [
      `set(attributes["instance"], "<INSTANCE_LABEL>")`,
      `set(attributes["job"], "integrations/db-o11y")`,
      `set(attributes["loki.format"], "raw")`,
      `set(attributes["loki.attribute.labels"], "instance,job")`,
    ]
  }
  output {
    logs = [otelcol.exporter.loki.rds_logs.input]
  }
}

// Convert OTLP to Loki format
otelcol.exporter.loki "rds_logs" {
  forward_to = [database_observability.postgres.postgres_<DB_NAME>.logs_receiver]
}

Historical Log Processing

The logs collector only processes logs with timestamps after the collector’s start time. This prevents re-counting historical logs when the source component replays old entries.

Behavior:

• On startup: Skips logs with timestamps before the collector started
• Relies on the source component features to prevent duplicate log ingestion across restarts

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

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.

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 security groups, subnets, DNS, and the monitoring user’s host restrictions.

For detailed guidance, refer to Troubleshoot Alloy or Troubleshoot PostgreSQL.

Next steps

• View query performance
• Find your application’s queries
• Analyze explain plans