Naver Cloud Platform Exporter Configuration

Caution

Notice on Cloud Insight API Call Volume

The Cloud Insight API call volume grows in proportion to number of collected metrics × number of instances. Select only the metrics you need. For configuration details, refer to config.yml File Configuration.

Prerequisites

NCP Account and Permission Requirements

The Exporter calls the following two APIs. The API key you use must have permissions for both.

Target API	Endpoint	Purpose
Cloud Insight	`cw.apigw.ntruss.com`	Query product key (`cw_key`), metric definitions, and metric data
NCloud API Gateway	`ncloud.apigw.ntruss.com`	Query the region list and the instance list per service

Note

All NCP APIs used by the Exporter perform read-only operations.

When using a sub account's API key, grant both the NCP_CLOUD_INSIGHT_VIEWER and NCP_VPC_SERVER_VIEWER policies to that sub account or its group, and allow API Gateway access. If either policy is missing, the Exporter cannot query Cloud Insight metrics or the VPC Server instance list, and collection may fail.

Collecting Required Information

Collect the following information in advance for Exporter configuration.

Item	Description	Where to Issue
Access Key	NCP API authentication key	My Page → Account Management → Authentication Key Management
Secret Key	NCP API authentication secret	Same as above (visible only at the time of issuance)
Region code	Target region for collection (for example, `KR`)	All regions are queried automatically if not specified

Tip

When using a sub account (IAM), the issued key starts with ncp_iam_.

NCloud Exporter Installation

Download Exporter

Download the binary that matches your system architecture.

# linux/amd64
wget https://repo.whatap.io/exporter/ncloud_exporter/latest/amd64/ncloud_exporter

# linux/arm64
wget https://repo.whatap.io/exporter/ncloud_exporter/latest/arm64/ncloud_exporter

To specify a particular version, enter the version instead of latest.

wget https://repo.whatap.io/exporter/ncloud_exporter/1.0.0/amd64/ncloud_exporter

Granting Execute Permission and Installing

chmod +x ncloud_exporter
sudo mv ncloud_exporter /usr/local/bin/
sudo mkdir -p /etc/ncloud_exporter

config.yml File Configuration

Supported Service List

Namespace	NCP Service
`ncloud.vserver`	VPC Server
`ncloud.vloadbalancer`	VPC Load Balancer
`ncloud.vloadbalancertargetgroup`	Load Balancer Target Group
`ncloud.vmysql`	Cloud DB for MySQL
`ncloud.vpostgresql`	Cloud DB for PostgreSQL
`ncloud.vredis`	Cloud DB for Cache
`ncloud.vmongodb`	Cloud DB for MongoDB
`ncloud.vmssql`	Cloud DB for MSSQL
`ncloud.vautoscaling`	Auto Scaling (VPC)
`ncloud.vnks`	Ncloud Kubernetes Service (New)
`ncloud.vsearchengine`	Search Engine Service
`ncloud.vhadoop`	Cloud Hadoop

A metric catalog is provided for all 12 services, and the catalog contains 283 metrics in total. The metrics you can actually query vary by resource type, node role, and service configuration.

Note

Service names

ncloud.vredis corresponds to Cloud DB for Cache in the NCP console. Depending on the engine, it uses either the cache_* or the redis_* series.
ncloud.vnks uses the metrics of the new Ncloud Kubernetes Service.

Building config.yml with the setup builder

Instead of writing the configuration file yourself, you can select the services and metrics to collect on the NCP installation guide screen in the product and have the config.yml content generated. Copy the result or download it as a file, and place it at /etc/ncloud_exporter/config.yml.

Action	Result
Opening the builder	All 12 services start in the off state.
Turning on a service	The metrics required by that service's preset dashboard are selected automatically. For VPC Server, this combination collects 16 series per instance.
Selecting metrics	Expand a service to turn its catalog metrics and aggregations on or off individually.
Exporting	Copy or download config.yml with your selection.

Note

Services that have no metrics in the catalog provide only a toggle, so you can export them without selecting metrics. In that case the service is omitted from config.yml and nothing is collected for it.

