Prometheusとの統合

EMQXは、Prometheusなどのサードパーティ監視システムとの統合をサポートしています。PrometheusはSoundCloudによってオープンソース化された監視ソリューションで、多次元データモデルのサポート、柔軟なクエリ言語、強力なアラーム管理など多彩な機能を提供します。

サードパーティ監視システムを利用することで、以下のような利点があります。

• EMQXの監視データを他のシステムの監視データと統合した、包括的な監視システムを構築可能。例えば、サーバーホストの監視情報も取得できます。
• Grafanaダッシュボードなどを使って、図やグラフによるより直感的な監視レポートが得られます。
• Prometheus Alertmanagerを利用したアラームルールや通知方法の設定など、多様なアラーム通知オプションを利用できます。

EMQXはPrometheusのメトリクス監視統合に対して、以下の2つの方法をサポートしています。

• Pullモード: PrometheusがEMQXのREST APIを通じて直接メトリクスを収集します。
• Pushモード: EMQXがメトリクスをPushgatewayサービスにプッシュし、Prometheusがそこからメトリクスを収集します。

本ページでは両モードの設定手順を紹介します。EMQXダッシュボードの左側ナビゲーションメニューで Management -> Monitoring をクリックし、Integration タブで Prometheus を選択して設定を行えます。また、ページ内の Help ボタンをクリックすると、各モードの具体的な設定手順を確認できます。

Pullモード統合の設定

EMQXはPrometheusがシステムメトリクスを収集するために、以下のREST APIを提供しています。

• /api/v5/prometheus/stats: EMQXの基本的なメトリクスとカウンター。
• /api/v5/prometheus/auth: 認証・認可を含むアクセス制御に関する主要なメトリクスとカウンター。
• /api/v5/prometheus/data_integration: ルールエンジン、コネクター、アクション、Sink/Source、エンコード/デコードに関するメトリクスとカウンター。

これらのAPIを呼び出してメトリクスを取得する際、URLクエリパラメータ mode を用いて異なるタイプのメトリクスデータを取得できます。パラメータの意味は以下の通りです。

mode=node

デフォルトモードで、現在のリクエストノードのメトリクスを返します。特に指定がない場合はこのモードが適用されます。

mode=all_nodes_aggregated

クラスターのメトリクスを集約し、クラスター内のすべての稼働ノードのメトリクスの算術和または論理和を返します。

• 「オン状態」や「稼働状態」などのメトリクスは論理和を返します。すべてのノードがオンまたは稼働中なら1を返し、それ以外は0を返します。

• CPUやメモリ使用率などノードごとに独立したメトリクスは集約値を返しません。ノード名をラベルとして付与し、異なるノードのメトリクスを区別します。例：

  emqx_vm_cpu_use{node="emqx@172.17.0.2"} 7.6669163995887715
  emqx_vm_cpu_idle{node="emqx@172.17.0.2"} 92.33308360041123
  
  emqx_vm_cpu_use{node="emqx@172.17.0.3"} 7.676007766679973
  emqx_vm_cpu_idle{node="emqx@172.17.0.3"} 92.32399223332003

• クラスター内のどのノードでも値が一貫しているべきメトリクスは、APIリクエストを受けたノードの値を直接返します。これらは合算されず、ノード名のラベルも付きません。例：

  emqx_topics_count 3
  emqx_cert_expiry_at{listener_type="ssl",listener_name="default"} 1904285225
  emqx_cert_expiry_at{listener_type="wss",listener_name="default"} 1904285225

• その他のメトリクスは算術和を返します。すなわち、返されるメトリクスは全ノードのメトリクスの合計です。

mode=all_nodes_unaggregated

クラスター非集約メトリクスモードで、クラスター内のすべての稼働ノードの個別メトリクスを返します。

• ノード名をラベルとして付与し、異なるノードのメトリクスを区別します。例：

  emqx_connections_count{node="emqx@127.0.0.1"} 0

