PrometheusでEMQXをモニタリングする

EMQXは、Prometheusがクエリ、アラート、可視化のために収集できるランタイムメトリクスを公開しています。これらのメトリクスは、以下のいずれかの方法で収集できます。

• プルモード（推奨）：PrometheusがREST APIエンドポイントから直接EMQXのメトリクスをスクレイプします。このモードを使用すると、利用可能なメトリクスの完全なセットを収集できます。
• プッシュモード：EMQXが基本的なメトリクスをPushgatewayに送信し、PrometheusがPushgatewayからそれらをスクレイプします。PrometheusがEMQXに直接接続できない場合にこのモードを使用します。

収集したEMQXメトリクスは、Grafanaを使って可視化できます。

TIP

EMQX 6.3.0以降、Prometheusメトリクスはmetrics機能ゲートで制御されます。EMQX_FEATURESを手動で設定する場合、metricsを有効にすると、その依存であるdashboardも有効になります。認証と認可はコア機能であり、機能ゲートで制御されません。詳細は機能ゲートをご覧ください。

EMQXでのメトリクス収集の設定

DashboardのPrometheus統合ページで、認証、Pushgatewayへの送信、レイテンシーバケット、ネームスペースのリクエスト制限を制御できます。このセクションでは各設定項目の内容を説明します。プルモードおよびプッシュモードの設定手順は後述します。

Prometheus統合設定を開くには：

1. EMQX DashboardのManagement -> Monitoringに移動します。
2. Integrationタブを選択します。
3. Prometheusを選択します。

以下のエンドポイントで公開されるメトリクスシリーズの厳選されたリファレンス（アラートに適したものを含む）は、Broker Health Indicatorsをご覧ください。

スクレイプリクエストの認証を必須にする

