Cloud Agent Configuration

This guide explains how to configure the WhaTap Cloud Agent in AWS and NCP environments. It covers key settings, field descriptions, role configuration, and execution commands.

Agent CONFIG.

The following explains how to configure the AWS Aurora and RDS, and NCP Cloud DB for PostgreSQL.

Configure AWS Aurora and RDS

config.yaml
input:
  csp: "aws" # Enter the Cloud Service Provider.
  namespace: "rds"
  region: "us-east-1" # Set the region where the instance is located.
  # assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly" # (Optional) Default role for all AWS calls. If omitted, the EC2 Instance Profile role is used.
  instances: # The specified instances are collected always. Instances listed under this property are collected at all times, regardless of the autoscaling setting.
    - name: "mysql-rds"
      slow_query: true # To use the slow query page, set it to true. Supported for MySQL, MariaDB, and PostgreSQL instances (including Aurora).
  slow_query: false # Whether to collect slow queries for instances automatically discovered from clusters.
  clusters:
    autoscale:
      enabled: false # If the autoscale is enabled, the autoscaled instances are added or deleted for collection.
      interval: 60 # Autoscale checking cycle for the specified clusters (unit: second)
    names:
      - "database-cluster-name"
  # metrics_interval: 1m # (Optional) Metric collection interval. Choose from 1m, 5m, 15m, or 1h; the unit is required. (Default: 1m)
  metrics: # Enter the metrics to collect.
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "ReadIOPS"
    - "WriteIOPS"
    - "NetworkReceiveThroughput"
    - "NetworkTransmitThroughput"
    - "FreeLocalStorage"
  logs:
    enabled: false # Can be enabled/disabled. Select true/false.
    groups: # Add the desired AWS log groups.
      - "/aws/rds/cluster/database-cluster-name/error"
      - "/aws/lambda/MyLambda"
  events:
    enabled: false # Set to true to enable RDS event collection.

output: # Enter the WhaTap information to receive the collected metrics.
  license: "abcdefg-higjgkgjk-zxcvnbnbmc"
  host: "127.0.0.1"

Field	Description
`csp`	Indicates `aws` (Amazon Web Services) as a cloud service provider.
`namespace`	Namespace of the service to be collected - Fixed value: Enter `rds` when configuring Aurora and RDS.
`region`	AWS Region code - e.g. `us-east-1` (Virginia Region)
`assume_role_arn`	(Optional) Default IAM Role ARN the agent uses to call AWS APIs - If omitted, the EC2 Instance Profile role is used. - Format: `arn:aws:iam::<12-digit account ID>:role/<name>` - Note. Agent default role
`instances`	It always collects the specified instances regardless of whether they are auto-scaled, as long as they are in the list of instances to collect.
`instances[].name`	RDS InstanceName - e.g. `mysql-rds`
`instances[].slow_query`	Whether to collect slow queries for the instance. Supported for MySQL, MariaDB, PostgreSQL, Aurora MySQL, and Aurora PostgreSQL instances. - `true`: To be collected - `false`: Not to be collected - Slow query logs must be exported to CloudWatch Logs (`slowquery` log for MySQL-family, `postgresql` log for PostgreSQL-family).
`instances[].oname`	(Optional) Instance name (oname) displayed on the WhaTap screen - If omitted, it is generated automatically from the endpoint.
`slow_query`	Whether to collect slow queries for instances automatically discovered from clusters (`clusters`) - Default: `false` - Cluster member instances follow this value, not `instances[].slow_query`.
`clusters`	RDS Cluster-related settings
`clusters.autoscale.enabled`	Whether to collect cluster autoscale - `true`: Automatically add/remove/collect instances - `false`: Only the instances directly entered in `instances` are included in the collection targets.
`clusters.autoscale.interval`	Polling interval for detecting autoscaling status (unit: second) - Default: `300`
`clusters.names`	List of cluster names to check for autoscaling status
`metrics`	List of metrics to collect - e.g. `CPUUtilization`, `FreeStorageSpace`, etc - Note. Shortcut to the official Amazon CloudWatch Metrics documentation for Amazon RDS
`metrics_interval`	(Optional) Metric collection interval - Allowed values: `1m`, `5m`, `15m`, `1h` (default: `1m`) - The unit is required. If you enter any other value, the agent does not start.
`logs.enabled`	Whether to collect CloudWatch Logs
`logs.groups`	List of CloudWatch Logs log groups to collect - Note. Log collection settings
`events.enabled`	(Optional) Whether to collect RDS events - Default: `false` - Requires the `rds:DescribeEvents` permission.
`output.license`	WhaTap's license key to transmit the collected data
`output.host`	WhaTap server host address (IP) to transmit the collected data to