The VPC Server list in the builder shows only 25 of the 27 entries in the VPC Server default metrics table. dev_nm (STRING type) and mnt_stat_cd (interval: Min1 only) do not produce time series and cannot be put in the configuration file, so they are excluded from the list.

Preset dashboards

A preset dashboard is provided for each of the 12 supported services. You can see metrics as soon as collection starts, without placing widgets yourself.

NCP service	Dashboard key
VPC Server	`vpc_server`
VPC Load Balancer	`load_balancer`
Load Balancer Target Group	`target_group`
Cloud DB for MySQL	`mysql`
Cloud DB for PostgreSQL	`postgresql`
Cloud DB for Cache	`cache`
Cloud DB for MongoDB	`mongodb`
Cloud DB for MSSQL	`mssql`
Auto Scaling (VPC)	`auto_scaling`
Ncloud Kubernetes Service (New)	`nks`
Search Engine Service	`search_engine`
Cloud Hadoop	`hadoop`

Each widget title has a description icon next to it. Hover over the icon to see what the metric means.

config.yml Example File

Create the configuration file at /etc/ncloud_exporter/config.yml. The following is a basic configuration that collects VPC Server metrics.

ncloud:
  access_key: "YOUR_ACCESS_KEY"
  secret_key: "YOUR_SECRET_KEY"

namespaces:
  - name: "ncloud.vserver"
    enabled: true
    regions: ["KR"]          # All regions if the array is empty
    interval: "Min5"         # Min1 | Min5 | Min30 | Hour2 | Day1
    aggregations: ["AVG"]    # Default aggregation for the metrics below
    metrics:
      # CPU
      - name: "avg_cpu_used_rto"     # CPU utilization (%)
      - name: "max_cpu_used_rto"     # CPU utilization peak (%)
        aggregations: ["MAX"]
      - name: "load_average_1m"
      - name: "load_average_5m"
      - name: "load_average_15m"

      # Memory
      - name: "mem_usert"            # Memory utilization (%)
        aggregations: ["AVG", "MAX"]
      - name: "swap_usert"           # Swap utilization (%)

      # File system
      - name: "avg_fs_usert"
      - name: "max_fs_usert"
        aggregations: ["MAX"]

      # Network
      - name: "avg_rcv_bps"          # Inbound (bits/sec)
      - name: "avg_snd_bps"          # Outbound (bits/sec)

      # Disk I/O
      - name: "avg_read_byt_cnt"
      - name: "avg_write_byt_cnt"
      - name: "avg_read_cnt"
      - name: "avg_write_cnt"

  - name: "ncloud.vloadbalancer"
    enabled: false
    regions: []

Configuration Items

Item	Description	Default
`ncloud.access_key`	NCP API Access Key	(Required)
`ncloud.secret_key`	NCP API Secret Key	(Required)
`namespaces[].name`	Service namespace to collect	-
`namespaces[].enabled`	Whether collection is enabled	`false`
`namespaces[].regions`	Target regions (all regions if the array is empty)	`[]`
`namespaces[].interval`	Query interval (`Min1` to `Day1`)	`Min5`
`namespaces[].aggregations`	Default aggregation for the namespace	(All provided by the API)
`namespaces[].metrics`	Metrics to collect	(All if omitted)

Caution

If you do not specify metrics, all metrics × all aggregations for that service are collected. For VPC Server, 125 series are created per instance, so specify only the metrics you need. The example configuration above collects 16 series per instance.

For the metric list per service, refer to VPC Server Default Metrics.

Injecting Credentials Through Environment Variables

To avoid storing keys in plain text in the configuration file, use environment variables. Environment variables take precedence over values in the configuration file.

Environment Variable	Description
`NCLOUD_ACCESS_KEY`	Overrides `ncloud.access_key`
`NCLOUD_SECRET_KEY`	Overrides `ncloud.secret_key`
`NCLOUD_CW_API_GW`	Cloud Insight endpoint (default `https://cw.apigw.ntruss.com`)
`NCLOUD_API_GW`	NCloud API GW endpoint (default `https://ncloud.apigw.ntruss.com`)

Service Registration and Execution

Execution Options

