From 9ffe0ff24c851b3969a7276def3299f138896293 Mon Sep 17 00:00:00 2001 From: Dmitry Kochetov Date: Mon, 31 Aug 2026 17:51:37 +0400 Subject: [PATCH 1/3] Document Aurora parameter groups and expand PostgreSQL installation. Align agent docs with Releem Agent: cluster parameter groups, writer-only cluster apply, and PostgreSQL install options. Co-authored-by: Cursor --- .../aws-rds.md | 4 +- ...how-to-check-if-releem-agent-is-working.md | 4 +- docs/getting-started/step-2-add-server.md | 5 +- docs/releem-agent/configuration-settings.md | 10 + ...-managed-aws-rds-automatic-installation.md | 91 +++- .../postgresql-manual-installation-linux.md | 511 +++++++++++++++--- 6 files changed, 536 insertions(+), 89 deletions(-) diff --git a/docs/configuration-tuning/how-to-apply-configuration-manually/aws-rds.md b/docs/configuration-tuning/how-to-apply-configuration-manually/aws-rds.md index ffcb0ac..bf4bf7b 100644 --- a/docs/configuration-tuning/how-to-apply-configuration-manually/aws-rds.md +++ b/docs/configuration-tuning/how-to-apply-configuration-manually/aws-rds.md @@ -5,7 +5,9 @@ sidebar_label: AWS RDS # How to apply the Recommended Configuration for AWS RDS -Use Parameter Groups to apply the recommended configuration. Follow the steps below: +Use Parameter Groups to apply the recommended configuration. Follow the steps below. + +For Amazon Aurora MySQL or Aurora PostgreSQL, update both the instance DB parameter group and the DB cluster parameter group when Releem recommendations target cluster parameters. AWS-managed default groups cannot be modified. ## Step 1: Modify the Parameter Group in AWS RDS diff --git a/docs/getting-started/how-to-check-if-releem-agent-is-working.md b/docs/getting-started/how-to-check-if-releem-agent-is-working.md index 3053c56..84b5206 100644 --- a/docs/getting-started/how-to-check-if-releem-agent-is-working.md +++ b/docs/getting-started/how-to-check-if-releem-agent-is-working.md @@ -49,7 +49,9 @@ Please exclude "releem" user from MySQLGovernor. If your server is managed through WHM/cPanel, use the [WHM/cPanel installation guide](/releem-agent/installation-guides/whm-cpanel) for setup-specific troubleshooting, including how to verify that cPanel MySQL auto-adjust settings are disabled. ### AWS RDS -[Common issues for AWS RDS](/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation#common-issues-for-aws-rds) +[Common issues for AWS RDS MySQL and Aurora MySQL](/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation#common-issues-for-aws-rds) + +[Common issues for AWS RDS PostgreSQL and Aurora PostgreSQL](/releem-agent/installation-guides/postgresql-aws-rds#common-issues-for-aws-rds-and-aurora-postgresql) ## Releem Agent Installation Errors diff --git a/docs/getting-started/step-2-add-server.md b/docs/getting-started/step-2-add-server.md index 8b7cd40..acc3451 100644 --- a/docs/getting-started/step-2-add-server.md +++ b/docs/getting-started/step-2-add-server.md @@ -16,11 +16,14 @@ Click the "Add Server" button to start the setup process. Choose the type of database server you are adding: - [MySQL on Linux Server: Automatic Agent Installation (Linux)](/releem-agent/installation-guides/self-managed-servers-automatic-installation) – Automatic installation for MySQL instances running on Linux-based servers. - [MySQL on Linux Server: Advanced Agent Installation](/releem-agent/installation-guides/self-managed-servers-manual-installation-linux) – Manual installation for MySQL instances running on Linux-based servers. Use this guide if you don't have a MySQL root user, or if MySQL is installed on a different IP address, or if you want to create a Releem user manually. +- [PostgreSQL on Linux Server: Automatic Agent Installation](/releem-agent/installation-guides/postgresql-automatic-installation) – Automatic installation for PostgreSQL instances running on Linux-based servers. - [PostgreSQL on Linux Server: Manual Agent Installation](/releem-agent/installation-guides/postgresql-manual-linux) – Manual installation for PostgreSQL instances running on Linux-based servers. +- [PostgreSQL in Docker](/releem-agent/installation-guides/postgresql-docker-installation) – Manual installation for PostgreSQL instances running in Docker containers. +- [PostgreSQL on AWS RDS and Aurora](/releem-agent/installation-guides/postgresql-aws-rds) – For managed PostgreSQL databases hosted on Amazon RDS or Aurora. - [WHM/cPanel](/releem-agent/installation-guides/whm-cpanel) – Recommended installation path for database servers managed through WHM/cPanel. - [MySQL on Linux Server: Manual Installation in Docker](/releem-agent/installation-guides/self-managed-servers-docker-installation) – Manual installation for MySQL instances running in Docker containers. - [Self-Managed Server (Windows)](/releem-agent/installation-guides/self-managed-servers-manual-installation-windows) – For MySQL instances running on Windows. -- [MySQL on AWS RDS: CloudFormation installation](/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation) – For managed MySQL databases hosted on AWS. +- [MySQL on AWS RDS and Aurora: CloudFormation installation](/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation) – For managed MySQL databases hosted on Amazon RDS or Aurora. - [MySQL on GCP Cloud SQL: Manual installation](/releem-agent/installation-guides/cloud-managed-gcp-cloud-sql-automatic-installation) – For managed MySQL databases hosted on GCP. - [MySQL in Kubernetes](/releem-agent/installation-guides/installation-in-kubernetes) – If your MySQL instance is deployed in a Kubernetes cluster. diff --git a/docs/releem-agent/configuration-settings.md b/docs/releem-agent/configuration-settings.md index 042bd65..a91385f 100644 --- a/docs/releem-agent/configuration-settings.md +++ b/docs/releem-agent/configuration-settings.md @@ -30,6 +30,9 @@ aws_rds_db="[RDS_INSTANCE_NAME]" # AWS RDS parameter group name aws_rds_parameter_group="releem-agent" +# AWS RDS / Aurora cluster parameter group name. Required for Aurora; leave empty for non-Aurora RDS +aws_rds_cluster_parameter_group="" + #GCP project ID for Cloud SQL instance gcp_project_id="my-project-123" @@ -78,6 +81,12 @@ pg_port="5432" # PostgreSQL SSL mode: false = disable, true = require pg_ssl_mode=false +# Command to restart PostgreSQL service +pg_restart_service="/bin/systemctl restart postgresql" + +# Path to copy the recommended PostgreSQL config +pg_cnf_dir="/etc/postgresql/releem.conf.d" + # Command to restart MySQL service mysql_restart_service="/bin/systemctl restart mysql" @@ -134,6 +143,7 @@ releem_region="" - For MySQL, the `mysql_password` field should contain the password for the user specified in `mysql_user`. - For PostgreSQL, the `pg_password` field should contain the password for the user specified in `pg_user`. - PostgreSQL monitoring is enabled when `pg_user` and `pg_password` are configured. +- For Aurora, set `aws_rds_cluster_parameter_group` to the custom DB cluster parameter group attached in AWS. Leave it empty for non-Aurora RDS. The configured instance and cluster group names must match the groups attached in AWS. - Set `query_optimization=true` to enable SQL query optimization features where supported. - Use `databases_query_optimization` to specify which databases to monitor for query optimization (leave empty for all databases). - The `releem_region` field can be set to `EU` for European data storage or left empty for default storage. diff --git a/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md b/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md index 0b165ea..59be7f9 100644 --- a/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md +++ b/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md @@ -1,24 +1,37 @@ --- id: cloud-managed-aws-rds-automatic-installation -title: AWS RDS +title: RDS --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Cloud-Managed AWS RDS Automatic Installation - +# Cloud-Managed AWS RDS and Aurora MySQL Automatic Installation Use this instruction to install Releem Agent automatically via CloudFormation to AWS Fargate, or manually on an EC2 instance. Releem Agent will run in a container on AWS Fargate or directly on the EC2 instance, depending on your choice. -To configure automatic applying of recommended configuration please sign in to your AWS account and do the following steps: - - In the Amazon RDS console, create a Parameter Group for the version of your database named “releem-agent". - - Modify the database by specifying in “DB parameter group” the Parameter group created in the previous step. - - Reboot the database if required to apply the changes. - -The requirements for RDS instance: -- Enhanced monitoring to collect system performance metrics. +Releem supports Amazon RDS MySQL, Amazon RDS MariaDB, and Amazon Aurora MySQL. Configure one Agent for each DB instance endpoint. + +## Parameter groups + +To apply recommended configuration automatically, sign in to your AWS account and prepare custom parameter groups. AWS-managed default groups cannot be modified and are not valid onboarding targets. + +**Amazon RDS MySQL or MariaDB (non-Aurora):** +- Create a custom DB parameter group for your database version, for example `releem-agent`. +- Attach it to the instance as **DB parameter group**. +- Leave the cluster parameter group empty. +- Reboot the instance if AWS requires it. + +**Amazon Aurora MySQL:** +- Create a custom DB parameter group for the instance and a custom DB cluster parameter group for the cluster. +- Attach both groups in AWS. The names you configure for Releem must match the groups attached in AWS. +- Both groups must be ready before the Agent applies recommendations. A recommendation can target either group. +- Only the Agent that targets the writer modifies cluster parameters. That Agent needs `rds:ModifyDBClusterParameterGroup` permission. + +The requirements for the RDS or Aurora instance: +- Enhanced Monitoring to collect system performance metrics. - Performance Insights to collect MySQL performance metrics. -- Performance Schema to collect MySQL performance metrics. Please change the following variable in the Parameter Group and reboot the database instance: +- Performance Schema to collect MySQL performance metrics. Change the following variables in the custom parameter group and reboot the database instance if required: + ```ini performance_schema=ON slow_query_log=ON @@ -38,6 +51,7 @@ You have the following options to install Releem Agent: - ecr:GetDownloadUrlForLayer - ecr:BatchGetImage - rds:ModifyDBParameterGroup + - rds:ModifyDBClusterParameterGroup To move forward just do the following steps: 1. Create read-only user "releem" in MySQL using the [instruction](/releem-agent/mysql-permissions). To enable Automatic SQL Query Optimization please add [Additional Permissions](/releem-agent/mysql-permissions#additional-database-permissions-required). @@ -45,13 +59,18 @@ You have the following options to install Releem Agent: 2. Open the [CloudFormation Quick Create page](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateUrl=https://releem.s3.amazonaws.com/v2/releem-agent-cloudformation.yml&stackName=releem-agent) in your browser, check that the correct region is selected, and fill in the following fields: - Image: Releem Agent Docker image in the `releem/releem-agent:[version]` format. Use the latest version available on [Docker Hub](https://hub.docker.com/r/releem/releem-agent/tags). - APIKey: Releem API Key from the [Profile page](https://app.releem.com/profile?menu=profile) in the Releem Customer Portal. - - DBID: RDS DB Instance ID. If you're using a cluster, please set the instance name you would like to tune. + - DBID: RDS DB Instance ID. For Aurora, set the instance name you want to monitor, not the cluster endpoint. Deploy one stack per instance. + - DatabaseType: leave `mysql` (default) for RDS MySQL, MariaDB, and Aurora MySQL. - DBUser: User to collect metrics from the SQL server, that we added in the step 1. - DBPassword: Password for user + - DBSSLMode: set `true` when the instance requires SSL. - SecurityGroupIDs: Releem Agent SecurityGroups to connect to RDS. Please Allow All Outbound traffic for Releem Agent Security Group. - SubnetIDs: Releem Agent container should be able to connect to RDS. - QueryOptimization: set True if Releem Agent should collect additional information for Automatic SQL Query Optimization. - - DBParameterGroup: Parameter Group name which Releem will use to set recommendations for RDS instance. Default name is "releem-agent". + - DBParameterGroup: Custom DB parameter group attached to the instance. Required for RDS and Aurora instance parameters. + - DBClusterParameterGroup: Custom DB cluster parameter group attached to Aurora. Required for Aurora. Leave empty only for non-Aurora RDS. + + `DatabaseType` defaults to `mysql` and exposes MySQL (`DB_*`) credentials to the container. Select `postgresql` only for Aurora PostgreSQL; see [PostgreSQL RDS](/releem-agent/installation-guides/postgresql-aws-rds). 3. Next, click "Create Stack". @@ -73,7 +92,8 @@ You have the following options to install Releem Agent: "cloudwatch:Get*", "logs:Get*", "ec2:Describe*", - "rds:ModifyDBParameterGroup" + "rds:ModifyDBParameterGroup", + "rds:ModifyDBClusterParameterGroup" ], "Resource": "*", "Effect": "Allow" @@ -82,15 +102,25 @@ You have the following options to install Releem Agent: } ``` - 3. Run Installation command as a root user on the server: - ```ini + 3. Run Installation command as a root user on the server. + + **Amazon RDS MySQL or MariaDB:** + + ```bash RELEEM_INSTANCE_TYPE="aws/rds" RELEEM_AWS_REGION="[AwsRegion]" RELEEM_AWS_RDS_DB="[AwsRdsDBidentifier]" RELEEM_AWS_RDS_PARAMETER_GROUP="releem-agent" RELEEM_MYSQL_PASSWORD='[Password]' RELEEM_MYSQL_LOGIN='releem' RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 RELEEM_QUERY_OPTIMIZATION=true bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" ``` + + **Amazon Aurora MySQL:** add `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP` with the custom cluster parameter group name. Set `RELEEM_AWS_RDS_DB` to the instance identifier, not the cluster endpoint. Repeat the installation for each instance you want to monitor. Only the writer Agent applies cluster parameter recommendations. + + ```bash + RELEEM_INSTANCE_TYPE="aws/rds" RELEEM_AWS_REGION="[AwsRegion]" RELEEM_AWS_RDS_DB="[AwsRdsDBidentifier]" RELEEM_AWS_RDS_PARAMETER_GROUP="releem-agent" RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP="releem-agent-cluster" RELEEM_MYSQL_PASSWORD='[Password]' RELEEM_MYSQL_LOGIN='releem' RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 RELEEM_QUERY_OPTIMIZATION=true bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" + ``` **Parameters:** - `RELEEM_AWS_REGION` - AWS region name - - `RELEEM_AWS_RDS_DB` - RDS instance name. - - `RELEEM_AWS_RDS_PARAMETER_GROUP` - Parameter Group name which Releem will use to set recommendations for RDS instance. Default name is "releem-agent". + - `RELEEM_AWS_RDS_DB` - RDS or Aurora instance identifier. + - `RELEEM_AWS_RDS_PARAMETER_GROUP` - Custom DB parameter group name. Required. + - `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP` - Custom DB cluster parameter group name. Required for Aurora. Omit for non-Aurora RDS. - `RELEEM_MYSQL_LOGIN` - MySQL User name to collect MySQL metrics - `RELEEM_MYSQL_PASSWORD` - MySQL User password to collect MySQL metrics - `RELEEM_DB_MEMORY_LIMIT` - Change parameter in case there are other software installed on the server. Default value is 0 means use all memory. @@ -116,7 +146,8 @@ You have the following options to install Releem Agent: "cloudwatch:Get*", "logs:Get*", "ec2:Describe*", - "rds:ModifyDBParameterGroup" + "rds:ModifyDBParameterGroup", + "rds:ModifyDBClusterParameterGroup" ], "Resource": "*", "Effect": "Allow" @@ -142,6 +173,8 @@ You have the following options to install Releem Agent: -e RELEEM_QUERY_OPTIMIZATION=true \ releem/releem-agent:[version] ``` + + For Aurora MySQL, add `-e AWS_RDS_CLUSTER_PARAMETER_GROUP="releem-agent-cluster"` (or `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP`). Run one container per instance. Only the writer container applies cluster parameter recommendations. **Docker Compose** @@ -165,6 +198,7 @@ You have the following options to install Releem Agent: AWS_REGION: "[AWS_REGION]" AWS_RDS_DB: "[AWS_RDS_DB]" AWS_RDS_PARAMETER_GROUP: "releem-agent" + AWS_RDS_CLUSTER_PARAMETER_GROUP: "releem-agent-cluster" RELEEM_QUERY_OPTIMIZATION: true # You can duplicate docker compose services to launch multiple agents by changing the name, container_name, and environment. @@ -178,10 +212,13 @@ You have the following options to install Releem Agent: DB_PASSWORD: "[DB_PASSWORD]" INSTANCE_TYPE: "aws/rds" AWS_REGION: "[AWS_REGION]" - AWS_RDS_DB: "[AWS_RDS_DB]" + AWS_RDS_DB: "[AWS_RDS_DB_READER]" AWS_RDS_PARAMETER_GROUP: "releem-agent" + AWS_RDS_CLUSTER_PARAMETER_GROUP: "releem-agent-cluster" RELEEM_QUERY_OPTIMIZATION: true ``` + + Leave `AWS_RDS_CLUSTER_PARAMETER_GROUP` empty or omit it for non-Aurora RDS. ***Parameters:*** - `RELEEM_API_KEY`: API Key. Get it from Profile page in Releem Customer Portal. @@ -189,8 +226,9 @@ You have the following options to install Releem Agent: - `DB_USER`: MySQL User name to collect MySQL metrics - `DB_PASSWORD`: MySQL User password to collect MySQL metrics - `AWS_REGION`: AWS region name - - `AWS_RDS_DB`: RDS instance name. - - `AWS_RDS_PARAMETER_GROUP`: Parameter Group name which Releem will use to set recommendations for RDS instance. Default name is "releem-agent". + - `AWS_RDS_DB`: RDS or Aurora instance identifier. + - `AWS_RDS_PARAMETER_GROUP`: Custom DB parameter group name. Required. + - `AWS_RDS_CLUSTER_PARAMETER_GROUP` / `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP`: Custom DB cluster parameter group name. Required for Aurora. - `RELEEM_QUERY_OPTIMIZATION` - set 'true' if Releem Agent should collect additional information for Automatic SQL Query Optimization. Please use the latest version of Releem Agent. You can find the latest version of Releem Agent by clicking on the [link](https://hub.docker.com/r/releem/releem-agent/tags). @@ -199,7 +237,7 @@ You have the following options to install Releem Agent: -## Common Issues for AWS RDS +## Common Issues for AWS RDS {#common-issues-for-aws-rds} To check Releem Agent logs please open CloudWatch -> Log Groups and then select Releem Agent log group. @@ -229,3 +267,10 @@ To check Releem Agent logs please open CloudWatch -> Log Groups and then select 7. Performance_schema_ variables aren't being applied on AWS RDS - Amazon RDS only applies performance_schema_* variables when performance_schema is explicitly set to 1 in the Parameter Group. By default, it's set to 0, even though Performance Insights enables it automatically at the database level. - Solution: Set performance_schema from 0 to 1 in your Parameter Group, save the changes, and reboot your RDS instance. + +8. Aurora apply fails because the cluster parameter group is missing or does not match + - Create a custom DB cluster parameter group, attach it to the cluster, and set `DBClusterParameterGroup` / `AWS_RDS_CLUSTER_PARAMETER_GROUP` to that exact name. + - AWS-managed default groups cannot be modified. + +9. Cluster parameters are not applied on a reader + - Only the Agent targeting the writer modifies cluster parameters. Keep an Agent on the writer instance. diff --git a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md index 44552db..18ff613 100644 --- a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md +++ b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md @@ -6,104 +6,488 @@ title: "PostgreSQL" import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Installing Releem Agent on Self-Managed PostgreSQL Servers -Use this guide to configure Releem Agent for PostgreSQL metrics collection on a self-managed Linux server. +## Installation Steps + +Choose the installation flow that matches your setup: + + + + +# Automatic Installation for Self-Managed PostgreSQL Servers + +Use this instruction to install Releem Agent automatically on a self-managed PostgreSQL server. The installer creates the monitoring user, enables `pg_stat_statements` when possible, and starts metrics collection. ## Prerequisites -Before proceeding, ensure that the `postgresql-contrib` package is installed for your specific PostgreSQL version. This package provides extensions required for Releem Agent operation. +Install the `postgresql-contrib` package for your PostgreSQL version. This package provides extensions required by Releem Agent. ## Installation Steps -Choose the installation flow that matches your setup: +1. Click **Add Server** in the Releem Customer Portal and select PostgreSQL if that option is available. +2. Run the Releem Agent installation command as a **root** user on the server: - - +```bash +RELEEM_PG_TYPE=1 RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" +``` -The Releem Agent installer can create the PostgreSQL monitoring user automatically. +Set `RELEEM_PG_ROOT_LOGIN` and `RELEEM_PG_ROOT_PASSWORD` when the PostgreSQL superuser is not available through peer/passwordless authentication. If the password is omitted, the installer first tries peer/passwordless access and then prompts for it in the console. -1. Run the Releem Agent installation command as a root user on the server: - ```bash - RELEEM_PG_TYPE=1 RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" - ``` - Set `RELEEM_PG_ROOT_LOGIN` and `RELEEM_PG_ROOT_PASSWORD` when the PostgreSQL superuser is not available through peer/passwordless authentication. If the password is omitted, the installer first tries peer/passwordless access and then prompts for it in the console. +**Parameters:** +- `RELEEM_HOSTNAME` - Server hostname, which should display in the Releem Dashboard. +- `RELEEM_PG_LOGIN` - PostgreSQL user name for collecting metrics. The installer creates `releem` when this is omitted. +- `RELEEM_PG_PASSWORD` - PostgreSQL user password for collecting metrics. The installer generates a password when this is omitted. +- `RELEEM_DB_MEMORY_LIMIT` - Change this parameter when other software is installed on the server. Default value is `0`, which means use all memory. +- `RELEEM_API_KEY` - API Key. Get it from the Profile page in Releem Customer Portal. +- `RELEEM_PG_TYPE` - set to `1` to explicitly select the PostgreSQL installation path. +- `RELEEM_PG_HOST` - use this variable when PostgreSQL listens on a different interface or is available only through a socket. +- `RELEEM_PG_PORT` - use this variable when PostgreSQL listens on a different port. +- `RELEEM_PG_DATABASE` - database used for the monitoring connection. Default value is `postgres`. +- `RELEEM_PG_SSL_MODE` - PostgreSQL SSL mode for the collector: `true` for SSL (`sslmode=require`), `false` (or omitted) for `sslmode=disable`. +- `RELEEM_PG_ROOT_LOGIN` - PostgreSQL superuser used during automatic `releem` user creation. Default value is `postgres`. +- `RELEEM_PG_ROOT_PASSWORD` - password for the PostgreSQL superuser. If omitted, the installer first tries peer/passwordless access and then prompts for the password in the console. +- `RELEEM_PG_CONF_DIR` - directory where Releem writes recommended PostgreSQL configuration. Set this when the installer cannot detect `postgresql.conf`. +- `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. - **Parameters:** - - `RELEEM_HOSTNAME` - Server hostname, which should display in the Releem Dashboard. - - `RELEEM_PG_LOGIN` - PostgreSQL user name for collecting metrics. - - `RELEEM_PG_PASSWORD` - PostgreSQL user password for collecting metrics. - - `RELEEM_DB_MEMORY_LIMIT` - Change parameter in case there are other software installed on the server. Default value is 0 means use all memory. - - `RELEEM_API_KEY` - API Key. Get it from Profile page in Releem Customer Portal. - - `RELEEM_PG_TYPE` - set to `1` to explicitly select the PostgreSQL installation path. - - `RELEEM_PG_HOST` - use this variable in case PostgreSQL listens different interface or connection available only through socket. - - `RELEEM_PG_PORT` - use this variable in case PostgreSQL listens different port. - - `RELEEM_PG_SSL_MODE` - PostgreSQL SSL mode for collector: `true` for SSL (`sslmode=require`), `false` (or omitted) for `sslmode=disable`. - - `RELEEM_PG_ROOT_LOGIN` - PostgreSQL superuser used during automatic `releem` user creation. Default value is `postgres`. - - `RELEEM_PG_ROOT_PASSWORD` - password for the PostgreSQL superuser. If omitted, the installer first tries peer/passwordless access and then prompts for the password in the console. - - `RELEEM_QUERY_OPTIMIZATION` - set 'true' if Releem Agent should collect additional information for Automatic SQL Query Optimization. +Setting `RELEEM_PG_TYPE`, `RELEEM_PG_HOST`, `RELEEM_PG_LOGIN`, `RELEEM_PG_PASSWORD`, `RELEEM_PG_ROOT_LOGIN`, or `RELEEM_PG_ROOT_PASSWORD` makes the installer use the PostgreSQL installation path. - Setting `RELEEM_PG_TYPE`, `RELEEM_PG_HOST`, `RELEEM_PG_LOGIN`, `RELEEM_PG_PASSWORD`, `RELEEM_PG_ROOT_LOGIN`, `RELEEM_PG_ROOT_PASSWORD` variables makes the installer use the PostgreSQL installation path. +For a full list of configuration settings, see [Releem Agent Configuration](/releem-agent/configuration). + +3. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. - For a full list of configuration settings, please refer to the [Releem Agent Configuration](/releem-agent/configuration). +## Notes -2. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. +- PostgreSQL support is enabled when `pg_user` and `pg_password` are set in the agent configuration. +- `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. +- If you prefer to create the monitoring user yourself, use the [Manual](/releem-agent/installation-guides/postgresql-manual-linux) installation. -Create the PostgreSQL monitoring user before running the Releem Agent installation command. +# Manual Installation for Self-Managed PostgreSQL Servers + +Use this instruction to install Releem Agent after you create the PostgreSQL monitoring user yourself. + +## Prerequisites + +Install the `postgresql-contrib` package for your PostgreSQL version. This package provides extensions required by Releem Agent. + +## Installation Steps + +1. Create a PostgreSQL monitoring user: + +```sql +CREATE USER releem WITH PASSWORD '[Password]'; +GRANT pg_monitor TO releem; +GRANT SELECT ON pg_hba_file_rules TO releem; +GRANT EXECUTE ON FUNCTION pg_hba_file_rules TO releem; +``` + +Enable `pg_stat_statements` for query performance metrics. + +Add the following line to `postgresql.conf`: + +```ini +shared_preload_libraries = 'pg_stat_statements' +``` + +Add the following line to `pg_hba.conf` for local agent connections: + +```ini +host all releem 127.0.0.1/32 md5 +``` + +Add the following line to `pg_hba.conf` for remote agent connections: + +```ini +host all releem 0.0.0.0/0 md5 +``` + +Restart PostgreSQL, then create the extension in the database used by Releem Agent. The default database is `postgres`: + +```sql +\c postgres +CREATE EXTENSION IF NOT EXISTS pg_stat_statements; +``` + +To enable Automatic SQL Query Optimization, grant additional permissions as a PostgreSQL superuser: + +```sql +-- PostgreSQL 14+ +GRANT pg_read_all_data TO releem; + +-- PostgreSQL 12/13 +GRANT CONNECT ON DATABASE "" TO releem; +GRANT USAGE ON SCHEMA "" TO releem; +GRANT SELECT ON ALL TABLES IN SCHEMA "" TO releem; +GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA "" TO releem; +``` + +Replace `` and `` with all monitored databases and schemas. For most self-managed deployments, start with `postgres` and `public`. + +2. After the PostgreSQL user is created, run the Releem Agent installation command as a root user on the server: + +```bash +RELEEM_PG_PASSWORD='[Password]' RELEEM_PG_LOGIN='releem' RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" +``` + +**Parameters:** +- `RELEEM_HOSTNAME` - Server hostname, which should display in the Releem Dashboard. +- `RELEEM_PG_LOGIN` - PostgreSQL user name for collecting metrics. +- `RELEEM_PG_PASSWORD` - PostgreSQL user password for collecting metrics. +- `RELEEM_DB_MEMORY_LIMIT` - Change this parameter when other software is installed on the server. Default value is `0`, which means use all memory. +- `RELEEM_API_KEY` - API Key. Get it from the Profile page in Releem Customer Portal. +- `RELEEM_PG_TYPE` - set to `1` to explicitly select the PostgreSQL installation path. +- `RELEEM_PG_HOST` - use this variable when PostgreSQL listens on a different interface or is available only through a socket. +- `RELEEM_PG_PORT` - use this variable when PostgreSQL listens on a different port. +- `RELEEM_PG_DATABASE` - database used for the monitoring connection. Default value is `postgres`. +- `RELEEM_PG_SSL_MODE` - PostgreSQL SSL mode for the collector: `true` for SSL (`sslmode=require`), `false` (or omitted) for `sslmode=disable`. +- `RELEEM_PG_CONF_DIR` - directory where Releem writes recommended PostgreSQL configuration. Set this when the installer cannot detect `postgresql.conf`. +- `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. + +For a full list of configuration settings, see [Releem Agent Configuration](/releem-agent/configuration). + +3. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. + + + + +# Installation in a Docker Container on Self-Managed PostgreSQL Servers + +Use this instruction to run Releem Agent in a Docker container against a self-managed PostgreSQL server. Releem Agent collects metrics and recommends configuration. 1. Create a PostgreSQL monitoring user: + +```sql +CREATE USER releem WITH PASSWORD '[Password]'; +GRANT pg_monitor TO releem; +GRANT SELECT ON pg_hba_file_rules TO releem; +GRANT EXECUTE ON FUNCTION pg_hba_file_rules TO releem; +``` + +Enable `pg_stat_statements` and create the extension in the database used by Releem Agent. The default database is `postgres`: + +```sql +CREATE EXTENSION IF NOT EXISTS pg_stat_statements; +``` + +To enable Automatic SQL Query Optimization, grant additional permissions as described in [Enable SQL Query Optimization](/query-optimization/enable-sql-query-optimization). + +2. Run the container using Docker or Docker Compose. + + **Docker** + + ```bash + docker run -d -ti --name 'releem-agent' \ + -e RELEEM_HOSTNAME="[Hostname]" \ + -e PG_HOST="[PG_HOST]" \ + -e PG_PORT="[PG_PORT]" \ + -e PG_PASSWORD="[PG_PASSWORD]" \ + -e PG_USER="releem" \ + -e RELEEM_API_KEY="[RELEEM_API_KEY]" \ + -e MEMORY_LIMIT=[MEMORY_LIMIT] \ + -e RELEEM_QUERY_OPTIMIZATION=true \ + releem/releem-agent:[version] + ``` + + Use the latest version of Releem Agent from [Docker Hub](https://hub.docker.com/r/releem/releem-agent/tags). + + **Docker Compose** + + ```yaml + version: '3.7' + services: + releem-agent: + image: releem/releem-agent:[version] + container_name: releem-agent + environment: + MEMORY_LIMIT: "${MEMORY_LIMIT}" + PG_USER: "releem" + RELEEM_API_KEY: "${RELEEM_API_KEY}" + PG_PASSWORD: "${PG_PASSWORD}" + PG_PORT: "${PG_PORT}" + PG_HOST: "${PG_HOST}" + RELEEM_QUERY_OPTIMIZATION: true + restart: unless-stopped + volumes: + - /tmp/.mysqlconfigurer/:/tmp/.mysqlconfigurer/ + - /etc/postgresql/releem.conf.d/:/etc/postgresql/releem.conf.d/ + ``` + + **Parameters:** + - `RELEEM_HOSTNAME` - Server hostname, which should be displayed in the Releem Dashboard. + - `RELEEM_API_KEY` - Releem API Key. Get it from the Profile page in the Releem Customer Portal. + - `PG_USER` / `RELEEM_PG_LOGIN` - PostgreSQL user name for data collection. + - `PG_PASSWORD` / `RELEEM_PG_PASSWORD` - PostgreSQL user password for data collection. + - `PG_HOST` / `RELEEM_PG_HOST` - PostgreSQL host for data collection. + - `PG_PORT` / `RELEEM_PG_PORT` - PostgreSQL port for data collection. Default value is `5432`. + - `PG_SSL` / `RELEEM_PG_SSL_MODE` - PostgreSQL SSL mode: `true` for `sslmode=require`, `false` (or omitted) for `sslmode=disable`. + - `MEMORY_LIMIT` - RAM limit allocated for PostgreSQL in megabytes. Set to system RAM or the limit for PostgreSQL. + - `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. + + PostgreSQL monitoring starts when `pg_user` and `pg_password` are set. Do not set MySQL `DB_USER` and `DB_PASSWORD` in the same container if you want the agent to use the PostgreSQL collector. + + **Volumes:** + - `/tmp/.mysqlconfigurer/` + - `/etc/postgresql/releem.conf.d/` + +3. To apply recommended PostgreSQL settings automatically, mount the Releem configuration directory into the PostgreSQL container and include it from `postgresql.conf`: + +```ini +include_dir = 'conf.d' +``` + +**Note:** If you do not configure automatic applying of configuration, add `pg_stat_statements` to `shared_preload_libraries` and create the extension in the monitored database. + + + + +# Cloud-Managed AWS RDS and Aurora PostgreSQL Installation + +Use this instruction to install Releem Agent automatically via CloudFormation to AWS Fargate, or manually on an EC2 instance. Releem Agent runs in a container on AWS Fargate or directly on the EC2 instance, depending on your choice. + +Releem supports Amazon RDS PostgreSQL and Amazon Aurora PostgreSQL. Configure one Agent for each DB instance endpoint. + +## Parameter groups + +To apply recommended configuration automatically, sign in to your AWS account and prepare custom parameter groups. AWS-managed default groups cannot be modified and are not valid onboarding targets. + +**Amazon RDS PostgreSQL (non-Aurora):** +- Create a custom DB parameter group for your PostgreSQL version, for example `releem-agent`. +- Attach it to the instance as **DB parameter group**. +- Leave the cluster parameter group empty. +- Reboot the instance if AWS requires it. + +**Amazon Aurora PostgreSQL:** +- Create a custom DB parameter group for the instance and a custom DB cluster parameter group for the cluster. +- Attach both groups in AWS. The names you configure for Releem must match the groups attached in AWS. +- Both groups must be ready before the Agent applies recommendations. A recommendation can target either group. +- Only the Agent that targets the writer modifies cluster parameters. That Agent needs `rds:ModifyDBClusterParameterGroup` permission. + +The requirements for the RDS or Aurora instance: +- Enhanced Monitoring to collect system performance metrics. +- Performance Insights to collect PostgreSQL performance metrics. +- `pg_stat_statements` in the instance or cluster parameter group, then reboot if AWS marks the change as pending reboot: + +```ini +shared_preload_libraries=pg_stat_statements +``` + +You have the following options to install Releem Agent: + + + + + CloudFormation deploys the Releem Agent container with AWS Fargate. The template creates roles with the following permissions: + - logs:Get* + - rds:Describe* + - cloudwatch:Get* + - ecr:GetAuthorizationToken + - ecr:BatchCheckLayerAvailability + - ecr:GetDownloadUrlForLayer + - ecr:BatchGetImage + - rds:ModifyDBParameterGroup + - rds:ModifyDBClusterParameterGroup + + 1. Create a monitoring user in PostgreSQL: + ```sql CREATE USER releem WITH PASSWORD '[Password]'; GRANT pg_monitor TO releem; - GRANT SELECT ON pg_hba_file_rules TO releem; - GRANT EXECUTE ON FUNCTION pg_hba_file_rules TO releem; ``` - Enable `pg_stat_statements` for query performance metrics: + Skip `GRANT` on `pg_hba_file_rules`: Aurora and RDS own that view with the internal `rdsadmin` role, and a customer monitoring role cannot read it. - Add the following line to `postgresql.conf`: - ```ini - shared_preload_libraries = 'pg_stat_statements' - ``` + To enable Automatic SQL Query Optimization, grant additional permissions: - - Add the following line to `pg_hba.conf` for local agent connections: - ```ini - host all releem 127.0.0.1/32 md5 + ```sql + -- PostgreSQL 14+ + GRANT pg_read_all_data TO releem; ``` - - Add the following line to `pg_hba.conf` for remote agent connections: - ```ini - host all releem 0.0.0.0/0 md5 - ``` + 2. Open the [CloudFormation Quick Create page](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateUrl=https://releem.s3.amazonaws.com/v2/releem-agent-cloudformation.yml&stackName=releem-agent) in your browser, check that the correct region is selected, and fill in the following fields: + - Image: Releem Agent Docker image in the `releem/releem-agent:[version]` format. Use the latest version available on [Docker Hub](https://hub.docker.com/r/releem/releem-agent/tags). + - APIKey: Releem API Key from the [Profile page](https://app.releem.com/profile?menu=profile) in the Releem Customer Portal. + - DBID: RDS DB Instance ID. For Aurora, set the instance name you want to monitor, not the cluster endpoint. Deploy one stack per instance. + - DatabaseType: set to `postgresql`. + - DBUser: User to collect metrics from PostgreSQL, created in step 1. + - DBPassword: Password for that user. + - DBSSLMode: set `true` when the instance requires SSL. + - SecurityGroupIDs: Security groups for Releem Agent. Allow all outbound traffic. + - SubnetIDs: Subnets from which the Releem Agent container can connect to RDS. + - QueryOptimization: set True if Releem Agent should collect additional information for Automatic SQL Query Optimization. + - DBParameterGroup: Custom DB parameter group attached to the instance. Required for RDS and Aurora instance parameters. + - DBClusterParameterGroup: Custom DB cluster parameter group attached to Aurora. Required for Aurora. Leave empty only for non-Aurora RDS. + + `DatabaseType` defaults to `mysql`. Select `postgresql` so the container receives PostgreSQL (`PG_*`) credentials and starts the PostgreSQL collector. + + 3. Click **Create Stack**. + + + + + Use this instruction to install Releem Agent on an EC2 instance to monitor AWS RDS or Aurora PostgreSQL. + + 1. Create a monitoring user in PostgreSQL: - Restart PostgreSQL, then create the extension in the database used by Releem Agent. The default database is `postgres`: ```sql - \c postgres - CREATE EXTENSION IF NOT EXISTS pg_stat_statements; + CREATE USER releem WITH PASSWORD '[Password]'; + GRANT pg_monitor TO releem; ``` -2. After the PostgreSQL user is created, run the Releem Agent installation command as a root user on the server: - ```bash - RELEEM_PG_PASSWORD='[Password]' RELEEM_PG_LOGIN='releem' RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" - ``` + To enable Automatic SQL Query Optimization, grant additional permissions as in the CloudFormation tab. - **Parameters:** - - `RELEEM_HOSTNAME` - Server hostname, which should display in the Releem Dashboard. - - `RELEEM_PG_LOGIN` - PostgreSQL user name for collecting metrics. - - `RELEEM_PG_PASSWORD` - PostgreSQL user password for collecting metrics. - - `RELEEM_DB_MEMORY_LIMIT` - Change parameter in case there are other software installed on the server. Default value is 0 means use all memory. - - `RELEEM_API_KEY` - API Key. Get it from Profile page in Releem Customer Portal. - - `RELEEM_PG_HOST` - use this variable in case PostgreSQL listens different interface or connection available only through socket. - - `RELEEM_PG_PORT` - use this variable in case PostgreSQL listens different port - - `RELEEM_PG_SSL_MODE` - PostgreSQL SSL mode for collector: `true` for SSL (`sslmode=require`), `false` (or omitted) for `sslmode=disable`. - - `RELEEM_QUERY_OPTIMIZATION` - set 'true' if Releem Agent should collect additional information for Automatic SQL Query Optimization. - - For a full list of configuration settings, please refer to the [Releem Agent Configuration](/releem-agent/configuration). + 2. Add IAM role `releem-agent-role` and apply it to the EC2 instance: -3. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. + ``` + { + "Version": "2012-10-17", + "Statement": [ + { + "Action": [ + "rds:Describe*", + "cloudwatch:Get*", + "logs:Get*", + "ec2:Describe*", + "rds:ModifyDBParameterGroup", + "rds:ModifyDBClusterParameterGroup" + ], + "Resource": "*", + "Effect": "Allow" + } + ] + } + ``` + + 3. Run the installation command as a root user on the server. + + **Amazon RDS PostgreSQL:** + + ```bash + RELEEM_INSTANCE_TYPE="aws/rds" RELEEM_PG_TYPE=1 RELEEM_AWS_REGION="[AwsRegion]" RELEEM_AWS_RDS_DB="[AwsRdsDBidentifier]" RELEEM_AWS_RDS_PARAMETER_GROUP="releem-agent" RELEEM_PG_PASSWORD='[Password]' RELEEM_PG_LOGIN='releem' RELEEM_PG_SSL_MODE=true RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 RELEEM_QUERY_OPTIMIZATION=true bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" + ``` + + **Amazon Aurora PostgreSQL:** add `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP` with the custom cluster parameter group name. Set `RELEEM_AWS_RDS_DB` to the instance identifier, not the cluster endpoint. Repeat the installation for each instance you want to monitor. Only the writer Agent applies cluster parameter recommendations. + + ```bash + RELEEM_INSTANCE_TYPE="aws/rds" RELEEM_PG_TYPE=1 RELEEM_AWS_REGION="[AwsRegion]" RELEEM_AWS_RDS_DB="[AwsRdsDBidentifier]" RELEEM_AWS_RDS_PARAMETER_GROUP="releem-agent" RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP="releem-agent-cluster" RELEEM_PG_PASSWORD='[Password]' RELEEM_PG_LOGIN='releem' RELEEM_PG_SSL_MODE=true RELEEM_DB_MEMORY_LIMIT=0 RELEEM_API_KEY=[Key] RELEEM_CRON_ENABLE=1 RELEEM_QUERY_OPTIMIZATION=true bash -c "$(curl -L https://releem.s3.amazonaws.com/v2/install.sh)" + ``` + + **Parameters:** + - `RELEEM_AWS_REGION` - AWS region name. + - `RELEEM_AWS_RDS_DB` - RDS or Aurora instance identifier. + - `RELEEM_AWS_RDS_PARAMETER_GROUP` - Custom DB parameter group name. Required. + - `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP` - Custom DB cluster parameter group name. Required for Aurora. Omit for non-Aurora RDS. + - `RELEEM_PG_LOGIN` - PostgreSQL user name to collect metrics. + - `RELEEM_PG_PASSWORD` - PostgreSQL user password to collect metrics. + - `RELEEM_PG_SSL_MODE` - set `true` when the instance requires SSL. + - `RELEEM_DB_MEMORY_LIMIT` - Change this parameter when other software is installed on the server. Default value is `0`. + - `RELEEM_API_KEY` - API Key. Get it from the Profile page in Releem Customer Portal. + - `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. + + + + + Use this instruction to run Releem Agent in a Docker container on EC2 against AWS RDS or Aurora PostgreSQL. + + 1. Create a monitoring user in PostgreSQL as in the EC2 tab. + + 2. Add IAM role `releem-agent-role` and apply it to the EC2 instance, including `rds:ModifyDBParameterGroup` and `rds:ModifyDBClusterParameterGroup`. + + 3. Run Releem Agent using Docker or Docker Compose. + + **Docker (Amazon RDS PostgreSQL)** + + ```bash + docker run -d -ti --name 'releem-agent' \ + -e RELEEM_API_KEY="[RELEEM_API_KEY]" \ + -e RELEEM_HOSTNAME="[RELEEM_HOSTNAME]" \ + -e PG_USER="releem" \ + -e PG_PASSWORD="[PG_PASSWORD]" \ + -e PG_SSL="true" \ + -e INSTANCE_TYPE="aws/rds" \ + -e AWS_REGION="[AWS_REGION]" \ + -e AWS_RDS_DB="[AWS_RDS_DB]" \ + -e AWS_RDS_PARAMETER_GROUP="releem-agent" \ + -e RELEEM_QUERY_OPTIMIZATION=true \ + releem/releem-agent:[version] + ``` + + For Aurora PostgreSQL, add `-e AWS_RDS_CLUSTER_PARAMETER_GROUP="releem-agent-cluster"` (or `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP`). Run one container per instance. Only the writer container applies cluster parameter recommendations. + + **Docker Compose** + + ```yaml + version: '3.7' + + x-common-service: &common-service + image: releem/releem-agent:[version] + restart: unless-stopped + + services: + releem-agent-1: + <<: *common-service + container_name: releem-agent-1 + environment: + RELEEM_API_KEY: "[RELEEM_API_KEY]" + RELEEM_HOSTNAME: "[RELEEM_HOSTNAME]" + PG_USER: "releem" + PG_PASSWORD: "[PG_PASSWORD]" + PG_SSL: "true" + INSTANCE_TYPE: "aws/rds" + AWS_REGION: "[AWS_REGION]" + AWS_RDS_DB: "[AWS_RDS_DB]" + AWS_RDS_PARAMETER_GROUP: "releem-agent" + AWS_RDS_CLUSTER_PARAMETER_GROUP: "releem-agent-cluster" + RELEEM_QUERY_OPTIMIZATION: true + ``` + + Leave `AWS_RDS_CLUSTER_PARAMETER_GROUP` empty or omit it for non-Aurora RDS. + + ***Parameters:*** + - `RELEEM_API_KEY`: API Key. Get it from the Profile page in Releem Customer Portal. + - `RELEEM_HOSTNAME` - Server hostname, which should display in the Releem Dashboard. + - `PG_USER`: PostgreSQL user name to collect metrics. + - `PG_PASSWORD`: PostgreSQL user password to collect metrics. + - `PG_SSL`: set `true` when the instance requires SSL. + - `AWS_REGION`: AWS region name. + - `AWS_RDS_DB`: RDS or Aurora instance identifier. + - `AWS_RDS_PARAMETER_GROUP`: Custom DB parameter group name. Required. + - `AWS_RDS_CLUSTER_PARAMETER_GROUP` / `RELEEM_AWS_RDS_CLUSTER_PARAMETER_GROUP`: Custom DB cluster parameter group name. Required for Aurora. + - `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. + + Use the latest version of Releem Agent from [Docker Hub](https://hub.docker.com/r/releem/releem-agent/tags). + + + + +## Common Issues for AWS RDS and Aurora PostgreSQL + +To check Releem Agent logs, open CloudWatch → Log Groups and select the Releem Agent log group. + +1. Failed to read log stream `%s:%s: %s` RDSOSMetrics + - Enable Enhanced Monitoring for your RDS or Aurora instance. + +2. No Latency graph on Releem Dashboard + - Enable Performance Insights for your instance. + +3. PostgreSQL connection failed / password authentication failed + - Check the password for the Releem user and that the security group allows inbound PostgreSQL traffic from the Agent. + +4. Connect: connection timed out + - Check that the RDS or Aurora security group has an inbound rule for connections from Releem Agent. + +5. CloudFormation stack is not finished, still "in progress" for a long time + - Enable Performance Insights and Enhanced Monitoring. + - Check that the security group for Releem Agent allows all outbound traffic. + - Confirm `DatabaseType` is `postgresql` and that `DBParameterGroup` matches the attached instance group. + +6. Aurora apply fails because the cluster parameter group is missing or does not match + - Create a custom DB cluster parameter group, attach it to the cluster, and set `DBClusterParameterGroup` / `AWS_RDS_CLUSTER_PARAMETER_GROUP` to that exact name. + - AWS-managed default groups cannot be modified. + +7. Cluster parameters are not applied on a reader + - Only the Agent targeting the writer modifies cluster parameters. Keep an Agent on the writer instance. @@ -113,3 +497,4 @@ Create the PostgreSQL monitoring user before running the Releem Agent installati - PostgreSQL support is enabled when `pg_user` and `pg_password` are set in the agent configuration. - `pg_stat_statements` is recommended for query performance visibility. - `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. +- On Amazon RDS and Aurora PostgreSQL, `pg_hba_file_rules` is owned by `rdsadmin` and cannot be granted to a customer monitoring role. Skip those grants and use the [RDS](/releem-agent/installation-guides/postgresql-aws-rds) guide instead. From a59cef560c96fe3dbe08000a1ae7d2ea50e9cba0 Mon Sep 17 00:00:00 2001 From: Dmitry Kochetov Date: Mon, 31 Aug 2026 18:00:34 +0400 Subject: [PATCH 2/3] Fix MDX TabItem nesting so the PostgreSQL install page builds. Indented closing tags were parsed as list items; also point leftover links at the existing PostgreSQL guide. Co-authored-by: Cursor --- ...how-to-check-if-releem-agent-is-working.md | 2 +- docs/getting-started/step-2-add-server.md | 6 ++-- ...-managed-aws-rds-automatic-installation.md | 12 ++++---- .../postgresql-manual-installation-linux.md | 30 +++++++++---------- 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/getting-started/how-to-check-if-releem-agent-is-working.md b/docs/getting-started/how-to-check-if-releem-agent-is-working.md index 84b5206..4b9f5d9 100644 --- a/docs/getting-started/how-to-check-if-releem-agent-is-working.md +++ b/docs/getting-started/how-to-check-if-releem-agent-is-working.md @@ -51,7 +51,7 @@ If your server is managed through WHM/cPanel, use the [WHM/cPanel installation g ### AWS RDS [Common issues for AWS RDS MySQL and Aurora MySQL](/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation#common-issues-for-aws-rds) -[Common issues for AWS RDS PostgreSQL and Aurora PostgreSQL](/releem-agent/installation-guides/postgresql-aws-rds#common-issues-for-aws-rds-and-aurora-postgresql) +[Common issues for AWS RDS PostgreSQL and Aurora PostgreSQL](/releem-agent/installation-guides/postgresql-manual-linux#common-issues-for-aws-rds-and-aurora-postgresql) ## Releem Agent Installation Errors diff --git a/docs/getting-started/step-2-add-server.md b/docs/getting-started/step-2-add-server.md index acc3451..4465403 100644 --- a/docs/getting-started/step-2-add-server.md +++ b/docs/getting-started/step-2-add-server.md @@ -16,10 +16,10 @@ Click the "Add Server" button to start the setup process. Choose the type of database server you are adding: - [MySQL on Linux Server: Automatic Agent Installation (Linux)](/releem-agent/installation-guides/self-managed-servers-automatic-installation) – Automatic installation for MySQL instances running on Linux-based servers. - [MySQL on Linux Server: Advanced Agent Installation](/releem-agent/installation-guides/self-managed-servers-manual-installation-linux) – Manual installation for MySQL instances running on Linux-based servers. Use this guide if you don't have a MySQL root user, or if MySQL is installed on a different IP address, or if you want to create a Releem user manually. -- [PostgreSQL on Linux Server: Automatic Agent Installation](/releem-agent/installation-guides/postgresql-automatic-installation) – Automatic installation for PostgreSQL instances running on Linux-based servers. +- [PostgreSQL on Linux Server: Automatic Agent Installation](/releem-agent/installation-guides/postgresql-manual-linux) – Automatic installation for PostgreSQL instances running on Linux-based servers. - [PostgreSQL on Linux Server: Manual Agent Installation](/releem-agent/installation-guides/postgresql-manual-linux) – Manual installation for PostgreSQL instances running on Linux-based servers. -- [PostgreSQL in Docker](/releem-agent/installation-guides/postgresql-docker-installation) – Manual installation for PostgreSQL instances running in Docker containers. -- [PostgreSQL on AWS RDS and Aurora](/releem-agent/installation-guides/postgresql-aws-rds) – For managed PostgreSQL databases hosted on Amazon RDS or Aurora. +- [PostgreSQL in Docker](/releem-agent/installation-guides/postgresql-manual-linux) – Manual installation for PostgreSQL instances running in Docker containers. +- [PostgreSQL on AWS RDS and Aurora](/releem-agent/installation-guides/postgresql-manual-linux) – For managed PostgreSQL databases hosted on Amazon RDS or Aurora. - [WHM/cPanel](/releem-agent/installation-guides/whm-cpanel) – Recommended installation path for database servers managed through WHM/cPanel. - [MySQL on Linux Server: Manual Installation in Docker](/releem-agent/installation-guides/self-managed-servers-docker-installation) – Manual installation for MySQL instances running in Docker containers. - [Self-Managed Server (Windows)](/releem-agent/installation-guides/self-managed-servers-manual-installation-windows) – For MySQL instances running on Windows. diff --git a/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md b/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md index 59be7f9..d8f07ee 100644 --- a/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md +++ b/docs/releem-agent/installation-guides/cloud-managed-aws-rds-automatic-installation.md @@ -70,12 +70,12 @@ You have the following options to install Releem Agent: - DBParameterGroup: Custom DB parameter group attached to the instance. Required for RDS and Aurora instance parameters. - DBClusterParameterGroup: Custom DB cluster parameter group attached to Aurora. Required for Aurora. Leave empty only for non-Aurora RDS. - `DatabaseType` defaults to `mysql` and exposes MySQL (`DB_*`) credentials to the container. Select `postgresql` only for Aurora PostgreSQL; see [PostgreSQL RDS](/releem-agent/installation-guides/postgresql-aws-rds). + `DatabaseType` defaults to `mysql` and exposes MySQL (`DB_*`) credentials to the container. Select `postgresql` only for Aurora PostgreSQL; see [PostgreSQL](/releem-agent/installation-guides/postgresql-manual-linux). 3. Next, click "Create Stack". - - + + Use this instruction to install Releem Agent manually on the EC2 instance to tune AWS RDS. Releem Agent will automatically collect metrics and recommend configuration. To move forward just do the following steps: @@ -128,8 +128,8 @@ You have the following options to install Releem Agent: - `RELEEM_QUERY_OPTIMIZATION` - set 'true' if Releem Agent should collect additional information for Automatic SQL Query Optimization. - - + + Use this instruction to install Releem Agent manually on the EC2 instance in Docker container to tune AWS RDS. Releem Agent will automatically collect metrics and recommend configuration. To move forward just do the following steps: @@ -233,7 +233,7 @@ You have the following options to install Releem Agent: Please use the latest version of Releem Agent. You can find the latest version of Releem Agent by clicking on the [link](https://hub.docker.com/r/releem/releem-agent/tags). - + diff --git a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md index 18ff613..fe9428f 100644 --- a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md +++ b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md @@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; Choose the installation flow that matches your setup: - + # Automatic Installation for Self-Managed PostgreSQL Servers @@ -61,8 +61,8 @@ For a full list of configuration settings, see [Releem Agent Configuration](/rel - `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. - If you prefer to create the monitoring user yourself, use the [Manual](/releem-agent/installation-guides/postgresql-manual-linux) installation. - - + + # Manual Installation for Self-Managed PostgreSQL Servers @@ -149,8 +149,8 @@ For a full list of configuration settings, see [Releem Agent Configuration](/rel 3. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. - - + + # Installation in a Docker Container on Self-Managed PostgreSQL Servers @@ -239,8 +239,8 @@ include_dir = 'conf.d' **Note:** If you do not configure automatic applying of configuration, add `pg_stat_statements` to `shared_preload_libraries` and create the extension in the monitored database. - - + + # Cloud-Managed AWS RDS and Aurora PostgreSQL Installation @@ -276,7 +276,7 @@ shared_preload_libraries=pg_stat_statements You have the following options to install Releem Agent: - + CloudFormation deploys the Releem Agent container with AWS Fargate. The template creates roles with the following permissions: - logs:Get* @@ -323,8 +323,8 @@ You have the following options to install Releem Agent: 3. Click **Create Stack**. - - + + Use this instruction to install Releem Agent on an EC2 instance to monitor AWS RDS or Aurora PostgreSQL. @@ -385,8 +385,8 @@ You have the following options to install Releem Agent: - `RELEEM_API_KEY` - API Key. Get it from the Profile page in Releem Customer Portal. - `RELEEM_QUERY_OPTIMIZATION` - set `true` if Releem Agent should collect additional information for Automatic SQL Query Optimization. - - + + Use this instruction to run Releem Agent in a Docker container on EC2 against AWS RDS or Aurora PostgreSQL. @@ -458,7 +458,7 @@ You have the following options to install Releem Agent: Use the latest version of Releem Agent from [Docker Hub](https://hub.docker.com/r/releem/releem-agent/tags). - + ## Common Issues for AWS RDS and Aurora PostgreSQL @@ -489,7 +489,7 @@ To check Releem Agent logs, open CloudWatch → Log Groups and select the Releem 7. Cluster parameters are not applied on a reader - Only the Agent targeting the writer modifies cluster parameters. Keep an Agent on the writer instance. - + ## Notes @@ -497,4 +497,4 @@ To check Releem Agent logs, open CloudWatch → Log Groups and select the Releem - PostgreSQL support is enabled when `pg_user` and `pg_password` are set in the agent configuration. - `pg_stat_statements` is recommended for query performance visibility. - `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. -- On Amazon RDS and Aurora PostgreSQL, `pg_hba_file_rules` is owned by `rdsadmin` and cannot be granted to a customer monitoring role. Skip those grants and use the [RDS](/releem-agent/installation-guides/postgresql-aws-rds) guide instead. +- On Amazon RDS and Aurora PostgreSQL, `pg_hba_file_rules` is owned by `rdsadmin` and cannot be granted to a customer monitoring role. Skip those grants and use the AWS RDS tab above. From 836cb44497834378f474b9ada2fb4c94cff3e30b Mon Sep 17 00:00:00 2001 From: Dmitry Kochetov Date: Mon, 7 Sep 2026 13:59:54 +0400 Subject: [PATCH 3/3] Move PostgreSQL RDS common issues out of the install tabs. Keep installation headings as page sections so Common Issues can be linked directly. Co-authored-by: Cursor --- .../postgresql-manual-installation-linux.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md index fe9428f..9a03b5f 100644 --- a/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md +++ b/docs/releem-agent/installation-guides/postgresql-manual-installation-linux.md @@ -14,7 +14,7 @@ Choose the installation flow that matches your setup: -# Automatic Installation for Self-Managed PostgreSQL Servers +## Automatic Installation for Self-Managed PostgreSQL Servers Use this instruction to install Releem Agent automatically on a self-managed PostgreSQL server. The installer creates the monitoring user, enables `pg_stat_statements` when possible, and starts metrics collection. @@ -55,16 +55,10 @@ For a full list of configuration settings, see [Releem Agent Configuration](/rel 3. Open the [Releem Dashboard](https://app.releem.com/). If the server does not appear immediately, refresh the page. -## Notes - -- PostgreSQL support is enabled when `pg_user` and `pg_password` are set in the agent configuration. -- `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. -- If you prefer to create the monitoring user yourself, use the [Manual](/releem-agent/installation-guides/postgresql-manual-linux) installation. - -# Manual Installation for Self-Managed PostgreSQL Servers +## Manual Installation for Self-Managed PostgreSQL Servers Use this instruction to install Releem Agent after you create the PostgreSQL monitoring user yourself. @@ -152,7 +146,7 @@ For a full list of configuration settings, see [Releem Agent Configuration](/rel -# Installation in a Docker Container on Self-Managed PostgreSQL Servers +## Installation in a Docker Container on Self-Managed PostgreSQL Servers Use this instruction to run Releem Agent in a Docker container against a self-managed PostgreSQL server. Releem Agent collects metrics and recommends configuration. @@ -242,7 +236,7 @@ include_dir = 'conf.d' -# Cloud-Managed AWS RDS and Aurora PostgreSQL Installation +## Cloud-Managed AWS RDS and Aurora PostgreSQL Installation Use this instruction to install Releem Agent automatically via CloudFormation to AWS Fargate, or manually on an EC2 instance. Releem Agent runs in a container on AWS Fargate or directly on the EC2 instance, depending on your choice. @@ -461,6 +455,9 @@ You have the following options to install Releem Agent: + + + ## Common Issues for AWS RDS and Aurora PostgreSQL To check Releem Agent logs, open CloudWatch → Log Groups and select the Releem Agent log group. @@ -489,12 +486,10 @@ To check Releem Agent logs, open CloudWatch → Log Groups and select the Releem 7. Cluster parameters are not applied on a reader - Only the Agent targeting the writer modifies cluster parameters. Keep an Agent on the writer instance. - - - ## Notes - PostgreSQL support is enabled when `pg_user` and `pg_password` are set in the agent configuration. - `pg_stat_statements` is recommended for query performance visibility. - `pg_ssl_mode` in `releem.conf` is a boolean: `true` means `sslmode=require`, omitted/false means `sslmode=disable`. - On Amazon RDS and Aurora PostgreSQL, `pg_hba_file_rules` is owned by `rdsadmin` and cannot be granted to a customer monitoring role. Skip those grants and use the AWS RDS tab above. +- If you prefer to create the monitoring user yourself, use the [Manual](/releem-agent/installation-guides/postgresql-manual-linux) installation.