Naver Cloud Platform Exporter 設定

注意

Cloud Insight API 呼び出し量に関する案内

Cloud Insight API の呼び出し量は 収集メトリクス数 × インスタンス数 に比例して増加します。必要なメトリクスのみを選択して収集してください。設定方法は config.yml ファイル設定をご参照ください。

事前準備

NCP アカウントおよび権限要件

Exporter は以下の 2 種類の API を呼び出します。使用する API キーには両方の権限が必要です。

対象 API	エンドポイント	用途
Cloud Insight	`cw.apigw.ntruss.com`	製品キー（`cw_key`）の照会、メトリクス定義の照会、メトリクスデータの照会
NCloud API Gateway	`ncloud.apigw.ntruss.com`	リージョン一覧の照会、サービス別インスタンス一覧の照会

ノート

Exporter が使用する NCP API はすべて照会（読み取り）操作のみを実行します。

サブアカウントの API キーを使用する場合は、該当サブアカウントまたは所属グループに NCP_CLOUD_INSIGHT_VIEWER と NCP_VPC_SERVER_VIEWER ポリシーの両方を付与し、API Gateway へのアクセスを許可してください。2 つのポリシーのいずれかが欠けていると、Cloud Insight のメトリクスまたは VPC Server のインスタンス一覧を照会できず、収集に失敗する可能性があります。

必要な情報の収集

Exporter の設定に必要な情報を事前に収集します。

項目	説明	発行場所
Access Key	NCP API 認証キー	マイページ → アカウント管理 → 認証キー管理
Secret Key	NCP API 認証シークレット	上記と同じ（発行時点のみ確認可能）
リージョンコード	収集対象リージョン（例: `KR`）	未指定の場合は全リージョンを自動照会

Tips

サブアカウント（IAM）を使用する場合は、ncp_iam_ で始まるキーが発行されます。

NCloud Exporter インストール

Exporter ダウンロード

システムアーキテクチャに合ったバイナリをダウンロードします。

# 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

特定のバージョンを指定する場合は、latest の代わりにバージョンを入力します。

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

実行権限の付与およびインストール

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

config.yml ファイル設定

サポートサービス一覧

Namespace	NCP サービス
`ncloud.vserver`	VPC Server
`ncloud.vloadbalancer`	VPC Load Balancer
`ncloud.vautoscaling`	VPC Auto Scaling
`ncloud.vmysql`	Cloud DB for MySQL
`ncloud.vpostgresql`	Cloud DB for PostgreSQL
`ncloud.vredis`	Cloud DB for Redis
`ncloud.vmongodb`	Cloud DB for MongoDB
`ncloud.vmssql`	Cloud DB for MSSQL
`ncloud.vnks`	Ncloud Kubernetes Service
`ncloud.vsearchengine`	Search Engine Service
`ncloud.vhadoop`	Cloud Hadoop

config.yml サンプルファイル

/etc/ncloud_exporter/config.yml のパスに設定ファイルを作成します。以下は VPC Server を収集する基本構成です。

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

namespaces:
  - name: "ncloud.vserver"
    enabled: true
    regions: ["KR"]          # 空の配列の場合は全リージョン
    interval: "Min5"         # Min1 | Min5 | Min30 | Hour2 | Day1
    aggregations: ["AVG"]    # 以下 metrics の既定 aggregation
    metrics:
      # CPU
      - name: "avg_cpu_used_rto"     # CPU 使用率（%）
      - name: "max_cpu_used_rto"     # CPU 使用率ピーク（%）
        aggregations: ["MAX"]
      - name: "load_average_1m"
      - name: "load_average_5m"
      - name: "load_average_15m"

      # メモリー
      - name: "mem_usert"            # メモリー使用率（%）
        aggregations: ["AVG", "MAX"]
      - name: "swap_usert"           # swap 使用率（%）

      # ファイルシステム
      - name: "avg_fs_usert"
      - name: "max_fs_usert"
        aggregations: ["MAX"]

      # ネットワーク
      - name: "avg_rcv_bps"          # 受信（bits/sec）
      - name: "avg_snd_bps"          # 送信（bits/sec）

      # ディスク 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: []

設定項目

