OpenAgent 設定

OpenAgentはPrometheusエンドポイントからメトリクスを収集してWhaTapサーバーに送信するエージェントです。エージェント動作に必要な設定は2つのファイルに分離されています。

whatap.conf: エージェントの基本設定（ライセンス、サーバーアドレス、ログレベルなど）
scrape_config.yaml: 収集ターゲット（Prometheusエンドポイント）の定義

エージェントは環境変数を通じて設定ファイルの場所を把握してロードします。別途設定がない場合、エージェントは現在の実行ディレクトリでwhatap.confファイルを探します。5秒に1回whatap.confファイルの変更有無をチェックしてリロードするため、エージェントを再起動せずにほとんどの設定変更を適用できます。

ユーザーの利便性のため、WhaTapモニタリングサービスでもエージェント設定機能を提供しています。

ノート

OpenAgentのインストール方法はOpenAgentインストールドキュメントを参照してください。

基本設定

whatap.conf

OpenAgentは最低限ライセンスキーとサーバーアドレスが設定されていないと動作しません。

license=xxxxxxxxxxxxx-xxxxxxxxxx-xxxxxxxxxxxxx
whatap.server.host=10.10.0.1
whatap.server.port=6600

# ログレベル: DEBUG(0), INFO(1), WARN(2), ERROR(3)
log_level=INFO
debug=false

OpenAgentは同じ設定値を複数のキー形式で受け取れるようにサポートしています。環境変数とwhatap.confのどちらにも設定でき、設定ファイルの値が優先適用され、ない場合は環境変数の値を使用します。

Setting	Key	Environment Variable	Default
ライセンスキー	license, WHATAP_LICENSE	WHATAP_LICENSE	（必須）
サーバーホスト	whatap.server.host, WHATAP_HOST	WHATAP_HOST, WHATAP_SERVER_HOST	（必須）
サーバーポート	whatap.server.port, WHATAP_PORT	WHATAP_PORT, WHATAP_SERVER_PORT	6600
エージェント名	whatap.oname, app_name	WHATAP_ONAME	自動生成

設定ファイルパス

OpenAgentは以下の環境変数を使用して設定ファイルの場所とエージェントホームディレクトリを識別します。

WHATAP_HOME: whatap.confファイルが存在するディレクトリ。デフォルト値は現在のディレクトリ（.）
WHATAP_OPEN_HOME: OpenAgentの実行ホームディレクトリ（ログファイルなどの保存場所）

環境変数が設定されていない場合、エージェントが実行中のディレクトリを基準にwhatap.confファイルを探します。

export WHATAP_HOME=/app/whatap
export WHATAP_OPEN_HOME=/app/whatap
./openagent

サーバー接続およびデータ送信

OpenAgentはwhatap.confに設定したサーバーアドレスにTCPセッションを接続します。

whatap.server.host=10.10.1.1
whatap.server.port=6600

TCPセッションを接続するとlicenseを使用してサーバーから通信キーを受け取ります。誤ったlicenseを設定するとサーバーはセッションを終了します。
TCP接続が繰り返し終了する場合はファイアウォールの問題を確認するか、license値が正しいか確認してください。
TCPセッションを接続するとサーバーから受け取った秘密鍵をベースにセキュア通信でデータを送信します。
複数のサーバーアドレスを/または,で区切って列挙するとフェイルオーバー用として使用します。

whatap.server.host=10.10.1.1/10.10.1.2

ログレベル設定

ログはlog_levelまたはdebug設定で制御できます。両方の設定がある場合はlog_levelが優先されます。

log_level=INFO   # DEBUG(0) | INFO(1) | WARN(2) | ERROR(3)
debug=false      # trueに設定するとDEBUGレベルで動作

ログレベルもwhatap.confリロードの対象のため、エージェントの再起動なしに変更が反映されます。

スクレイピングターゲット設定 (scrape_config.yaml)

OpenAgentのコア動作であるPrometheusエンドポイント収集は$WHATAP_HOME/scrape_config.yamlファイルで定義します。以下の3種類のターゲットタイプをサポートしています。

PodMonitor: Podラベルセレクターを使用した動的ディスカバリー（Kubernetes）
ServiceMonitor: Serviceラベルセレクターを使用した動的ディスカバリー（Kubernetes）
StaticEndpoints: 固定IPアドレスとポートを直接入力

scrape_config.yamlファイルは修正時に自動的に変更が検知され、エージェントの再起動が不要です。

StaticEndpoints 基本例

features:
  openAgent:
    enabled: true
    targets:
      - targetName: dcgm-exporter
        type: StaticEndpoints
        enabled: true
        endpoints:
          - address: "192.168.49.2:30400"
            path: "/metrics"
            scheme: "http"
            interval: "30s"
            metricRelabelConfigs:
              - source_labels: [__name__]
                regex: "DCGM.*"
                action: keep