• 「ブラックリスト数」や「保持メッセージ数」など、クラスター内のどのノードでも値が一貫しているべきメトリクスは、APIリクエストを受けたノードの値を直接返します。ノード名のラベルは付きません。例：

  emqx_retained_count 3

PrometheusのPullエンドポイントの詳細は、EMQX Enterprise APIドキュメントを参照してください。

TIP

デフォルトではPullモードAPIは認証不要です。ページ上の Enable Basic Auth スイッチを設定すると、インターフェースにベーシック認証を有効化できます。有効化後は、EMQXでAPIキーを作成し、Prometheus設定に適用してメトリクスを取得する必要があります。

参考用Prometheus設定例

# prometheus.yaml
global:
  scrape_interval:     10s # デフォルトのスクレイプ間隔は10秒ごとです。
  evaluation_interval: 10s # デフォルトの評価間隔も10秒ごとです。
  # このマシン上のすべての時系列がデフォルトでエクスポートされます。
  external_labels:
    monitor: 'emqx-monitor'
scrape_configs:
  - job_name: 'emqx_stats'
    static_configs:
      - targets: ['127.0.0.1:18083']
    metrics_path: '/api/v5/prometheus/stats'
    scheme: 'http'
    basic_auth:
      username: ''
      password: ''

  - job_name: 'emqx_auth'
    static_configs:
      - targets: ['127.0.0.1:18083']
    metrics_path: '/api/v5/prometheus/auth'
    scheme: 'http'
    basic_auth:
      username: ''
      password: ''

  - job_name: 'emqx_data_integration'
    static_configs:
      - targets: ['127.0.0.1:18083']
    metrics_path: '/api/v5/prometheus/data_integration'
    scheme: 'http'
    basic_auth:
      username: ''
      password: ''

Pushモード統合の設定

EMQXはメトリクスをPushgatewayにプッシュし、Prometheusがそこからメトリクスを収集する方式をサポートしています。Pushgatewayサービスはデフォルトで無効化されています。ダッシュボードのPrometheus設定ページで Enable Pushgateway トグルスイッチをクリックすると有効化できます。

ビジネス要件に応じて以下の項目を設定し、Save Changes をクリックしてください。

• Interval: メトリクスデータをPushgatewayに報告する時間間隔を指定します。デフォルトは15秒です。
• Pushgateway Server: PrometheusサーバーのURLを入力します。デフォルトは http://127.0.0.1:9091 です。
• Job Name: EMQXクラスター名、ノード名、ホスト名を含む変数を指定します。デフォルトは ${name}/instance/${name}~${host} です。例えば、EMQXノード名が emqx@127.0.0.1 の場合、name は emqx、host は 127.0.0.1 になります。
• Headers: Pushgatewayにプッシュする監視メトリクスのHTTPヘッダーのキーと値を入力します。Add ボタンをクリックして複数のヘッダーを追加可能です。型は文字列で、例として { Authorization = "some-authz-tokens" } のように設定します。

同時に、Help ボタンをクリックし、Use Pushgateway タブの手順を参照して設定を行うこともできます。

TIP

Pushモードでは現状、/api/v5/prometheus/stats エンドポイントのEMQX基本メトリクスとカウンターのみが含まれるため、Pullモードの利用を推奨します。

Pushgatewayの有効化および設定は、設定ファイルに以下の内容を追加することでも可能です。設定項目の詳細はConfiguration - Prometheusを参照してください。

prometheus {
  push_gateway_server = "http://127.0.0.1:9091"
  interval = 15s
  headers {}
  job_name = "${name}/instance/${name}~${host}"
}

GrafanaでEMQXメトリクスを可視化する

GrafanaとPrometheusを組み合わせてEMQXメトリクスを可視化することも可能です。これはEMQXのテンプレートファイルをGrafanaにインポートすることで実現できます。テンプレートのダウンロードは、EMQX | Grafana Dashboard をクリックするか、Monitoring ページの Integration タブ下部の Help ボタンから行えます。

TIP

詳細な操作手順は Monitoring MQTT broker with Prometheus and Grafana をご覧ください。