Are you ready to take your AWS RDS monitoring to the next level? Say hello to prometheus-rds-exporter, your ultimate solution for comprehensive, real-time insights into your Amazon RDS instances!

Built by SRE Engineers, designed for production: Meticulously crafted by a team of Site Reliability Engineers with years of hands-on experience in managing RDS production systems. Trust in their expertise to supercharge your monitoring.

It collects key metrics about:

• Hardware resource usage
• Underlying EC2 instance's hard limits
• Pending AWS RDS maintenance operations
• Pending modifications
• Logs size
• RDS quota usage information

🥇 Advanced Metrics: Gain deep visibility with advanced metrics for AWS RDS. Monitor performance, query efficiency, and resource utilization like never before.

🧩 AWS Quotas Insights: Stay in control with real-time information about AWS quotas. Ensure you never hit limits unexpectedly.

💡 Hard Limits visibility: Know the hard limits of the EC2 instance used by RDS and manage your resources effectively.

🔔 Alerting at Your Fingertips: Easily set up Prometheus alerting rules to stay informed of critical events, ensuring you're always ahead of issues.

🛠️ Simple Setup: Getting started is a breeze! Our clear documentation and examples will have you up and running in no time.

📊 Dashboards: Prometheus-RDS Exporter export adopts the USE methodology and provides well-designed, ready-to-use dashboards.

🌐 Community-Driven: Join a vibrant community of users and contributors. Collaborate, share knowledge, and shape the future of AWS RDS monitoring together.

🚀 When combined with prometheus-community/postgres_exporter, it provides a production-ready monitoring framework for RDS PostgreSQL.

For convenience, dashboards are also available in configs/grafana/public/ folder and Grafana labs:

Configuration could be defined in prometheus-rds-exporter.yaml or environment variables (format PROMETHEUS_RDS_EXPORTER_<PARAMETER_NAME>).

Configuration parameters priorities:

1. $HOME/prometheus-rds-exporter.yaml file
2. prometheus-rds-exporter.yaml file
3. Environment variables
4. Command line flags

Prometheus RDS exporter needs read-only AWS IAM permissions to fetch metrics from AWS RDS, CloudWatch, EC2 and ServiceQuota AWS APIs.

Standard AWS authentication methods (AWS credentials, SSO and assumed role) are supported, see https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html.

If you are running on AWS EKS, we strongly recommend to use IRSA

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowInstanceAndLogDescriptions",
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
                "rds:DescribeDBLogFiles"
            ],
            "Resource": [
                "arn:aws:rds:*:*:db:*"
            ]
        },
        {
            "Sid": "AllowMaintenanceDescriptions",
            "Effect": "Allow",
            "Action": [
                "rds:DescribePendingMaintenanceActions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowGettingCloudWatchMetrics",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricData"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowRDSUsageDescriptions",
            "Effect": "Allow",
            "Action": [
                "rds:DescribeAccountAttributes"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowQuotaDescriptions",
            "Effect": "Allow",
            "Action": [
                "servicequotas:GetServiceQuota"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowInstanceTypeDescriptions",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstanceTypes"
            ],
            "Resource": "*"
        }
    ]
}

curl \
--fail \
--silent \
--write-out "Reponse code: %{response_code}\n" \
https://raw.githubusercontent.com/qonto/prometheus-rds-exporter/main/configs/aws/policy.json \
-o /tmp/prometheus-rds-exporter.policy.json

We recommend deployment using helm Helm.

See all available configuration parameters in configs/helm/values.yaml

See the Development environment to start the Prometheus RDS exporter, Prometheus, and Grafana with dashboards in a minute.

Recommended method to deploy on AWS EKS using IRSA and Helm.

1. Create an IAM policy

   IAM_POLICY_NAME=prometheus-rds-exporter
   
   # Download policy payload
   curl --fail --silent --write-out "Reponse code: %{response_code}\n" https://raw.githubusercontent.com/qonto/prometheus-rds-exporter/main/configs/aws/policy.json -o /tmp/prometheus-rds-exporter.policy.json
   
   # Create IAM policy
   aws iam create-policy --policy-name ${IAM_POLICY_NAME} --policy-document file:///tmp/prometheus-rds-exporter.policy.json

