Cloud Agent Configuration

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

Agent CONFIG.

The following explains how to configure the AWS DocumentDB Agent.

AWS DocumentDB Agent

config.yaml
input:
  csp: "aws" # Enter the Cloud Service Provider.
  namespace: "docdb"
  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 always collected. When the instances within the cluster are specified in this property, collection is applied regardless of the autoscaling status.
    - name: "docdb-instance-name"
  clusters:
    autoscale:
      enabled: false # If autoscale is enabled, autoscaled instances are added or deleted for collection targets.
      interval: 60 # Autoscale checking cycle for the specified clusters (unit: second)
    names:
      - "docdb-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"
    - "FreeableMemory"
    - "ReadLatency"   
    - "WriteLatency"  
    - "DatabaseConnections"
  logs:
    enabled: false # Can be enabled/disabled. Select true/false.
    groups: # Add the desired AWS log groups.
      - "/aws/rds/cluster/docdb-cluster-name/error"
      - "/aws/lambda/MyLambda"

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 the cloud service provider.
`namespace`	Namespace of the collection target service - When AWS DocumentDB is set, enter `docdb` as the fixed value.
`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`	DocumentDB InstanceName - e.g. `docdb-2025-04-08-01-21-05`
`instances[].oname`	(Optional) Instance name (oname) displayed on the WhaTap screen - If omitted, it is generated automatically from the endpoint.
`clusters`	DocumentDB 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`, `FreeableMemory`, etc - Note. Official Documentation for Amazon DocumentDB metrics
`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
`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: "docdb"
  region: "ap-northeast-2"
  assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly"
  clusters:
    names:
      - "docdb-cluster-name"

Role priority

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

Instance discovery and metrics 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 is not tied to a specific cluster, so it always uses the agent default role (input.assume_role_arn, or the EC2 role if not set).
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.

Caution

input.assume_role_arn is available only with csp: "aws". Setting it for any other csp, or using an invalid ARN format (arn:aws:iam::<12-digit account ID>:role/<name>), causes a configuration error at agent startup.
This setting is supported in DBXC agent 0.7.0 or later.

Cross-account monitoring (multi AWS account)

A single cloud agent can monitor 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 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: "docdb"
  region: "ap-northeast-2"
  clusters:
    autoscale:
      enabled: true
      interval: 300
    account_configs:
      # Local account
      - clusters: ["local-docdb-cluster"]

      # Another account
      - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
        clusters: ["partner-docdb-cluster"]
  metrics:
    - "CPUUtilization"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "DatabaseConnections"

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.
`clusters`	△	DocumentDB cluster names. Member instances are automatically discovered.
`instances`	△	Standalone instance names not belonging to a cluster.

△: Enter at least one of clusters or instances.

Note

Difference between clusters and instances

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

Role setting

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

AWS DocumentDB permissions

The cloud agent performs the following features for DocumentDB.

Viewing the DocumentDB instances and clusters
Collecting CloudWatch metrics

IAM inline policy for DocumentDB

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

The resources are configured to apply to all DocumentDB 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.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DocDBPermissions",
      "Effect": "Allow",
      "Action": [
        "docdb:DescribeDBInstances",
        "docdb:DescribeDBClusters"
      ],
      "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/docdb/*"
      ]
    }
  ]
}

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.

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.

Agent CONFIG.​

AWS DocumentDB Agent​

Agent default role (input.assume_role_arn)​

Choosing a configuration method​

account_configs configuration​

Role setting​

AWS DocumentDB permissions​

IAM inline policy for DocumentDB​

Agent EC2 Instance Profile​

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

Configuration validation​

Pricing information​

AWS Pricing​

Agent CONFIG.

AWS DocumentDB Agent

Agent default role (`input.assume_role_arn`)

Choosing a configuration method

`account_configs` configuration

Role setting

AWS DocumentDB permissions

IAM inline policy for DocumentDB

Agent EC2 Instance Profile

Target role (Cross-Account Role or default role)

Configuration validation

Pricing information

AWS Pricing