MQTT Streams
Important Notice
MQTT Streams は現在ベータ機能です。その機能やインターフェースは大幅に変更される可能性があります。
EMQX 6.1 では、MQTT Streams を導入しました。これは、MQTT のリアルタイムなパブリッシュ/サブスクライブモデルを拡張し、永続的でリプレイ可能なメッセージストリームを提供するストリーミングおよびリプレイ機能です。MQTT のセマンティクスを維持しつつ、Kafka のようなストリーミング機能を実現します。
本ページでは、EMQX における MQTT Streams の全体像を、設計の動機、主要概念、内部アーキテクチャ、メッセージフロー、実際の適用シナリオにわたって解説します。
Listener Mountpoint との非互換性
mountpoint が設定されたリスナー経由で接続されたクライアントに対しては、ストリームのリプレイは動作しません。EMQX はマウントポイントを $stream/ プレフィックスのマッチング前に適用するため、$stream/<name> へのサブスクライブはマウントされたリテラルトピックへの通常のサブスクライブとして扱われ、クライアントにはエラーが報告されません。メッセージの取り込みも影響を受け、パブリッシュされたトピックにはマウントポイントのプレフィックスが付与されるため、そのプレフィックスを含むトピックフィルターを持つストリームにのみマッチします。
MQTT Stream とは?
MQTT Stream は、名前付きの論理リソースであり、設定されたトピックフィルターにマッチする MQTT メッセージを継続的に収集します。メッセージはストリームの保持ポリシーに従って永続的に保存され、後からサブスクライブしたクライアントによってリプレイ可能です。
ストリームは一意の名前で識別されます。トピックフィルターはストリームの設定の一部ですが、識別子ではありません。
各ストリームは以下を持ちます:
- 一意の名前
- 設定されたトピックフィルター
- 保持ポリシー(時間ベースおよび/またはサイズベース)
- オプションのラストバリューセマンティクス
- 明示的なライフサイクル(作成、更新、削除)
なぜ MQTT Streams を使うのか?
MQTT はリアルタイムメッセージングに最適化されていますが、以下のような制約があります:
- メッセージは通常オンラインのサブスクライバーにのみ配信される。
- 過去のデータのリプレイはネイティブにはサポートされていない。
- 過去データの再処理には外部システムが必要。
- 順序付けられたリプレイ可能なメッセージ履歴の維持は困難。
MQTT Streams は、永続的なメッセージ保存とリプレイ機能を MQTT に追加します。これにより、MQTT クライアントのパブリッシュやサブスクライブの方法を変えずに、消費者が過去のメッセージを読み取り、デバイスの最新状態を取得できます。
MQTT Streams の主要概念
MQTT Stream
名前で識別・アドレス指定され、明示的なライフサイクルで管理される論理リソースです。アクティブな間は、設定された時間またはサイズの制限内でマッチするメッセージを継続的に保存します。保存されたメッセージは、パブリッシャー側の変更なしにサブスクライブする消費者によってリプレイ可能です。
ストリーム名に使用できる文字は以下のみです:
- 英数字(
A–Z,a–z,0–9) - アンダースコア(
_) - ハイフン(
-) - ドット(
.)
サポートされるストリームタイプは2種類です:
- 通常ストリーム:過去のデータを上書きせず、すべてのマッチするメッセージを保存します。
stream-offsetサブスクリプションプロパティを使い、指定したタイムスタンプやオフセットからメッセージをリプレイ可能です。 - ラストバリューストリーム:ラストバリューセマンティクスを有効にしたストリームです。同じストリームキーを持つメッセージは新しいものが古いものを上書きし、各キーに対して最新のメッセージのみを保持します。詳細はストリームキー式をご覧ください。
- 英数字(
トピックフィルター
sensors/+/dataのような MQTT トピックフィルターで、どのパブリッシュメッセージをストリームに取り込むかを決定します。マッチしたメッセージのみが取り込まれ、1つのメッセージが複数のストリームに属することもあります。TIP
トピックフィルターはストリームの識別子ではなく、名前付きストリームの設定メタデータです。
ストリームサブスクリプション
ストリームからメッセージを消費するための特別な MQTT サブスクリプションです。クライアントは以下のいずれかの形式でサブスクライブします:
SUBSCRIBE $stream/<name> SUBSCRIBE $stream/<name>/<topic_filter>ここで:
<name>はストリーム名(必須)<topic_filter>は既存ストリームにサブスクライブする際は省略可能- 自動作成が有効な場合、
$stream/<name>/<topic_filter>により、存在しないストリームは指定されたトピックフィルターで作成されます。
ストリームサブスクリプションは通常の MQTT サブスクリプションとは独立して動作し、External Subscription メカニズムを通じて配信されます。
ストリームオフセット(リプレイ開始位置)
リプレイの開始位置は、トピックパスではなく MQTT 5 のユーザーサブスクリプションプロパティ
stream-offsetで指定します。stream-offsetプロパティはリプレイ開始位置を決定します。例:- タイムスタンプ
- 論理オフセット
- 最も古い位置や最新位置などの特別な位置(対応している場合)
この設計により、トピック文字列からのオフセット解析が不要となり、リプレイ制御が MQTT 5 プロパティに統合されます。
キー式
受信した各メッセージに対して評価されるユーザー定義式で、キーを抽出します。式はメッセージの内容やメタデータを参照可能です。抽出されたキーはストレージパーティション内でのメッセージ順序を保証するために使われます。ラストバリューセマンティクスが有効な場合は、キーが上書き範囲を定義し、同じキーの新しいメッセージが古いものを置き換えます。
MQTT Streams のアーキテクチャ
MQTT Streams は、ブローカーコアと疎結合で既存のインフラを再利用する独立した EMQX アプリケーションとして実装されています。EMQX との統合は内部フックと External Subscription フレームワークを通じて行われます。
TIP
External Subscription は、ライブ MQTT パブリッシュ経路外から発生するメッセージソースを MQTT クライアントセッションに接続し、クライアントの動作を変えずに標準 MQTT サブスクリプションを通じてメッセージを届ける EMQX の仕組みです。
主なコンポーネント
- Streams Registry:MQTT ストリームのライフサイクルを管理し、ストリーム名、トピックフィルター、保持ポリシー、キー式などのメタデータを保持します。Mnesia テーブルを使い効率的にストリームを検索します。
- Streams Message Database:ストリームメッセージの永続ストレージを提供し、EMQX のパーシステントストレージ上に構築されています。メッセージを保存し、保持制限を適用し、ラストバリューセマンティクスを有効にし、保持ポリシーに従って効率的にメッセージを取得可能です。
- Streams ExtSub Handler:メッセージストリームを MQTT クライアントセッションに統合します。パーシステントストレージからメッセージを取得し、External Subscription フレームワークを通じてサブスクライブクライアントに配信します。
MQTT Streams データフローダイアグラム
以下の図は MQTT Streams コンポーネント間のデータフローを示しています:

パブリッシュフロー
- クライアントが MQTT トピックにメッセージをパブリッシュします。
- MQTT Streams フックが発火し、パブリッシュ処理を開始します。
- フックは Streams Registry に問い合わせ、メッセージのトピックにマッチするストリームを特定します。
- マッチした各ストリームに対してメッセージを書き込み、パーシステントストレージに保存します。
サブスクライブおよび消費フロー
クライアントがストリームトピック(
$stream/<name>または$stream/<name>/<topic_filter>)にサブスクライブし、任意でstream-offsetサブスクリプションプロパティを含めます。Deprecated
後方互換性のため、レガシーフォーマット
$s/<offset>/<topic_filter>はサポートされていますが非推奨です。詳細は互換性の注意をご覧ください。External Subscription フレームワークがサブスクリプションを処理し、ストリームトピック用の Streams ExtSub ハンドラーを初期化します。
ハンドラーは指定された
stream-offsetと保持ルールに従い、パーシステントストレージからメッセージを取得します。取得したメッセージは External Subscription フレームワークに渡されます。
ExtSub アプリケーションが標準 MQTT 配信を通じてクライアントにメッセージを届けます。
MQTT Streams のコア機能
MQTT Streams は、メッセージの保存、順序付け、保持、リプレイ配信を定義する一連のコア機能を提供します。
オフセットベースのリプレイ
リプレイ開始位置はトピックパスではなく
stream-offsetサブスクリプションプロパティで指定します。指定オフセット以前にパブリッシュされたメッセージはスキップされます。保持
ストリームの保持ポリシーによりメッセージのリプレイ範囲が制限されます。メッセージは時間またはサイズの制限で保持され、期限切れのメッセージは消費済みか否かに関わらず自動的に削除されます。
キー単位の順序保証
MQTT Streams は単一のグローバルな配信順序を保証しません。同じキーを持つメッセージは常にパブリッシュ順に配信されますが、異なるキーのメッセージは任意の順序で配信される可能性があります。
ラストバリューセマンティクス
ストリームはラストバリューセマンティクスを有効にできます。同じキーを持つメッセージは新しいものが古いものを上書きし、最新の値のみが保持されます。キーが解決できないメッセージは通常通り保存されます。
MQTT ネイティブ配信
ストリームメッセージは標準の MQTT メカニズムを使って配信されます。パブリッシャーは挙動を変える必要がありません。サブスクライバーへの配信は External Subscription を通じて統合されます。
セキュリティ上の考慮点
EMQX はストリームサブスクリプションを、$stream/ プレフィックスおよびストリーム名を含む完全なサブスクリプショントピックフィルターに対して認可します。ストリームサブスクリプションを認可すると、サブスクリプション作成前にストリームが保存したメッセージのリプレイも許可される可能性があります。
ストリームサブスクリプションには専用のルールが必要
通常のトピックスペース用に書かれたルールは対応するストリームサブスクリプションをカバーしません:
t/#のルールは$stream/events/t/#には適用されません。EMQX はこれらを異なるトピックとして扱います。#や+で始まる認可トピックフィルターは$で始まるサブスクリプショントピックフィルターにマッチしません。デフォルトのacl.confにある{eq, "#"}ルールを含む#を拒否するルールは$stream/events/#を拒否しません。
したがって、# が拒否されているクライアントでも $stream/events/# にサブスクライブし、stream-offset を earliest に設定してストリームに保存されているすべてのメッセージをリプレイ可能です。$stream/ に対して明示的なルールを追加し、ストリームのトピックフィルターにマッチするトピックのルールと同等以上の厳格さにしてください:
%% 自動作成を許可せず、事前作成済みの "events" ストリームをリプレイできる1つのコンシューマを許可
{allow, {username, "event_reader"}, subscribe, ["$stream/events"]}.
%% その他すべてのストリームサブスクリプションを拒否(非推奨プレフィックス含む)
{deny, all, subscribe, ["$stream/#", "$s/#"]}.非推奨の $s/ プレフィックスは、クライアントがまだ使用している間はルールに残してください。非推奨プレフィックスも参照してください。
この挙動は共有サブスクリプションとは異なります。$share/<group>/t/# では EMQX はプレフィックスを除去し t/# を認可しますが、$stream/<name>/t/# では完全なサブスクリプショントピックフィルターを認可します。
自動作成はクライアント指定のトピックフィルターを許可
ストリーム自動作成が有効な場合、サブスクライブクライアントが新ストリームのトピックフィルターを決定します。EMQX は $stream/<name>/<topic_filter> の <topic_filter> を使ってストリームを作成し、クライアントが <topic_filter> への直接サブスクライブを認可されているかは別途チェックしません。
例えば、クライアントが $stream/+/# へのサブスクライブを許可されている場合、$stream/events/# にサブスクライブできます。events ストリームが存在しなければ、EMQX はトピックフィルター # で作成します。すると、$ で始まらないすべてのトピックのメッセージを保存し、クライアントは直接サブスクライブが認可されていないトピックのメッセージもリプレイ可能になります。
自動作成はデフォルトでラストバリューストリームに対して有効、通常ストリームに対しては無効ですが、MQTT Streams が有効な場合にのみ機能します。MQTT Streams はデフォルトで無効(streams.enable = false)です。信頼できないクライアントを受け入れる環境では、$stream/events のような特定の事前作成済みストリームのみアクセスを許可し、$stream/# や $s/# にマッチするその他のサブスクリプションはすべて拒否してください。あるいは自動作成を無効化し、ダッシュボードや REST API からストリームを作成してください。ダッシュボード経由でストリームを自動作成するも参照してください。
互換性に関する注意
既存のデプロイメントに関する互換性の考慮点を説明します。
名前付きストリーム
- すべてのストリームは明示的に名前付きリソースになりました。
- ストリーム名は許可された文字セットのルールに従う必要があります。
レガシーストリーム
以前に作成された名前なしストリームには、トピックフィルターから派生した名前が自動的に割り当てられます。
派生名は /<topic_filter> となります。
非推奨プレフィックス
ストリームサブスクライブ用の $s プレフィックスは後方互換性のためにまだサポートされていますが非推奨です。
新規デプロイメントでは $stream/<name> を使用してください。
典型的なユースケース
- 過去データのリプレイ:過去の MQTT イベントを再処理し、デバッグや新たなビジネスロジックに活用。
- 時系列分析:センサーデータを保存・リプレイし、分析や予知保全に利用。
- イベントソーシング:すべての状態変化を不変のイベントログとして永続化。
- IoT デジタルツイン:物理デバイスの最新状態をデジタルで保持。
- 設定同期:デバイスが常に最新の設定を受け取ることを保証。
次のステップ
MQTT Streams の基本を理解したら、実際の活用方法を学びましょう:
- ストリームの作成と設定:ダッシュボードや REST API を使ったストリーム宣言、ラストバリューセマンティクスや保持ポリシーの設定方法を学べます。
- クイックスタートチュートリアル:MQTTX を使って実際のパブリッシャーとサブスクライバーのシナリオをステップバイステップで体験できます。