項目	説明	既定値
`ncloud.access_key`	NCP API Access Key	（必須）
`ncloud.secret_key`	NCP API Secret Key	（必須）
`namespaces[].name`	収集するサービスのネームスペース	-
`namespaces[].enabled`	収集の有効化有無	`false`
`namespaces[].regions`	対象リージョン（空の配列の場合は全体）	`[]`
`namespaces[].interval`	照会間隔（`Min1`～`Day1`）	`Min5`
`namespaces[].aggregations`	ネームスペースの既定 aggregation	（API 提供分すべて）
`namespaces[].metrics`	収集するメトリクス一覧	（省略時はすべて）

注意

metrics を指定しない場合、該当サービスの すべてのメトリクス × すべての aggregation を収集します。VPC Server の場合はインスタンス 1 台あたり 125 個のシリーズが生成されるため、必要なメトリクスのみを指定してください。上記のサンプル設定では、インスタンスあたり 16 個のシリーズを収集します。

サービス別のメトリクス一覧は VPC Server 基本メトリクスをご参照ください。

認証情報を環境変数で指定

設定ファイルにキーを平文で保存したくない場合は、環境変数を使用します。環境変数は設定ファイルの値より優先して適用されます。

環境変数	説明
`NCLOUD_ACCESS_KEY`	`ncloud.access_key` を上書き
`NCLOUD_SECRET_KEY`	`ncloud.secret_key` を上書き
`NCLOUD_CW_API_GW`	Cloud Insight エンドポイント（既定 `https://cw.apigw.ntruss.com`）
`NCLOUD_API_GW`	NCloud API GW エンドポイント（既定 `https://ncloud.apigw.ntruss.com`）

サービス登録および実行

実行オプション

フラグ	説明	既定値
`--config`	設定ファイルのパス	`config.yml`
`--web.listen-address`	HTTP リスナーアドレス	`:9850`
`--web.telemetry-path`	メトリクスエンドポイントのパス	`/metrics`
`--log.level`	ログレベル（`debug`、`info`、`warn`、`error`）	`info`
`--log.format`	ログフォーマット（`text`、`json`）	`text`

方法 A: systemd サービス登録

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

登録後、サービスを開始します。

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

Tips

設定ファイルを修正した後は、再起動せずに sudo systemctl reload ncloud-exporter で反映できます。認証情報、ネームスペース、メトリクスの選択が再読み込みされます。ただし、リスナーアドレスとパスは実行引数であるため、変更する場合は再起動が必要です。

方法 B: nohup 実行

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

メトリクス収集の確認およびトラブルシューティング

メトリクスの確認

curl http://localhost:9850/metrics

# 特定のサービスのみ確認
curl -s http://localhost:9850/metrics | grep '^ncloud_vserver'

正常な出力例

# 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

Exporter 自体の状態は、以下のメトリクスで確認します。

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

メトリクス名の変換ルール

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

service: ネームスペースから ncloud. プレフィックスを除いた値（ncloud.vserver → vserver）
metric: Cloud Insight のメトリクス名（avg_cpu_used_rto）
aggregation: 小文字に変換した集計方式（avg、max、min、sum、count）

例: ncloud.vserver + avg_cpu_used_rto + AVG → ncloud_vserver_avg_cpu_used_rto_avg

トラブルシューティング

症状	原因	解決方法
`failed to initialize cw_keys` ログとともに起動失敗、`status 401 Authentication Failed`	Access Key / Secret Key の誤り、または権限不足	キーの値を確認し、該当キーに Cloud Insight の照会権限があるか点検します。
`read config file: open config.yml: no such file or directory`	設定ファイルのパス誤り	`--config` に絶対パスを指定します。
`unknown aggregation "..."` または `unknown interval "..."` で起動失敗	設定ファイルの誤字	`aggregations` は `AVG`/`MAX`/`MIN`/`SUM`/`COUNT`、`interval` は `Min1`/`Min5`/`Min30`/`Hour2`/`Day1` のみ許容されます。
`WARN configured metric matched no available metric`	存在しないメトリクス名を指定	メトリクス一覧で実際のメトリクス名を確認します。
`WARN some configured aggregations are not supported`	該当メトリクス・interval がサポートしない aggregation	ログの `available` 一覧にある値に修正します。
`/metrics` に `ncloud_` メトリクスがない	該当リージョンにインスタンスがない、または `enabled: false`	`regions` 設定と `enabled` の値を確認します。リージョンを特定しない場合は `regions: []` のままにします。
特定のメトリクスのみ値が空	Cloud Insight の収集遅延、または該当インスタンスが未提供	サーバーにモニタリングエージェントがインストールされているか確認します。直近 10 分以内のデータがない場合、時系列は生成されません。
`ncloud_scrape_errors_total` の値が増加し続ける	API 呼び出しの失敗	`--log.level=debug` で実行し、失敗したネームスペースと原因を確認します。