Agent default role (`input.assume_role_arn`)

If you set input.assume_role_arn, the agent calls AWS APIs with the specified role instead of the EC2 Instance Profile role. Even when you monitor only a single account, you can keep the EC2 role at minimum privileges and manage the read permissions for WhaTap collection in a dedicated role. It works with both clusters.names and clusters.account_configs.

config.yaml
input:
  csp: "aws"
  namespace: "rds"
  region: "ap-northeast-2"
  assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly"
  clusters:
    names:
      - "database-cluster-name"

Role priority

clusters.account_configs[].assume_role_arn > input.assume_role_arn > EC2 Instance Profile default credentials

Scope of the role

Instance discovery, metrics, cluster specs, slow queries, logs (logs.groups), and RDS event collection all call AWS APIs with the role determined by the priority above.

Instance discovery, metrics, cluster specs, and slow queries use the role of the account_configs entry the instance belongs to. If the entry has no role, input.assume_role_arn is used.
logs.groups and RDS events are not tied to a specific cluster, so they always use the agent default role (input.assume_role_arn, or the EC2 role if not set). Setting only the account_configs role does not change the role used to query logs.groups.
When you use input.assume_role_arn, the EC2 Instance Profile needs only the sts:AssumeRole permission. Grant the permissions required for collection to the specified role. For details, see Cross-account IAM permissions under Role setting below.
Temporary credentials obtained through AssumeRole are reused until they expire, so STS is not called on every request.

Caution

input.assume_role_arn is available only with csp: "aws". Setting it for any other csp causes a configuration error at agent startup.
The ARN format is validated. If it does not match arn:aws:iam::<12-digit account ID>:role/<name>, a configuration error occurs.
This setting is supported in DBXC agent 0.7.0 or later.

Cross-account monitoring (multi AWS account)

A single cloud agent can monitor RDS/DocumentDB across multiple AWS accounts. When using multiple accounts (separate by environment, partner accounts, etc.), you do not need to install an agent per account. One agent uses STS AssumeRole to query resources in other accounts.

Item	Description
Supported targets	AWS RDS (Aurora, standalone), DocumentDB
Authentication method	EC2 Instance Profile (or `input.assume_role_arn`) + STS AssumeRole

Choosing a configuration method

There are two methods for cluster configuration, and they cannot be used simultaneously.

names: Single-account only (queries only its own account using the agent default role; if input.assume_role_arn is not set, the IAM Role of the EC2 where the agent is installed is used)
account_configs: Cross-account support (queries multiple accounts via STS AssumeRole)

`account_configs` configuration

config.yaml
input:
  csp: "aws"
  namespace: "rds"
  region: "ap-northeast-2"
  clusters:
    autoscale:
      enabled: true
      interval: 300
    account_configs:
      # Local account (if assume_role_arn is omitted, input.assume_role_arn is used, or the EC2 role if that is also not set)
      - clusters: ["local-aurora-cluster"]
        instances: ["standalone-mysql-1"]

      # Another account A
      - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
        clusters: ["partner-cluster-1", "partner-cluster-2"]

      # Another account B
      - assume_role_arn: "arn:aws:iam::222222222222:role/QARole"
        clusters: ["qa-cluster"]
        instances: ["qa-standalone-pg"]
  metrics:
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"