2. Create and attach an IAM role to your EKS cluster

   eksctl will create an IAM role and a Kubernetes Service account

   EKS_CLUSTER_NAME=default # Replace with your EKS cluster name
   KUBERNETES_NAMESPACE=monitoring # Replace with namespace of your choice
   
   IAM_ROLE_NAME=prometheus-rds-exporter
   KUBERNETES_SERVICE_ACCOUNT_NAME=prometheus-rds-exporter
   AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
   
   eksctl \
   create iamserviceaccount \
   --cluster ${EKS_CLUSTER_NAME} \
   --namespace ${KUBERNETES_NAMESPACE} \
   --name ${KUBERNETES_SERVICE_ACCOUNT_NAME} \
   --role-name ${IAM_ROLE_NAME} \
   --attach-policy-arn arn:aws:iam::${AWS_ACCOUNT_ID}:policy/${IAM_POLICY_NAME} \
   --approve

3. Deploy the exporter

   PROMETHEUS_RDS_EXPORTER_VERSION=0.3.0 # Replace with latest version
   SERVICE_ACCOUNT_ANNOTATION="arn:aws:iam::${AWS_ACCOUNT_ID}:role/${IAM_ROLE_NAME}"
   
   helm upgrade \
   prometheus-rds-exporter \
   oci://public.ecr.aws/qonto/prometheus-rds-exporter-chart \
   --version ${PROMETHEUS_RDS_EXPORTER_VERSION} \
   --install \
   --namespace ${KUBERNETES_NAMESPACE} \
   --set serviceAccount.annotations."eks\.amazonaws\.com\/role-arn"="${SERVICE_ACCOUNT_ANNOTATION}"

4. Option. Customize Prometheus exporter settings

   Download Helm chart default values

   helm show values oci://public.ecr.aws/qonto/prometheus-rds-exporter-chart --version ${PROMETHEUS_RDS_EXPORTER_VERSION} > values.yaml

   Customize settings

   vim values.yaml

   Example to enable debug via PROMETHEUS_RDS_EXPORTER_DEBUG environment variable

   yq --inplace '.env += {"PROMETHEUS_RDS_EXPORTER_DEBUG": "true"}' values.yaml

   Update Helm deployment:

   helm upgrade \
   prometheus-rds-exporter \
   oci://public.ecr.aws/qonto/prometheus-rds-exporter-chart \
   --version ${PROMETHEUS_RDS_EXPORTER_VERSION} \
   --install \
   --namespace ${KUBERNETES_NAMESPACE} \
   --set serviceAccount.annotations."eks\.amazonaws\.com\/role-arn"="${SERVICE_ACCOUNT_ANNOTATION}" \
   --values values.yaml

1. Grant IAM permissions to the EC2 instance

   See steps

   1. Create IAM role

      IAM_ROLE_NAME=prometheus-rds-exporter
      
      cat > ec2-role-trust-policy.json << EOF
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": { "Service": "ec2.amazonaws.com"},
                  "Action": "sts:AssumeRole"
              }
          ]
      }
      EOF
      
      aws iam create-role --role-name ${IAM_ROLE_NAME} --assume-role-policy-document file://ec2-role-trust-policy.json

   2. Create IAM policy

      IAM_POLICY_NAME=prometheus-rds-exporter
      
      # Download Prometheus RDS exporter required IAM permissions
      curl --fail --silent --write-out "Reponse code: %{response_code}\n" https://raw.githubusercontent.com/qonto/prometheus-rds-exporter/main/configs/aws/policy.json -o prometheus-rds-exporter.policy.json
      
      # Create IAM policy
      aws iam create-policy --policy-name ${IAM_POLICY_NAME} --policy-document file://prometheus-rds-exporter.policy.json
      
      # Attach IAM policy to IAM role
      AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
      IAM_POLICY_ARN=arn:aws:iam::${AWS_ACCOUNT_ID}:policy/${IAM_POLICY_NAME}
      aws iam attach-role-policy --role-name ${IAM_ROLE_NAME} --policy-arn ${IAM_POLICY_ARN}

   3. Create an IAM instance profile

      EC2_INSTANCE_PROFILE_NAME="prometheus-rds-exporter"
      
      # Create IAM instance profile
      aws iam create-instance-profile --instance-profile-name ${EC2_INSTANCE_PROFILE_NAME}
      
      # Attach IAM role to IAM instance profile
      aws iam add-role-to-instance-profile  --instance-profile-name ${EC2_INSTANCE_PROFILE_NAME} --role-name ${IAM_ROLE_NAME}

   4. Attach the IAM instance profile to the EC2 instance

      EC2_INSTANCE_ID="i-1234567890abcdef0" # Replace with your AWS instance ID
      
      aws ec2 associate-iam-instance-profile \
      --instance-id ${EC2_INSTANCE_ID} \
      --iam-instance-profile Name="${EC2_INSTANCE_PROFILE_NAME}"