Flag	Description	Default
`--config`	Configuration file path	`config.yml`
`--web.listen-address`	HTTP listener address	`:9850`
`--web.telemetry-path`	Metric endpoint path	`/metrics`
`--log.level`	Log level (`debug`, `info`, `warn`, `error`)	`info`
`--log.format`	Log format (`text`, `json`)	`text`

Method A: Registering a systemd Service

sudo tee /etc/systemd/system/ncloud-exporter.service > /dev/null <<'EOF'
[Unit]
Description=NCloud Exporter
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
Environment="NCLOUD_ACCESS_KEY=YOUR_ACCESS_KEY"
Environment="NCLOUD_SECRET_KEY=YOUR_SECRET_KEY"
ExecStart=/usr/local/bin/ncloud_exporter \
  --config=/etc/ncloud_exporter/config.yml \
  --web.listen-address=:9850
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

After registering, start the service.

sudo systemctl daemon-reload
sudo systemctl enable ncloud-exporter
sudo systemctl start ncloud-exporter
sudo systemctl status ncloud-exporter

Tip

After modifying the configuration file, you can apply changes with sudo systemctl reload ncloud-exporter without a restart. Credentials, namespaces, and metric selections are reloaded. However, the listener address and path are execution arguments, so changing them requires a restart.

Method B: nohup Execution

nohup /usr/local/bin/ncloud_exporter \
  --config=/etc/ncloud_exporter/config.yml \
  --web.listen-address=:9850 > /var/log/ncloud_exporter.log 2>&1 &

Verifying Metric Collection and Troubleshooting

Checking Metrics

curl http://localhost:9850/metrics

# Check a specific service only
curl -s http://localhost:9850/metrics | grep '^ncloud_vserver'

Example of Normal Output

# HELP ncloud_vserver_avg_cpu_used_rto_avg NCloud ncloud.vserver avg_cpu_used_rto (%)
# TYPE ncloud_vserver_avg_cpu_used_rto_avg gauge
ncloud_vserver_avg_cpu_used_rto_avg{instancename="my-server",instanceno="12345678",regioncode="KR",serverinstancetype="Micro"} 0.360744
ncloud_vserver_mem_usert_avg{instancename="my-server",instanceno="12345678",regioncode="KR",serverinstancetype="Micro"} 72.1

Check the Exporter's own status with the following metrics.

ncloud_scrape_errors_total{namespace="ncloud.vserver"} 0
ncloud_scrape_duration_seconds 0.264890458

Metric Name Conversion Rule

ncloud_{service}_{metric}_{aggregation}

service: The namespace with the ncloud. prefix removed (ncloud.vserver → vserver)
metric: The Cloud Insight metric name (avg_cpu_used_rto)
aggregation: The aggregation method converted to lowercase (avg, max, min, sum, count)

Example: ncloud.vserver + avg_cpu_used_rto + AVG → ncloud_vserver_avg_cpu_used_rto_avg

Troubleshooting

Symptom	Cause	Solution
Startup fails with the `failed to initialize cw_keys` log and `status 401 Authentication Failed`	Incorrect Access Key/Secret Key, or insufficient permissions	Check the key values and verify that the key has Cloud Insight read permission.
`read config file: open config.yml: no such file or directory`	Incorrect configuration file path	Specify an absolute path in `--config`.
Startup fails with `unknown aggregation "..."` or `unknown interval "..."`	Typo in the configuration file	`aggregations` allows only `AVG`/`MAX`/`MIN`/`SUM`/`COUNT`, and `interval` allows only `Min1`/`Min5`/`Min30`/`Hour2`/`Day1`.
`WARN configured metric matched no available metric`	A metric name that does not exist was specified	Check the actual metric name in the metric list.
`WARN some configured aggregations are not supported`	An aggregation not supported by that metric or interval	Change it to a value from the `available` list in the log.
No `ncloud_` metrics appear in `/metrics`	No instances in that region, or `enabled: false`	Check the `regions` setting and the `enabled` value. To avoid limiting regions, leave it as `regions: []`.
Only certain metrics have empty values	Cloud Insight collection delay, or the instance does not provide the metric	Verify that the monitoring agent is installed on the server. If there is no data within the last 10 minutes, no time series is created.
The `ncloud_scrape_errors_total` value keeps increasing	API call failure	Run with `--log.level=debug` to check the failed namespace and the cause.