Enable Basic Authは、/api/v5/prometheus/*以下のすべてのPrometheusスクレイプAPIの認証を制御します。Dashboardのラベルにかかわらず、この設定はHTTP Basic認証とBearer認証の両方を制御します。

EMQX 6.3.0以降、認証はデフォルトで有効です。認証情報なしのリクエストは401を返します。PrometheusはAPIキーとシークレットキーを用いたHTTP Basic認証を使用できます。EMQXはDashboardのログイントークンをBearerトークンとしても受け入れますが、トークンは期限切れになるため、継続的なスクレイプには適しません。

長時間稼働するPrometheusサーバーの場合は、monitoringスコープの専用APIキーを作成し、Prometheusのスクレイプリクエスト認証を設定してください。

認証なしのスクレイプを許可するには、Enable Basic Authをオフにするか、prometheus.enable_basic_auth = falseに設定します。この設定はプルモードにのみ影響し、Pushgatewayへの送信には影響しません。

重要なお知らせ

認証を無効にすると、Dashboardリスナーにアクセス可能な任意のクライアントがEMQXメトリクスをスクレイプ可能になります。アップグレード後、明示的にprometheus.enable_basic_auth = falseに設定された構成や旧形式のPrometheus構成は、認証なしスクレイプを継続して許可します。アップグレード後はDashboardでEnable Basic Authを必ず確認してください。

Pushgatewayへのメトリクス送信を設定する

Enable Pushgatewayをオンにすると、EMQXがPushgatewayインスタンスにメトリクスを送信します。プッシュ送信はデフォルトで無効です。以下の項目を設定してください。

項目	説明
Interval	EMQXがメトリクスをプッシュする間隔。デフォルトは15秒です。
Pushgateway Server	PushgatewayのURL。デフォルトはhttp://127.0.0.1:9091です。
Job Name	プッシュされるメトリクスのジョブラベル。デフォルトは${name}/instance/${name}~${host}で、${name}は@の前のノード名、${host}は@の後のホスト名です。例えばemqx@127.0.0.1の場合、emqxと127.0.0.1になります。
Headers	Pushgatewayに送信する任意のHTTPヘッダー。各ヘッダーはキーと値のペアで追加します。例：Authorization = "some-auth-token"

完全な手順はPushgatewayへのメトリクス送信設定をご覧ください。

レイテンシーヒストグラムのバケットを定義する

Latency Bucketsには、カンマ区切りの期間値を入力します。例：

10ms, 100ms, 1s, 5s, 30s

これらの値はプルモード・プッシュモード両方のレイテンシーヒストグラムのバケット境界を定義します。バケット数が多いほど粒度は細かくなりますが、メトリクスのカーディナリティとストレージ使用量が増加する可能性があります。

すべてのネームスペースをスクレイプするリクエストの制限

Namespace Data Scraping Rate Limitは、すべてのネームスペースにまたがるメトリクススクレイプリクエストの最大レートを設定します。特定のネームスペースを指定したリクエストは制限されません。<requests>/<duration>形式で値を入力します。デフォルトの1/5sは5秒ごとに1リクエストを許可し、それ以外のリクエストは拒否されます。

PrometheusでEMQXメトリクスをスクレイプする設定

プルモードでは、PrometheusがEMQX Dashboardリスナーに接続し、1つ以上のREST APIエンドポイントをスクレイプします。

スクレイプするメトリクスエンドポイントの選択

収集したいメトリクスカテゴリごとにPrometheusのスクレイプジョブを追加します。

エンドポイント	メトリクス内容
/api/v5/prometheus/stats	基本的なEMQXメトリクスとカウンター
/api/v5/prometheus/namespaced_stats	ネームスペースごとに集約されたメトリクス
/api/v5/prometheus/auth	認証、認可、禁止クライアントのメトリクス
/api/v5/prometheus/data_integration	ルール、コネクター、アクション、Sink/Source、エンコード/デコードのメトリクス
/api/v5/prometheus/schema_validation	スキーマ検証のメトリクス
/api/v5/prometheus/message_transformation	メッセージ変換のメトリクス
/api/v5/prometheus/topic_metrics	トピックメトリクス収集のカウンター

完全なAPIリファレンスはEMQX Enterprise APIドキュメントをご覧ください。

ネームスペースごとのデータ統合メトリクスのスクレイプ

EMQX 6.3.0以降、GET /api/v5/prometheus/data_integrationは認証ユーザーのネームスペースに応じてルール、アクション、コネクターメトリクスを制限します。

• ネームスペースユーザーは割り当てられたネームスペースのメトリクスのみ受け取ります。ns=<namespace>で別のネームスペースを指定すると403が返されます。
• グローバル管理者はデフォルトで全ネームスペースのメトリクスを受け取ります。ns=<namespace>で特定のネームスペースをスクレイプ、またはonly_global=true（nsなし）でグローバルネームスペースのみをスクレイプできます。
• 認証が無効の場合、グローバル管理者と同様の可視性が適用され、デフォルトで全ネームスペースのメトリクスが返されます。

グローバル以外のネームスペースのルール、アクション、コネクターのリソース単位メトリクスにはnamespaceラベルが付きます。グローバルネームスペースのリソース単位メトリクスにはこのラベルは付きません。emqx_schema_registrys_countメトリクスはスキーマレジストリリソースがネームスペースでスコープされないためクラスター全体のままです。

すべてのネームスペースをスクレイプするリクエストはNamespace Data Scraping Rate Limitの対象となります。

メトリクス収集モードの選択

対応するエンドポイントでは、modeクエリパラメータで現在のノードのメトリクスを返すかクラスター全体のメトリクスを返すかを制御できます。

mode=node

リクエストを受け取ったノードのメトリクスを返します。デフォルトモードです。

mode=all_nodes_aggregated

すべての稼働中ノードのメトリクスを以下の集約ルールで返します。

• 状態メトリクスは論理集約されます。例えば、あるメトリクスが全ノードで有効または稼働中の場合に1となり、それ以外は0です。

• CPUやメモリ使用率などノード固有のメトリクスは集約されず、nodeラベルを保持します。

  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

• クラスター全体で一貫するメトリクスはリクエストを受けたノードの値を返し、合計はせずnodeラベルも付きません。

  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

すべての稼働ノードの個別メトリクスを返します。ノード固有の値にはnodeラベルが付きます。

emqx_connections_count{node="emqx@127.0.0.1"} 0

クラスター全体で一貫するメトリクスはリクエストを受けたノードの値を返し、nodeラベルは付きません。

emqx_retained_count 3

トピックメトリクス

EMQX 6.3以降、GET /api/v5/prometheus/topic_metricsはトピックメトリクスREST APIで作成された名前付きコレクションのカウンターを公開します。このエンドポイントをスクレイプする前に、少なくとも1つのコレクションを作成してください。作成手順はREST APIによるトピックメトリクスコレクションの管理をご覧ください。

公開されるカウンターは以下の通りです。

メトリクス	説明
emqx_topic_metric_messages_in_count	コレクションフィルターにマッチするトピックにパブリッシュされたメッセージ数
emqx_topic_metric_messages_out_count	マッチしたメッセージがサブスクライバーに配信された数
emqx_topic_metric_messages_dropped_count	EMQXによってドロップされたマッチしたメッセージ数
emqx_topic_metric_bytes_in	マッチしたパブリッシュメッセージのトピックとペイロードの合計サイズ
emqx_topic_metric_bytes_out	マッチした配信メッセージのトピックとペイロードの合計サイズ

各時系列にはnameとtopic_filterラベルが付きます。ネームスペース所有のコレクションにはnamespaceラベルも付きます。mode=all_nodes_unaggregatedの場合は各時系列にnodeラベルも付きます。

すべてのトピックメトリクス値は単調増加カウンターです。rate()などのPromQL関数を使って1秒あたりのレートを計算してください。例：

rate(emqx_topic_metric_messages_in_count[5m])

重要なお知らせ

各コレクションは5つのカウンターを公開します。集約されていないモードでは、EMQXはノードごとに別々の時系列を作成します。過剰なPrometheus時系列の作成を避けるため、コレクション数を制限してください。

Prometheusスクレイプリクエストの認証設定

EMQX 6.3.0以降、PrometheusスクレイプAPIはデフォルトで認証を要求します。継続的なスクレイプには専用APIキーを用いたHTTP Basic認証を使用してください。

1. EMQXでmonitoringスコープのAPIキーを作成します。

2. prometheus.yamlの各EMQXスクレイプジョブにAPIキーとシークレットキーを追加します。

   basic_auth:
     username: '<API_KEY>'
     password: '<SECRET_KEY>'

PrometheusはDashboardのBearerトークンでも認証可能です。dashboard.password_loginがbothの場合はPOST /api/v5/loginでトークンを取得します。scram_onlyモードではSCRAMチャレンジレスポンス認証で取得します。Dashboardログイントークンは期限切れになるため、長期間稼働するPrometheusスクレイパーにはAPIキーを推奨します。

PrometheusにEMQXスクレイプジョブを追加する

以下のprometheus.yaml例は、3つの一般的なメトリクスカテゴリを収集します。ターゲットアドレスと認証情報を置き換え、必要に応じて他のメトリクスエンドポイントのジョブを追加してください。ファイル変更後はPrometheusを再起動してください。

global:
  scrape_interval: 10s
  evaluation_interval: 10s
  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: '<API_KEY>'
      password: '<SECRET_KEY>'

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

  - 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: '<API_KEY>'
      password: '<SECRET_KEY>'

  - job_name: 'emqx_topic_metrics'
    static_configs:
      - targets: ['127.0.0.1:18083']
    metrics_path: '/api/v5/prometheus/topic_metrics'
    scheme: 'http'
    basic_auth:
      username: '<API_KEY>'
      password: '<SECRET_KEY>'

EMQXでPushgatewayにメトリクスをプッシュする設定

プッシュモードは/api/v5/prometheus/statsで提供される基本的なメトリクスとカウンターのみを送信します。他のエンドポイントのメトリクスが必要な場合はプルモードを使用してください。

DashboardでPushgateway送信を有効にする

1. DashboardのPrometheus統合設定を開きます。
2. Enable Pushgatewayをオンにします。
3. Pushgatewayサーバー、プッシュ間隔、ジョブ名、および必要なHTTPヘッダーを入力します。
4. Save Changesをクリックします。

PrometheusもPushgatewayインスタンスをスクレイプするよう設定する必要があります。

設定ファイルでPushgateway送信を有効にする

代わりに、推奨されるネストされた設定をetc/base.hoconに追加します。

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

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

PrometheusがEMQXメトリクスの収集を開始したら、EMQX Grafanaダッシュボードをインポートして可視化できます。このテンプレートはDashboardのPrometheus統合のHelpページからも入手可能です。

完全な例はPrometheusとGrafanaでMQTTブローカーをモニタリングするをご覧ください。