# トピックメトリクス

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

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

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

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

::: tip 互換性について

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

:::

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

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

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

<img src="./assets/topic-metrics-ee.png" alt="トピックメトリクスページ" style="zoom: 40%;" />

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

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

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

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

REST APIの認証については[REST API](../api.md#authentication)を参照してください。

### コレクションの制限

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

- コレクション名は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()`関数を使用してください。

### ネームスペースの分離

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

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

ネームスペースの詳細は[ネームスペース概要](../multi-tenancy/namespace-overview.md)を参照してください。

## トピックメトリクスをPrometheusにエクスポート

EMQX 6.3以降、Prometheusは`GET /api/v5/prometheus/topic_metrics`からコレクションカウンターをスクレイプできます。メトリック名、ラベル、コレクションモード、およびPrometheus設定例については[Prometheus連携](./prometheus.md#topic-metrics)を参照してください。