Tip

When validating your configuration, run with --log.level=debug. The selected metrics, configurations that failed to match, and API errors are all printed to the log.

OpenAgent Download and Configuration

All files must be located in the same directory.

Directory Structure
/opt/whatap/openagent/
├── openagent           # Executable file
├── whatap.conf         # Configuration file
└── scrape_config.yaml  # Scraping configuration file

Download and Permission Settings

mkdir -p /opt/whatap/openagent
cd /opt/whatap/openagent

## AMD64 (Intel/AMD 64-bit processor)
wget https://repo.whatap.io/openagent/latest/amd/openagent

## ARM64 (ARM processor in Linux environment)
wget https://repo.whatap.io/openagent/latest/arm/openagent

chmod +x openagent

Creating scrape_config.yaml

#scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
      - targetName: ncloud-exporter
        type: StaticEndpoints
        endpoints:
          - address: "127.0.0.1:9850"
            path: "/metrics"
            scheme: "http"
            interval: "300s"
            metricRelabelConfigs:
              - source_labels: ["__name__"]
                regex: "ncloud_.*"
                action: keep

Caution

The minimum collection cycle for Cloud Insight is 5 minutes.

Setting interval to a shorter value only collects the same value repeatedly and increases the API call volume. A value of 300s or higher is recommended.

Configuration Elements

Item	Description
`targetName`	Name of the collection target
`type`	Fixed to `StaticEndpoints`
`address`	Exporter address (`host:port`)
`path`	Metric path (default `/metrics`)
`scheme`	`http` or `https`
`interval`	Collection cycle (`300s` recommended)
`metricRelabelConfigs`	Filtering and relabeling for the metrics to collect

Metric Filtering Examples

1. Collecting all metrics from the Exporter

Caution

Not recommended, because Go runtime metrics (go_*, process_*) are also included.

metricRelabelConfigs:
  - source_labels: ["__name__"]
    regex: ".*"
    action: keep

2. Collecting NCloud metrics only (recommended)

metricRelabelConfigs:
  - source_labels: ["__name__"]
    regex: "ncloud_.*"
    action: keep

3. Collecting only CPU and memory for a specific service

metricRelabelConfigs:
  - source_labels: ["__name__"]
    regex: "ncloud_vserver_(avg_cpu_used_rto|mem_usert)_.*"
    action: keep

4. Adding a static label

metricRelabelConfigs:
  - target_label: "cloud_provider"
    replacement: "ncloud"
    action: replace

Execution

# Default execution
./openagent standalone

# Background execution
nohup ./openagent standalone > /dev/null 2>&1 &

# Check logs
tail -f logs/whatap-boot-$(date +%Y%m%d).log

# Check and terminate the process
ps aux | grep openagent
pkill openagent

VPC Server Default Metrics`Dashboard install page only`