PodMonitor例（Kubernetes）

features:
  openAgent:
    enabled: true
    globalInterval: "60s"
    globalPath: "/metrics"
    targets:
      - targetName: my-app-pod-metrics
        type: PodMonitor
        namespaceSelector:
          matchNames: ["production"]
        selector:
          matchLabels:
            app: my-app
        endpoints:
          - port: "web-metrics"
            path: "/metrics"
            interval: "15s"
            scheme: "http"
            timeout: "10s"

StaticEndpoints 設定要素

Option	Description
`targetName`	ターゲット識別子
`type`	ターゲットタイプ（"StaticEndpoints"）
`address`	IP:PORT または HOSTNAME:PORT
`path`	メトリクスパス（デフォルト: /metrics）
`scheme`	プロトコル（http または https、デフォルト: http）
`interval`	収集周期（デフォルト: 60s）
`metricRelabelConfigs`	メトリクス再ラベリング設定

params クエリパラメーター設定

HTTPスクレイピング時にURLにクエリパラメーターを追加できます。Azure Monitor Exporterなど外部サービス連携時に有用です。

Azure Monitor スタイル例

endpoints:
  - address: "192.168.49.2:30400"
    path: "/metrics"
    scheme: "http"
    interval: "30s"
    params:
      subscription: ["50d91b57-a280-45b5-8d7c-be8005662738"]
      resourceGroup: ["WhaTap-Data-KR-MID"]
      target: ["/subscriptions/50d91b57-a280-45b5-8d7c-be8005662738/resourceGroups/WhaTap-Data-KR-MID/providers/Microsoft.Sql/managedInstances/openmetrics-instance-01"]
      metric: ["avg_cpu_percent,virtual_core_count,memory_usage_percent"]
      interval: ["PT1M"]
      aggregation: ["average"]

シンプルなパラメーター例

params:
  format: "prometheus"
  version: "v1"
  debug: true

メトリクス再ラベリング (metricRelabelConfigs)

Prometheusのmetric_relabel_configsに類似したメトリクス再ラベリング機能を提供します。

項目	説明
source_labels	ソースラベルのリスト（配列）
separator	ソースラベル値の連結区切り文字（デフォルト: `;`）
target_label	対象ラベル
regex	ソースラベルに適用する正規表現
replacement	置換値（正規表現キャプチャグループ参照可能: `${1}`）
action	実行アクション（keep、drop、replace）

サポートアクションタイプ

keep: 正規表現に一致するメトリクスのみ保持
drop: 正規表現に一致するメトリクスを削除
replace: 対象ラベルの値を置換値に変更

特殊ラベル

__name__: メトリクス名を表す特殊ラベル

再ラベリング例

例1: すべてのメトリクスを収集

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

例2: 特定のメトリクスのみ保持

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "http_requests_total"
    action: keep

結果: http_requests_totalメトリクスのみ保持され、残りは削除されます。

例3: 正規表現を使用したフィルタリング

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "node_(cpu|memory).*"
    action: keep

結果: node_cpuまたはnode_memoryで始まるメトリクスのみ保持されます。

例4: ラベル名の変更

metricRelabelConfigs:
  - source_labels: [method]
    target_label: http_method
    replacement: "${1}"
    action: replace

結果: methodラベルの値がhttp_methodラベルにコピーされます。

例5: 複数のソースラベルの組み合わせ

metricRelabelConfigs:
  - source_labels: [__name__, status]
    regex: "http_requests_total;(200|500)"
    action: keep

結果: http_requests_totalメトリクスのうちstatusが200または500のメトリクスのみ保持されます。

例6: 静的ラベルの追加

metricRelabelConfigs:
  - target_label: metric_src
    replacement: "whatap-open-agent"
    action: replace

結果: すべてのメトリクスにmetric_src="whatap-open-agent"ラベルが追加されます。

複数のOpenAgentインスタンスの設定ファイル管理

1つのサーバーで複数のOpenAgentインスタンスを運用する必要がある場合、各インスタンスごとにホームディレクトリを分離してWHATAP_HOME環境変数を異なる値に指定します。

# インスタンスA
WHATAP_HOME=/app/whatap/serviceA ./openagent standalone

# インスタンスB
WHATAP_HOME=/app/whatap/serviceB ./openagent standalone

各ホームディレクトリに別々のwhatap.confとscrape_config.yamlを配置すると、インスタンスごとに独立した設定を維持できます。

pprofプロファイリングエンドポイント

パフォーマンス分析が必要な場合、pprof HTTPサーバーを通じてランタイム情報を確認できます。

export PPROF_PORT=6060   # デフォルト: 6060
./openagent standalone

使用可能なエンドポイントは以下のとおりです。

http://localhost:6060/debug/pprof/profile - CPUプロファイル
http://localhost:6060/debug/pprof/heap - Heapプロファイル
http://localhost:6060/debug/pprof/goroutine - Goroutineプロファイル

