Skip to main content

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 APIEndpointPurpose
Cloud Insightcw.apigw.ntruss.comQuery product key (cw_key), metric definitions, and metric data
NCloud API Gatewayncloud.apigw.ntruss.comQuery 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.

ItemDescriptionWhere to Issue
Access KeyNCP API authentication keyMy Page → Account Management → Authentication Key Management
Secret KeyNCP API authentication secretSame as above (visible only at the time of issuance)
Region codeTarget 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​

NamespaceNCP Service
ncloud.vserverVPC Server
ncloud.vloadbalancerVPC Load Balancer
ncloud.vloadbalancertargetgroupLoad Balancer Target Group
ncloud.vmysqlCloud DB for MySQL
ncloud.vpostgresqlCloud DB for PostgreSQL
ncloud.vredisCloud DB for Cache
ncloud.vmongodbCloud DB for MongoDB
ncloud.vmssqlCloud DB for MSSQL
ncloud.vautoscalingAuto Scaling (VPC)
ncloud.vnksNcloud Kubernetes Service (New)
ncloud.vsearchengineSearch Engine Service
ncloud.vhadoopCloud 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.

ActionResult
Opening the builderAll 12 services start in the off state.
Turning on a serviceThe metrics required by that service's preset dashboard are selected automatically. For VPC Server, this combination collects 16 series per instance.
Selecting metricsExpand a service to turn its catalog metrics and aggregations on or off individually.
ExportingCopy 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 serviceDashboard key
VPC Servervpc_server
VPC Load Balancerload_balancer
Load Balancer Target Grouptarget_group
Cloud DB for MySQLmysql
Cloud DB for PostgreSQLpostgresql
Cloud DB for Cachecache
Cloud DB for MongoDBmongodb
Cloud DB for MSSQLmssql
Auto Scaling (VPC)auto_scaling
Ncloud Kubernetes Service (New)nks
Search Engine Servicesearch_engine
Cloud Hadoophadoop

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

NCP alert templates​

31 PromQL alert templates are provided for 12 NCP services. When you add an event in the Alert > Event Configuration menu and select a template from the template list, the PromQL, detection condition, event level, and alert message are pre-filled.

  • The event creation screen of an NCP platform project shows only NCP templates.

  • OpenMetrics projects show CloudWatch, Azure, and NCP templates after the OpenMetrics templates.

  • The template list on the composite metrics event creation screen shows the same templates.

ServiceTemplateMetricConditionLevel
NCP VPC ServerHigh CPUncloud_vserver_avg_cpu_used_rto_avgvalue > 80Warning
NCP VPC ServerHigh Memoryncloud_vserver_mem_usert_avgvalue > 90Warning
NCP VPC ServerHigh Filesystem Usagencloud_vserver_max_fs_usert_maxvalue > 90Warning
NCP Load BalancerCollection Errorsncloud_scrape_errors_total{namespace="ncloud.vloadbalancer"}value > 0Warning
NCP Target GroupUnhealthy Targetsncloud_vloadbalancertargetgroup_unavailable_host_count_maxvalue > 0Critical
NCP Target GroupNo Healthy Targetsncloud_vloadbalancertargetgroup_available_host_count_minvalue < 1Critical
NCP MySQLHigh Memoryncloud_vmysql_mem_pct_avgvalue > 90Warning
NCP MySQLHigh CPUncloud_vmysql_cpu_total_avgvalue > 80Warning
NCP PostgreSQLAvailability Degradedncloud_vpostgresql_pg_up_avgvalue < 1Critical
NCP PostgreSQLHigh CPUncloud_vpostgresql_cpu_total_avgvalue > 80Warning
NCP PostgreSQLHigh Memoryncloud_vpostgresql_mem_used_avgvalue > 90Warning
NCP CacheHigh Cache Memoryncloud_vredis_cache_memory_pct_avg or ncloud_vredis_redis_memory_pct_avgvalue > 80Warning
NCP CacheHigh Host Memoryncloud_vredis_mem_pct_avgvalue > 90Warning
NCP Auto ScalingHigh Group CPUncloud_vautoscaling_avg_cpu_used_rto_avgvalue > 80Warning
NCP Auto ScalingHigh Group Memoryncloud_vautoscaling_mem_usert_avgvalue > 90Warning
NCP MongoDBAvailability Degradedncloud_vmongodb_ping_avgvalue < 1Critical
NCP MongoDBHigh CPUncloud_vmongodb_cpu_total_avgvalue > 80Warning
NCP MongoDBHigh Memoryncloud_vmongodb_mem_pct_avgvalue > 90Warning
NCP MSSQLLow Disk Spacencloud_vmssql_disk_free_percent_avgvalue < 10Warning
NCP MSSQLHigh CPUncloud_vmssql_cpu_avgvalue > 80Warning
NCP KubernetesNodes Not Readyncloud_vnks_node_not_ready_count_maxvalue > 0Critical
NCP KubernetesFailed Podsncloud_vnks_pod_phase_failed_max{type="PodStatus"}value > 0Critical
NCP KubernetesPending Podsncloud_vnks_pod_phase_pending_max{type="PodStatus"}value > 0Warning
NCP Search EngineProcess Degradedncloud_vsearchengine_search_engine_process_status_avgvalue < 1Critical
NCP Search EngineHigh Heap Usagencloud_vsearchengine_heap_used_percent_avgvalue > 85Warning
NCP Search EngineHigh CPUncloud_vsearchengine_cpu_total_avgvalue > 80Warning
NCP HadoopMissing HDFS Blocksncloud_vhadoop_missing_blocks_avg{type="HADOOP"}value > 0Critical
NCP HadoopUnhealthy YARN Nodesncloud_vhadoop_unhealthy_nodes_avg{type="HADOOP"}value > 0Critical
NCP HadoopHigh HDFS Usagencloud_vhadoop_hdfs_utilization_avg{type="HADOOP"}value > 85Warning
NCP HadoopHigh Node CPUncloud_vhadoop_avg_cpu_used_rto_avg{type="svr"}value > 80Warning
NCP HadoopHigh Node Memoryncloud_vhadoop_mem_usert_avg{type="memory"}value > 90Warning

