トピックメトリクス

トピックメトリクスは、選択した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`	1つのコレクションとそのクラスター集約カウンターの取得
`DELETE /api/v5/mqtt/topic_metrics2/:name`	1つのコレクションの削除
`PUT /api/v5/mqtt/topic_metrics2/:name/reset`	1つのコレクションのカウンターリセット

コレクションのカウンター

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

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

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

ネームスペースの分離

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

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

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