トピックメトリクス

トピックメトリクスは、選択したMQTTトピックのメッセージアクティビティを追跡します。ダッシュボードを使って特定のトピックを監視できます。EMQX 6.3以降では、REST APIを使用してワイルドカードトピックフィルターを持つ名前付きメトリックコレクションを作成し、そのカウンターをPrometheusにエクスポートすることも可能です。

トピックメトリクスインターフェース

EMQX 6.3では、以下のトピックメトリクスインターフェースを提供しています。

インターフェース	トピック選択	メトリクス	ユースケース
ダッシュボード	`+`や`#`を含まない単一のトピック名	メッセージカウンター、レート、QoS別メトリクス	特定トピックのアクティビティを表示・診断する。
REST API	`+`や`#`を含むトピックフィルター	メッセージおよびバイトカウンター	プログラムによる監視およびPrometheus連携のための名前付きコレクションを作成する。

互換性について

/api/v5/mqtt/topic_metricsのREST APIは互換性のために引き続き利用可能ですが、EMQX 6.3以降は非推奨です。このAPIで作成された監視レコードは名前付きコレクションに移行されません。

ダッシュボードでトピックメトリクスを表示する

ダッシュボードで、診断 -> トピックメトリクスをクリックします。トピックを追加をクリックし、監視したいトピック名を入力して追加をクリックします。

例として、devices/001/statusのような特定のトピック名を入力してください。ダッシュボードは+や#を含むトピックフィルターをサポートしていません。REST APIで作成されたワイルドカードトピックメトリクスコレクションはダッシュボードに表示されません。

トピックメトリクスリストには以下の項目が含まれます：

トピック：監視対象のトピック名。
受信メッセージ：受信したメッセージの合計数と受信メッセージレート。
送信メッセージ：送信したメッセージの合計数と送信メッセージレート。
ドロップメッセージ：ドロップされたメッセージの合計数とドロップレート。
開始時刻：監視レコードが作成された時刻。
操作：
- 表示：QoSレベル別のメトリクスを表示。
- リセット：トピックのメトリクスをリセット。
- 削除：監視レコードを削除。

REST APIによるトピックメトリックコレクションの管理

EMQX 6.3以降、REST APIは名前付きトピックメトリックコレクションをサポートしています。各コレクションは独立した名前とMQTTトピックフィルターを持ちます。複数のフィルターは重複可能で、1つのメッセージはそのトピックにマッチするすべてのコレクションのカウンターをインクリメントします。

REST APIの認証についてはREST APIを参照してください。

コレクションの制限

トピックメトリックコレクションには以下の制限があります：

コレクション名は1〜64文字の英数字、アンダースコア（_）、ハイフン（-）で構成される必要があります。
トピックフィルターは有効なMQTTトピックフィルターであり、+や#を含めることができます。
クラスターあたり最大512コレクションを作成可能です。

コレクションの作成

POST /api/v5/mqtt/topic_metrics2にコレクション名とトピックフィルターを送信します。以下のリクエストは、すべてのセンサーからの温度メッセージにマッチするコレクションを作成します。

bash

curl -u '<API_KEY>:<SECRET_KEY>' \
  -H 'Content-Type: application/json' \
  -X POST 'http://localhost:18083/api/v5/mqtt/topic_metrics2' \
  -d '{
    "name": "sensor-temperatures",
    "topic_filter": "sensors/+/temperature"
  }'

レスポンスにはコレクションのメタデータとカウンターが含まれます。

json

{
  "name": "sensor-temperatures",
  "topic_filter": "sensors/+/temperature",
  "namespace": null,
  "create_time": "2026-06-02T12:34:56+00:00",
  "metrics": {
    "messages.in.count": 0,
    "messages.out.count": 0,
    "messages.dropped.count": 0,
    "bytes.in": 0,
    "bytes.out": 0
  }
}

コレクションの照会と管理

以下のエンドポイントでコレクションの照会と管理が可能です：

メソッドとエンドポイント	操作内容
`GET /api/v5/mqtt/topic_metrics2`	認証された管理者が閲覧可能なコレクションの一覧を取得。
`POST /api/v5/mqtt/topic_metrics2`	コレクションを作成。
`DELETE /api/v5/mqtt/topic_metrics2`	認証された管理者が閲覧可能なすべてのコレクションを削除。
`GET /api/v5/mqtt/topic_metrics2/:name`	指定したコレクションとクラスター集約カウンターを取得。
`DELETE /api/v5/mqtt/topic_metrics2/:name`	指定したコレクションを削除。
`PUT /api/v5/mqtt/topic_metrics2/:name/reset`	指定したコレクションのカウンターをリセット。

コレクションカウンター

各コレクションには以下のカウンターが含まれます：

カウンター	説明
`messages.in.count`	フィルターにマッチするトピックにパブリッシュされたメッセージ数。
`messages.out.count`	マッチするメッセージがサブスクライバーに配信された数。
`messages.dropped.count`	EMQXによってドロップされたマッチするメッセージ数。
`bytes.in`	マッチするパブリッシュメッセージのトピックとペイロードの合計サイズ。
`bytes.out`	マッチする配信済みメッセージのトピックとペイロードの合計サイズ。

バイトカウンターにはMQTTプロパティ、ユーザープロパティ、その他のプロトコルオーバーヘッドは含まれません。REST APIはメッセージレートやQoS別カウンターを計算・公開しません。レートを計算するには、カウンターをPrometheusにエクスポートし、PromQLのrate()関数を使用してください。

ネームスペースの分離

トピックメトリックコレクションは作成者のネームスペースに従います：

ネームスペース管理者が作成したコレクションはそのネームスペースに属し、同じネームスペースのパブリッシャーのメッセージのみをカウントします。
ネームスペース管理者はそのネームスペース内のコレクションのみを一覧表示、照会、リセット、削除できます。
グローバル管理者はグローバルコレクションを作成します。グローバルコレクションはすべてのネームスペースのパブリッシャーのメッセージをカウントします。
グローバル管理者はすべてのネームスペースのコレクションを一覧表示できます。同じ名前のコレクションが異なるネームスペースに存在することがあります。

ネームスペースの詳細はネームスペース概要を参照してください。