output:
  license: "your-license-key"
  host: "127.0.0.1"

Table | account_configs fields

Field	Required	Description
`assume_role_arn`	N	STS AssumeRole ARN. If omitted, the agent default role (`input.assume_role_arn`, or the EC2 role if not set) is used. - Used for instance discovery, metrics, cluster specs, and slow query lookups in this account.
`clusters`	△	Aurora/DocumentDB cluster names. Member instances are automatically discovered.
`instances`	△	Standalone RDS instance names not belonging to a cluster.

△: Enter at least one of clusters or instances.

Note

Difference between clusters and instances

	`clusters`	`instances`
Target	Aurora clusters, DocumentDB clusters	Standalone RDS instances without a cluster
Behavior	Auto-discovers member instances by cluster name	Directly specifies instance names
Autoscale	Automatically reflects instance additions/deletions	N/A
Example	Aurora MySQL cluster	Standalone RDS MySQL instance

Configuration example 1: Single account + standalone instance

clusters:
  autoscale:
    enabled: true
    interval: 300
  account_configs:
    - clusters: ["prod-aurora"]
      instances: ["legacy-mysql-standalone"]

Configuration example 2: 3 accounts (local + partner + QA)

clusters:
  autoscale:
    enabled: true
    interval: 300
  account_configs:
    - clusters: ["prod-cluster", "staging-cluster"]

    - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
      clusters: ["partner-prod", "partner-dev"]

    - assume_role_arn: "arn:aws:iam::222222222222:role/QADBXCRole"
      clusters: ["qa-cluster"]
      instances: ["qa-standalone-pg"]

Caution

names and account_configs cannot be used simultaneously. A validation error occurs at agent startup.
ARN format is strictly validated. arn:aws:iam::<12-digit number>:role/<name> — be careful not to omit the double colons (::).
Each account_configs entry requires at least one of clusters or instances.
autoscale.enabled: true is required for cluster discovery to work.

NCP Cloud DB for PostgreSQL Setup

config.yaml
input:
  csp: "ncp" # Enter the Cloud Service Provider.
  namespace: "vpc_postgresql"
  region: "KR" # KR | SGN | JPN | USWN | DEN
  accessKey: "YOUR_ACCESS_KEY"
  secretKey: "YOUR_SECRET_KEY"
  instances: # Specify the name of the DB Server to monitor in the Cloud DB for PostgreSQL (VPC) list.
    - name: "instance-name"
      domain: "pg-xxxxx.vpc-pub-cdb-kr.ntruss.com" # Enter the private or public domain that can be accessed.
  metrics: # Enter the metrics to collect.
    - "cpu_user"
    - "mem_used"
    - "disk_usage"
    - "nic_total"
    - "cpu_load_1"
    - "tup_inserted"

output: # Enter the WhaTap information to receive the collected metrics.
  license: "4544ee0few5-a880410bb205-2987709519af"
  host: "127.0.0.1"

Field path	Description
`csp`	Indicates using the Naver Cloud Platform (`ncp`) as the cloud service provider.
`namespace`	It is used as the delimiter for monitoring targets or group name. - e.g. `vpc_postgresql`
`region`	Cloud region code - Available values: `KR`, `SGN`, `JPN`, `USWN`, `DEN`
`site`	(Optional) NAVER CLOUD PLATFORM site type - `public`: Private sector (default) - `gov`: Public institutions - `fin`: Finance - The API endpoint for the site is used automatically.
`accessKey`	Access key for API calls to Naver Cloud - Note. How to Create an Access Key and Secret Key
`secretKey`	Secret key for API calls to Naver Cloud
`instances`	List of PostgreSQL instances to monitor - Each instance contains the `name` and `domain` fields.
`instances[].name`	Cloud DB for PostgreSQL (VPC) instance name - It can be checked in DB Server > DB Server Name of the NAVER CLOUD PLATFORM console. - e.g. `whatap-001-70ld`
`instances[].domain`	Domain address that can be accessed from the instance - It can be checked in DB Server > Private or Public Domain of the NAVER CLOUD PLATFORM console. - Enter the Private or Public domain address that is being accessed by the DBX agent. - e.g. `pg-33rr40.vpc-pub-cdb-kr.ntruss.com`
`metrics`	List of metrics to collect - Note. Official Documentation for Cloud DB for PostgreSQL (VPC) metrics
`metrics_interval`	(Optional) Metric collection interval - NCP allows only `5m` (default).
`output`	WhaTap information to receive the collected metrics
`output.license`	WhaTap's license key to transmit the collected metrics
`output.host`	WhaTap server host address (IP) to transmit the collected data to