Metric	Description	Aggregation (Min5)	Unit	Dimension	Default	Statistic
`avg_cpu_used_rto`	CPU Utilization Average	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	AVG
`max_cpu_used_rto`	CPU used ratio maximum	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	MAX
`load_average_1m`	CPU load 1 minute	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	AVG
`load_average_5m`	CPU load 5 minute average	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	AVG
`load_average_15m`	CPU load 15 minute average	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	AVG
`mem_usert`	Memory Utilization	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=memory)	O	AVG, MAX
`swap_usert`	Swap used ratio	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=memory)	O	AVG
`avg_fs_usert`	File System Utilization Average	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	AVG
`max_fs_usert`	File system used ratio maximum	COUNT, SUM, MAX, MIN, AVG	%	instanceNo (type=svr)	O	MAX
`avg_read_byt_cnt`	Disk read bytes average	COUNT, SUM, MAX, MIN, AVG	bytes/sec	instanceNo (type=svr)	O	AVG
`max_read_byt_cnt`	Disk read bytes maximum	COUNT, SUM, MAX, MIN, AVG	bytes/sec	instanceNo (type=svr)	X	-
`avg_write_byt_cnt`	Disk write bytes average	COUNT, SUM, MAX, MIN, AVG	bytes/sec	instanceNo (type=svr)	O	AVG
`max_write_byt_cnt`	Disk write bytes maximum	COUNT, SUM, MAX, MIN, AVG	bytes/sec	instanceNo (type=svr)	X	-
`avg_read_cnt`	Disk read count per second average	COUNT, SUM, MAX, MIN, AVG	num/sec	instanceNo (type=svr)	O	AVG
`max_read_cnt`	Disk read count per second maximum	COUNT, SUM, MAX, MIN, AVG	num/sec	instanceNo (type=svr)	X	-
`avg_write_cnt`	Disk write count per second average	COUNT, SUM, MAX, MIN, AVG	num/sec	instanceNo (type=svr)	O	AVG
`max_write_cnt`	Disk write count per second maximum	COUNT, SUM, MAX, MIN, AVG	num/sec	instanceNo (type=svr)	X	-
`avg_rcv_bps`	Network In Average	COUNT, SUM, MAX, MIN, AVG	bits/sec	instanceNo (type=svr)	O	AVG
`max_rcv_bps`	Network receive bits/sec maximum	COUNT, SUM, MAX, MIN, AVG	bits/sec	instanceNo (type=svr)	X	-
`avg_snd_bps`	Network Out Average	COUNT, SUM, MAX, MIN, AVG	bits/sec	instanceNo (type=svr)	O	AVG
`max_snd_bps`	Network send bits/sec maximum	COUNT, SUM, MAX, MIN, AVG	bits/sec	instanceNo (type=svr)	X	-
`avg_rcv_pps`	Network receive packets/sec average	COUNT, SUM, MAX, MIN, AVG	packets/sec	instanceNo (type=svr)	X	-
`max_rcv_pps`	Network receive packets/sec maximum	COUNT, SUM, MAX, MIN, AVG	packets/sec	instanceNo (type=svr)	X	-
`avg_snd_pps`	Network send packets/sec average	COUNT, SUM, MAX, MIN, AVG	packets/sec	instanceNo (type=svr)	X	-
`max_snd_pps`	Network send packets/sec maximum	COUNT, SUM, MAX, MIN, AVG	packets/sec	instanceNo (type=svr)	X	-
`dev_nm`	Device name	Not supported (Min1 only)	-	instanceNo (type=fs, mnt_nm=/)	X	No time series is created even if specified, because it is a STRING type.
`mnt_stat_cd`	Mount state	Not supported (Min1 only)	-	instanceNo (type=fs, mnt_nm=/)	X	Available only with `interval: Min1`.

Prerequisites​

NCP Account and Permission Requirements​

Collecting Required Information​

NCloud Exporter Installation​

Download Exporter​

Granting Execute Permission and Installing​

config.yml File Configuration​

Supported Service List​

Building config.yml with the setup builder​

Preset dashboards​

config.yml Example File​

Configuration Items​

Injecting Credentials Through Environment Variables​

Service Registration and Execution​

Execution Options​

Method A: Registering a systemd Service​

Method B: nohup Execution​

Verifying Metric Collection and Troubleshooting​

Checking Metrics​

Example of Normal Output​

Metric Name Conversion Rule​

Troubleshooting​

OpenAgent Download and Configuration​

Download and Permission Settings​

Creating scrape_config.yaml​

Configuration Elements​

Metric Filtering Examples​

Execution​

VPC Server Default MetricsDashboard install page only​

Prerequisites

NCP Account and Permission Requirements

Collecting Required Information

NCloud Exporter Installation

Download Exporter

Granting Execute Permission and Installing

config.yml File Configuration

Supported Service List

Building config.yml with the setup builder

Preset dashboards

config.yml Example File

Configuration Items

Injecting Credentials Through Environment Variables

Service Registration and Execution

Execution Options

Method A: Registering a systemd Service

Method B: nohup Execution

Verifying Metric Collection and Troubleshooting

Checking Metrics

Example of Normal Output

Metric Name Conversion Rule

Troubleshooting

OpenAgent Download and Configuration

Download and Permission Settings

Creating scrape_config.yaml

Configuration Elements

Metric Filtering Examples

Execution

VPC Server Default Metrics`Dashboard install page only`