2. Download the Debian package

   PROMETHEUS_RDS_EXPORTER_VERSION=0.3.0 # Replace with latest version
   
   PACKAGE_NAME=prometheus-rds-exporter_${PROMETHEUS_RDS_EXPORTER_VERSION}_$(uname -m).deb
   wget https://github.com/qonto/prometheus-rds-exporter/releases/download/${PROMETHEUS_RDS_EXPORTER_VERSION}/${PACKAGE_NAME}

3. Install package

   Prometheus RDS exporter will be automatically started as a service.

   dpkg -i ${PACKAGE_NAME}

4. Optional, customize configuration

   # Copy configuration template
   cp /usr/share/prometheus-rds-exporter/prometheus-rds-exporter.yaml.sample /var/lib/prometheus-rds-exporter/prometheus-rds-exporter.yaml
   
   # Edit configuration
   vim /var/lib/prometheus-rds-exporter/prometheus-rds-exporter.yaml
   
   # Restart service
   systemctl restart prometheus-rds-exporter

1. Binary

   PROMETHEUS_RDS_EXPORTER_VERSION=0.3.0 # Replace with latest version
   TARBALL_NAME=prometheus-rds-exporter_Linux_$(uname -m).tar.gz
   
   wget https://github.com/qonto/prometheus-rds-exporter/releases/download/${PROMETHEUS_RDS_EXPORTER_VERSION}/${TARBALL_NAME}
   tar xvzf ${TARBALL_NAME}

2. Optional, customize configuration

   vim prometheus-rds-exporter.yaml

3. Start the exporter

   ./prometheus-rds-exporter

1. Connect on AWS with any method

   aws configure

2. Start application

   docker run -p 9043:9043 -e AWS_PROFILE=${AWS_PROFILE} -v $HOME/.aws:/app/.aws public.ecr.aws/qonto/prometheus-rds-exporter:latest

percona/rds_exporter and mtanda/rds_enhanced_monitoring_exporter are great alternatives.

prometheus/cloudwatch_exporter could be used to collect additional CloudWatch metrics.

See CONTRIBUTING.md.

To report a security issue, please visit SECURITY.md

You can start a simple development environment using the Docker compose configuration in /scripts/prometheus.

It will start Grafana (with the dashboards), Prometheus, and the RDS exporter:

1. Connect on AWS using the AWS CLI

2. Launch development stack

   cd scripts/prometheus
   docker compose up --build

3. Connect on the services

   • Grafana: http://localhost:3000 (credential: admin/hackme)
   • Prometheus: http://localhost:9090
   • Prometheus RDS exporter: http://localhost:9043

Execute Go tests:

make test

Execute Helm chart tests:

make helm-test # Helm unit test
make kubeconform # Kubernetes manifest validation
make checkcov # Check misconfigurations

Prometheus RDS Exporter includes an OpenTelemetry trace exporter to facilitate troubleshooting.

Traces can be forwarded to any OpenTelemetry server using gRPC protocol.

1. Export the OTEL_EXPORTER_OTLP_ENDPOINT variable.

   export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

   See OTEL SDK configuration and OpenTelemetry environments variables for all options.

2. Start exporter with OpenTelemetry enabled

   prometheus-rds-exporter --enable-otel-traces