How to Issue an Access Key / Secret Key

Log in to the NAVER CLOUD PLATFORM Console.
From the top menu, go to My Page > Account Management.
Click Authentication Key Management in the menu.
Click the [Create Key] button to generate a new Access Key and Secret Key.

Role setting

For the agent to operate normally, set the required roles for each service.

AWS Aurora and RDS roles

The Cloud Agent calls the AWS API to perform the following features.

Check the monitoring targets by querying the AWS Aurora and RDS instance and clusters.
Collecting CloudWatch metrics

IAM inline policy

Add the JSON policy as inline policy for IAM user or role. If you are running the agent on EC2, grant the policy to the IAM role associated with the EC2 instance.

This policy is applied to both Aurora and RDS services.
The resources are configured to apply to all Aurora and RDS resources. If needed, the resource ARNs can be restricted depending on the security policy.
The agent can use the read-only APIs only. The roles that can affect the database are not included.
rds:DescribeEvents is used for RDS event collection (events.enabled: true), and the logs: permissions are used for slow query and log collection.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RDSPermissions",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "rds:DescribeDBClusterParameters",
        "rds:DescribeOptionGroups",
        "rds:DescribeEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetricsPermissions",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsPermissions",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:FilterLogEvents",
        "logs:GetLogEvents"
      ],
      "Resource": [
        "arn:aws:logs:*:*:log-group:/aws/rds/*"
      ]
    }
  ]
}

Cross-account IAM permissions

Additional IAM permissions are required to specify a role with input.assume_role_arn or account_configs[].assume_role_arn.

Agent EC2 Instance Profile

Grant the EC2 running the agent permission to assume the specified role. If you specify a default role with input.assume_role_arn, the EC2 Instance Profile needs only this permission, and the IAM inline policy above is granted to the specified role.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::111111111111:role/DBXCRole",
        "arn:aws:iam::222222222222:role/QARole"
      ]
    }
  ]
}

Target role (Cross-Account Role or default role)

Create a role in the target account that allows access from the agent account. When you specify a role in the same account with input.assume_role_arn, configure the Trust Relationship and permissions in the same way.

Trust Relationship: Allow the agent account

{
  "Principal": {
    "AWS": "arn:aws:iam::<agent-account-ID>:role/DBXC-EC2-Instance-Role"
  },
  "Action": "sts:AssumeRole"
}

Permission Policy: RDS/CloudWatch/CloudWatch Logs read permissions

{
  "Effect": "Allow",
  "Action": [
    "rds:DescribeDBInstances",
    "rds:DescribeDBClusters",
    "cloudwatch:GetMetricData",
    "logs:FilterLogEvents",
    "logs:DescribeLogGroups"
  ],
  "Resource": "*"
}

When monitoring DocumentDB, grant docdb:DescribeDBInstances and docdb:DescribeDBClusters instead of the rds: permissions.

Caution

Starting with 0.7.0, slow queries are also queried with the account_configs role

In 0.6.0 or earlier, slow queries and logs.groups were queried with the EC2 role even when account_configs[].assume_role_arn was set. Starting with 0.7.0, slow queries are queried with the role of the corresponding account, so that role must have the logs:FilterLogEvents permission. Without it, slow queries are not collected.