Tips

設定を検証する際は、--log.level=debug で実行してください。選択されたメトリクス、マッチングに失敗した設定、API エラーがすべてログに出力されます。

OpenAgent ダウンロードおよび設定

すべてのファイルは同じディレクトリに配置する必要があります。

ディレクトリ構造
/opt/whatap/openagent/
├── openagent           # Executable file
├── whatap.conf         # Configuration file
└── scrape_config.yaml  # Scraping configuration file

ダウンロードおよび権限設定

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

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

注意

Cloud Insight の最小収集周期は 5 分 です。

interval をそれより短く設定しても同じ値が繰り返し収集されるだけで、API 呼び出し量のみが増加します。300s 以上を推奨します。

設定要素

項目	説明
`targetName`	収集対象の名前
`type`	`StaticEndpoints` 固定
`address`	Exporter のアドレス（`ホスト:ポート`）
`path`	メトリクスのパス（既定 `/metrics`）
`scheme`	`http` または `https`
`interval`	収集周期（`300s` 推奨）
`metricRelabelConfigs`	収集するメトリクスのフィルタリングおよびラベル変更

メトリクスフィルタリングの例

1. Exporter のすべてのメトリクスを収集

注意

Go ランタイムメトリクス（go_*、process_*）まで含まれるため、推奨しません。

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

2. NCloud メトリクスのみ収集（推奨）

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

3. 特定サービスの CPU・メモリーのみ収集

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

4. 静的ラベルの追加

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

実行

# 基本実行
./openagent standalone

# バックグラウンド実行
nohup ./openagent standalone > /dev/null 2>&1 &

# ログ確認
tail -f logs/whatap-boot-$(date +%Y%m%d).log

# プロセスの確認および終了
ps aux | grep openagent
pkill openagent

VPC Server 基本メトリクス`ダッシュボード設置ページ専用`

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	未サポート（Min1 専用）	-	instanceNo (type=fs, mnt_nm=/)	X	STRING タイプのため、指定しても時系列は生成されません。
`mnt_stat_cd`	Mount state	未サポート（Min1 専用）	-	instanceNo (type=fs, mnt_nm=/)	X	`interval: Min1` でのみ使用できます。

事前準備​

NCP アカウントおよび権限要件​

必要な情報の収集​

NCloud Exporter インストール​

Exporter ダウンロード​

実行権限の付与およびインストール​

config.yml ファイル設定​

サポートサービス一覧​

config.yml サンプルファイル​

設定項目​

認証情報を環境変数で指定​

サービス登録および実行​

実行オプション​

方法 A: systemd サービス登録​

方法 B: nohup 実行​

メトリクス収集の確認およびトラブルシューティング​

メトリクスの確認​

正常な出力例​

メトリクス名の変換ルール​

トラブルシューティング​

OpenAgent ダウンロードおよび設定​

ダウンロードおよび権限設定​

scrape_config.yaml の作成​

設定要素​

メトリクスフィルタリングの例​

実行​

VPC Server 基本メトリクスダッシュボード設置ページ専用​

事前準備

NCP アカウントおよび権限要件

必要な情報の収集

NCloud Exporter インストール

Exporter ダウンロード

実行権限の付与およびインストール

config.yml ファイル設定

サポートサービス一覧

config.yml サンプルファイル

設定項目

認証情報を環境変数で指定

サービス登録および実行

実行オプション

方法 A: systemd サービス登録

方法 B: nohup 実行

メトリクス収集の確認およびトラブルシューティング

メトリクスの確認

正常な出力例

メトリクス名の変換ルール

トラブルシューティング

OpenAgent ダウンロードおよび設定

ダウンロードおよび権限設定

scrape_config.yaml の作成

設定要素

メトリクスフィルタリングの例

実行

VPC Server 基本メトリクス`ダッシュボード設置ページ専用`