All templates evaluate data from the last 10 minutes every 60 seconds, and once an alert is triggered, the same event is not notified again for 30 minutes. Alert messages include the instance name, instance number, region code, and measured value (for Collection Errors, the collection namespace and error count) as substitution variables.

Note

Thresholds are examples for review and are not official NCP recommendations. Adjust them to your workload before saving. Also check the following.

  • All values are Cloud Insight aggregated values. Availability and process status templates use averages, so value < 1 means an abnormal state occurred during the aggregation interval, not that the service is currently completely down.
  • The Collection Errors template alerts on Load Balancer collection errors and does not indicate a Load Balancer failure. If errors occur, check the exporter logs and API permissions.
  • If you select an aggregation interval longer than the default Min5, adjust the query range as well.

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​

ItemDescriptionDefault
ncloud.access_keyNCP API Access Key(Required)
ncloud.secret_keyNCP API Secret Key(Required)
namespaces[].nameService namespace to collect-
namespaces[].enabledWhether collection is enabledfalse
namespaces[].regionsTarget regions (all regions if the array is empty)[]
namespaces[].intervalQuery interval (Min1 to Day1)Min5
namespaces[].aggregationsDefault aggregation for the namespace(All provided by the API)
namespaces[].metricsMetrics 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.

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 VariableDescription
NCLOUD_ACCESS_KEYOverrides ncloud.access_key
NCLOUD_SECRET_KEYOverrides ncloud.secret_key
NCLOUD_CW_API_GWCloud Insight endpoint (default https://cw.apigw.ntruss.com)
NCLOUD_API_GWNCloud API GW endpoint (default https://ncloud.apigw.ntruss.com)

Service Registration and Execution​

Execution Options​

FlagDescriptionDefault
--configConfiguration file pathconfig.yml
--web.listen-addressHTTP listener address:9850
--web.telemetry-pathMetric endpoint path/metrics
--log.levelLog level (debug, info, warn, error)info
--log.formatLog 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​

SymptomCauseSolution
Startup fails with the failed to initialize cw_keys log and status 401 Authentication FailedIncorrect Access Key/Secret Key, or insufficient permissionsCheck the key values and verify that the key has Cloud Insight read permission.
read config file: open config.yml: no such file or directoryIncorrect configuration file pathSpecify an absolute path in --config.
Startup fails with unknown aggregation "..." or unknown interval "..."Typo in the configuration fileaggregations allows only AVG/MAX/MIN/SUM/COUNT, and interval allows only Min1/Min5/Min30/Hour2/Day1.
WARN configured metric matched no available metricA metric name that does not exist was specifiedCheck the actual metric name in the metric list.
WARN some configured aggregations are not supportedAn aggregation not supported by that metric or intervalChange it to a value from the available list in the log.
No ncloud_ metrics appear in /metricsNo instances in that region, or enabled: falseCheck the regions setting and the enabled value. To avoid limiting regions, leave it as regions: [].
Only certain metrics have empty valuesCloud Insight collection delay, or the instance does not provide the metricVerify 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 increasingAPI call failureRun 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​

ItemDescription
targetNameName of the collection target
typeFixed to StaticEndpoints
addressExporter address (host:port)
pathMetric path (default /metrics)
schemehttp or https
intervalCollection cycle (300s recommended)
metricRelabelConfigsFiltering 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 MetricsDashboard install page only​

MetricDescriptionAggregation (Min5)UnitDimensionDefaultStatistic
avg_cpu_used_rtoCPU Utilization AverageCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OAVG
max_cpu_used_rtoCPU used ratio maximumCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OMAX
load_average_1mCPU load 1 minuteCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OAVG
load_average_5mCPU load 5 minute averageCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OAVG
load_average_15mCPU load 15 minute averageCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OAVG
mem_usertMemory UtilizationCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=memory)OAVG, MAX
swap_usertSwap used ratioCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=memory)OAVG
avg_fs_usertFile System Utilization AverageCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OAVG
max_fs_usertFile system used ratio maximumCOUNT, SUM, MAX, MIN, AVG%instanceNo (type=svr)OMAX
avg_read_byt_cntDisk read bytes averageCOUNT, SUM, MAX, MIN, AVGbytes/secinstanceNo (type=svr)OAVG
max_read_byt_cntDisk read bytes maximumCOUNT, SUM, MAX, MIN, AVGbytes/secinstanceNo (type=svr)X-
avg_write_byt_cntDisk write bytes averageCOUNT, SUM, MAX, MIN, AVGbytes/secinstanceNo (type=svr)OAVG
max_write_byt_cntDisk write bytes maximumCOUNT, SUM, MAX, MIN, AVGbytes/secinstanceNo (type=svr)X-
avg_read_cntDisk read count per second averageCOUNT, SUM, MAX, MIN, AVGnum/secinstanceNo (type=svr)OAVG
max_read_cntDisk read count per second maximumCOUNT, SUM, MAX, MIN, AVGnum/secinstanceNo (type=svr)X-
avg_write_cntDisk write count per second averageCOUNT, SUM, MAX, MIN, AVGnum/secinstanceNo (type=svr)OAVG
max_write_cntDisk write count per second maximumCOUNT, SUM, MAX, MIN, AVGnum/secinstanceNo (type=svr)X-
avg_rcv_bpsNetwork In AverageCOUNT, SUM, MAX, MIN, AVGbits/secinstanceNo (type=svr)OAVG
max_rcv_bpsNetwork receive bits/sec maximumCOUNT, SUM, MAX, MIN, AVGbits/secinstanceNo (type=svr)X-
avg_snd_bpsNetwork Out AverageCOUNT, SUM, MAX, MIN, AVGbits/secinstanceNo (type=svr)OAVG
max_snd_bpsNetwork send bits/sec maximumCOUNT, SUM, MAX, MIN, AVGbits/secinstanceNo (type=svr)X-
avg_rcv_ppsNetwork receive packets/sec averageCOUNT, SUM, MAX, MIN, AVGpackets/secinstanceNo (type=svr)X-
max_rcv_ppsNetwork receive packets/sec maximumCOUNT, SUM, MAX, MIN, AVGpackets/secinstanceNo (type=svr)X-
avg_snd_ppsNetwork send packets/sec averageCOUNT, SUM, MAX, MIN, AVGpackets/secinstanceNo (type=svr)X-
max_snd_ppsNetwork send packets/sec maximumCOUNT, SUM, MAX, MIN, AVGpackets/secinstanceNo (type=svr)X-
dev_nmDevice nameNot supported (Min1 only)-instanceNo (type=fs, mnt_nm=/)XNo time series is created even if specified, because it is a STRING type.
mnt_stat_cdMount stateNot supported (Min1 only)-instanceNo (type=fs, mnt_nm=/)XAvailable only with interval: Min1.