logs.groups is queried with the agent default role (input.assume_role_arn, or the EC2 role if not set), so grant the logs:FilterLogEvents permission to that role.

NCP Cloud DB for PostgreSQL permissions

The Cloud Agent calls the NCP Cloud Insight API to collect metrics and configuration data from the NCP Cloud DB for PostgreSQL instances. For this purpose, Access Key and Secret Key are required.

How to create an Access Key and Secret Key

Log in to the NAVER CLOUD PLATFORM Console.
From the top menu, go to My Page > Account Management.
Select Authentication Key Management from the menu.
Click the [Create Key] button to create new Access Key and Secret Key.

Configuration validation

Before starting the agent, you can check the configuration file and AWS permissions in advance with the validate command.

./dbxc-ctl validate -c config.yaml

validate checks the following items, prints the results, and exits. If any check fails, it reports ERROR along with the permissions to check.

Configuration file format and field values (assume_role_arn ARN format, whether names and account_configs are used together, etc.)
Whether the roles specified in input.assume_role_arn and account_configs[].assume_role_arn can be assumed
Permissions to query instances and clusters for each account
If logs.enabled: true, the logs:FilterLogEvents permission for each log group in logs.groups (based on the agent default role, RDS)

Pricing information

Caution

The Cloud Monitoring Agent is free, but note that separate charges may apply depending on the use of Cloud services.

AWS Pricing

Cloud monitoring agents are provided without separate SaaS fees, and the monitoring feature can be used simply by installing the agent. However, because the metrics are collected through the API for Cloud services such as AWS CloudWatch, separate charges may apply depending on the CloudWatch usage.

This agent basically collects metrics by calling the GetMetricData API every 1 minute. Note that the charge may increase depending on the call frequency and collection targets. To reduce the call frequency, increase metrics_interval to 5m, 15m, or 1h, or reduce the number of metrics to collect.

For more information about the pricing policy, see the Amazon CloudWatch pricing in AWS official documentation page.

NCP Pricing

Cloud monitoring agents are provided without separate SaaS fees, and the monitoring feature can be used simply by installing the agent. The Cloud Monitoring Agent calls the Cloud Insight API every 5 minutes to collect metrics at 1-minute granularity.

The Cloud Insight service of the Naver Cloud Platform (NCP) is currently provided free of charge, but may become paid depending on the future policy. If the Cloud Insight service becomes paid, charges may apply based on the number of API calls. Monitor the usage accordingly.

For more information about the pricing policy, see the Official pricing guide of NAVER Cloud Platform page.

Agent CONFIG.​

Configure AWS Aurora and RDS​

Agent default role (input.assume_role_arn)​

Choosing a configuration method​

account_configs configuration​

Configuration example 1: Single account + standalone instance​

Configuration example 2: 3 accounts (local + partner + QA)​

NCP Cloud DB for PostgreSQL Setup​

How to Issue an Access Key / Secret Key​

Role setting​

AWS Aurora and RDS roles​

IAM inline policy​

Agent EC2 Instance Profile​

Target role (Cross-Account Role or default role)​

NCP Cloud DB for PostgreSQL permissions​

Configuration validation​

Pricing information​

AWS Pricing​

NCP Pricing​

Agent CONFIG.

Configure AWS Aurora and RDS

Agent default role (`input.assume_role_arn`)

Choosing a configuration method

`account_configs` configuration

Configuration example 1: Single account + standalone instance

Configuration example 2: 3 accounts (local + partner + QA)

NCP Cloud DB for PostgreSQL Setup

How to Issue an Access Key / Secret Key

Role setting

AWS Aurora and RDS roles

IAM inline policy

Agent EC2 Instance Profile

Target role (Cross-Account Role or default role)

NCP Cloud DB for PostgreSQL permissions

Configuration validation

Pricing information

AWS Pricing

NCP Pricing