サービス画面でエージェントを設定する

管理 > エージェント設定

モニタリング対象サーバーに位置するwhatap.confファイルを直接修正せずに、WhaTapモニタリングサービスでエージェント設定オプションを追加、修正、削除できます。また、設定ファイルダウンロードボタンをクリックしてwhatap.confファイルをダウンロードできます。

この機能は修正権限を持つメンバーのみ利用できます。修正権限のないメンバーは設定内容を照会のみできます。
オプション値として設定できる形式は以下のとおりです。
- Boolean形式の値はtrueまたはfalseを選択してください。
- 数値形式の値は数値のみ入力できます。
- テキスト（String）形式の値を入力または修正する場合は、オプションの説明を詳しく確認してください。

追加、修正、削除したオプションによってエージェントを再起動する必要がある場合があります。OpenAgentの場合、ほとんどのwhatap.conf値は5秒以内に自動リロードされます。

オプションを追加する

openagent オプション追加

エージェントリストからオプションを追加したいエージェントを選択してください。
オプション作成で追加するオプション項目を選択してください。
- 検索から追加するオプションを見つけることができます。テキストを入力すると一致するオプションをフィルタリングします。
- 直接入力を選択するとオプションキーと値を入力できます。
選択したオプションキーの説明とデフォルト値を確認してから設定値を入力してください。
希望するすべてのオプションを追加したら、画面右上の適用ボタンを選択してください。

注意

オプション値に何も入力しない状態で適用ボタンを選択すると、そのオプションを削除します。すでに追加したオプションはオプションリストで選択できません。アプリケーションの種類およびエージェントバージョンによって適用できるオプションキーは異なる場合があります。

オプションを修正または削除する

openagent オプション修正または削除

画面を上下にスクロールするか、オプションリストから修正または削除するオプションを選択してください。
変更するオプションで希望する値を選択するか修正してください。オプションを削除するには削除アイコンボタンを選択してください。
変更した内容を適用するには適用ボタンを選択してください。

複数のエージェントに同時適用する

プロジェクトに属する複数のOpenAgentに変更したオプションを同時に適用できます。

画面右上の複数エージェント適用チェックボックスを選択すると、各オプション項目にチェックボックスが生成されます。
同時に適用したいオプションのチェックボックスを選択してください。
画面右上の適用ボタンを選択してください。
エージェント適用ウィンドウが表示されたら、変更したオプションを適用するエージェントを選択してから適用ボタンを選択してください。

エージェント設定オプション案内

OpenAgentで使用できる主要なwhatap.confオプションは以下のとおりです。

Option	Type	Default	Description
`license` / `WHATAP_LICENSE`	`string`	（必須）	WhaTapプロジェクトライセンスキー
`whatap.server.host` / `WHATAP_HOST`	`string`	（必須）	WhaTap収集サーバーアドレス。`/`または`,`で複数指定可能
`whatap.server.port` / `WHATAP_PORT`	`integer`	6600	WhaTap収集サーバーポート
`whatap.oname` / `WHATAP_ONAME`	`string`	自動生成	エージェントのオブジェクト名
`app_name`	`string`	-	whatap.oname未設定時の代替として使用
`debug`	`boolean`	false	デバッグログの有効化
`log_level`	`string` / `integer`	INFO	ログレベル（DEBUG / INFO / WARN / ERROR または 0〜3）
`tag_counter_enabled`	`boolean`	false	OpenMetricsプロジェクトを別途製品として使用する際に有効化
`scrape_interval`	`string`	60s	スクレイピング全体のデフォルト周期（scrape_config.yamlのglobalIntervalとは別の後方互換キー）
`scrape_timeout`	`string`	-	スクレイピング全体のデフォルトタイムアウト

Tips

tag_counter_enabledオプションはOpenMetricsプロジェクトが他のWhaTap製品と連携せず、別途製品として運用される場合にのみtrueに設定してください。デフォルト構成では使用しません。

ノート

アプリケーションの種類およびエージェントのバージョンによって適用できるオプションキーは異なる場合があります。収集ターゲット設定に関連するオプションは上記のスクレイピングターゲット設定セクションを参照してください。

基本設定​

whatap.conf​

設定ファイルパス​

サーバー接続およびデータ送信​

ログレベル設定​

スクレイピングターゲット設定 (scrape_config.yaml)​

StaticEndpoints 基本例​

PodMonitor例（Kubernetes）​

StaticEndpoints 設定要素​

params クエリパラメーター設定​

メトリクス再ラベリング (metricRelabelConfigs)​

再ラベリング例​

複数のOpenAgentインスタンスの設定ファイル管理​

pprofプロファイリングエンドポイント​

サービス画面でエージェントを設定する​

オプションを追加する​

オプションを修正または削除する​

複数のエージェントに同時適用する​

エージェント設定オプション案内​