Create an isolated Proxy, route MQTT test traffic through it, add 500 ms downstream latency, compare Trace evidence, then remove the toxic and prove recovery.
Loading...
This guide follows one complete experiment: prove a clean MQTT path, add 500 ms of downstream latency, observe the delay, remove it, and prove recovery. The screenshots let you inspect the whole workflow without Mqttable installed. Running it requires Mqttable and an MQTT Broker that you own or are authorized to test.
The guide supplies every Proxy name, Client ID, Topic, and Payload. You enter those values; Mqttable does not generate them.
MQTTABLE CONNECTIONS
Publisher + Subscriber
connect to 127.0.0.1:3883
MQTTABLE PROXY
Docs Proxy Demo
Listen 127.0.0.1:3883
Upstream 127.0.0.1:1883
AUTHORIZED MQTT BROKER
Upstream target
127.0.0.1:1883
Open Proxy in the workspace sidebar. A fresh Runtime shows No Proxies Available and the Create Proxy action.
Start from the empty Proxy workspace so no existing listener, toxic, or Trace can contaminate the experiment.
Mqttable does not include an MQTT Broker. This experiment uses an authorized Broker already listening on 127.0.0.1:1883. Do not substitute a public, shared, or production Broker: adding a toxic immediately changes real traffic routed through this Proxy.
Select Create Proxy and enter:
Docs Proxy Demo127.0.0.1:3883TCP127.0.0.1:18830 secondsThe form defaults to Listen 127.0.0.1:1883, which would collide with this Broker, and to the public broker.emqx.io:1883 Upstream. Replace both values. Initial Delay controls when periodic toxics begin after Proxy start or after this value changes; the Always On toxic used here does not need a delay.
The dedicated loopback listener keeps fault traffic separate from the Broker's direct endpoint.
After creation, confirm that Docs Proxy Demo is selected, the route reads 127.0.0.1:3883 → 127.0.0.1:1883, status is Proxy running, Connections is 0, and Toxics is empty.
A running listener is only setup evidence; it does not yet prove that a client can reach the Broker through Proxy.
Stop here if the status is not running. A busy Listen port, unreachable Upstream, or unsupported address must be fixed before a toxic is added.
Keep the authorized Broker on 1883, then open Connections and create a dedicated Broker workspace that points to the Proxy listener instead of the Upstream:
Docs Proxy Routemqtt127.0.0.13883Select Test Connection and continue only after both MQTT versions report Connection OK, then select Create. The displayed endpoint must be mqtt://127.0.0.1:3883; 1883 would bypass Proxy.
In Docs Proxy Route, create and connect the built-in MQTT 5 client:
subscribermqttable-docs-proxy-subscriber-01On the connected subscriber row, select Add subscription and enter Topic mqttable/docs/proxy/temperature with QoS 1. Keep this Mqttable client connected until cleanup. The Client ID and Topic are tutorial values supplied here, not values generated by Mqttable.
Continue only after Proxy shows one downstream Connection and Trace contains a successful SUBSCRIBE → SEND followed by SUBACK ← RECV.
The Connection row proves the client entered through port 3883; SUBACK proves that the upstream Broker accepted the Topic Filter.
If the subscriber works but Proxy still shows 0 Connections and no Trace rows, it is probably bypassing Proxy and connecting directly to 1883. Fix the client port before continuing.
Return to Connections → Docs Proxy Route and create a second built-in MQTT 5 client:
publishermqttable-docs-proxy-publisher-01Connect publisher. In the Composer, select it and enter Topic mqttable/docs/proxy/temperature, QoS 1, Retain Off, and this JSON Payload:
{"phase":"baseline","temperature":21.5}
Select Send once, minimize the Composer, and return to Proxy. Pressing Send is not the success condition. Require publisher PUBLISH → SEND and PUBACK ← RECV, subscriber PUBLISH ← RECV and PUBACK → SEND, plus the matching phase=baseline Payload in Trace.
PUBACK proves Broker acceptance; the independent subscriber PUBLISH and PUBACK prove end-to-end delivery through Proxy.
In this capture, publisher PUBLISH at 22:34:07.630 reaches the subscriber at 22:34:07.632. Treat that Trace spacing only as this experiment's comparison baseline, not as a Benchmark result. Return to Connections and disconnect publisher; leave subscriber connected so the next sample includes a fresh publisher connection.
Select Add Toxic. Mqttable currently provides six network toxics and three MQTT-aware toxics in the same Proxy workspace.
The picker combines generic link faults with MQTT-specific disconnect, keepalive, and duplicate-message behavior.
Choose Latency and enter:
100%500 ms0 msDown means Broker → client. It delays the publisher's incoming CONNACK and PUBACK as well as the subscriber's incoming PUBLISH. Toxicity is the probability of applying the toxic, not an extra latency percentage.
Review the isolated target and every field before Add; the Engineer UI has no Dry Run for this operation.
Select Add only after confirming that no unrelated client depends on 127.0.0.1:3883.
Return to Connections → Docs Proxy Route and connect publisher again. After it reaches Connected, use the Composer to send the same-size fault Payload once with the same Topic, QoS 1, and Retain Off:
{"phase":"fault-on","temperature":21.5}
The Toxic row proves configuration, not impact. Use Trace timestamps to inspect publisher CONNECT → SEND to CONNACK ← RECV, publisher PUBLISH → SEND to subscriber PUBLISH ← RECV, and the matching subscriber Payload and PUBACK.
The active Toxic and MQTT rows preserve the exact fault condition, affected packets, and delivered Payload in one workbench.
The Trace shows about 560 ms from CONNECT to CONNACK and 551 ms from publisher PUBLISH to subscriber PUBLISH. Do not expect every interval to equal exactly 500 ms: protocol and processing overhead remains around the injected delay. Use Benchmark for statistically meaningful latency or capacity measurements. Disconnect publisher again before removing the Toxic.
Select the delete action on the exact latency_downstream row. The Toxic area must become empty immediately. Do not stop Proxy as a substitute: stopping the listener does not express that this saved fault was removed.
Return to Connections, connect publisher, and use the Composer to send the same-size recovery Payload once with the same Topic, QoS 1, and Retain Off:
{"phase":"recovery","temperature":21.5}
Recovery requires a fresh publication: an empty Toxic area plus delivered recovery Payload and comparable timestamps.
The recovery Trace shows CONNECT at 22:36:03.935, CONNACK at 22:36:03.936, and publisher and subscriber PUBLISH rows at 22:36:03.936, comparable to the clean baseline. Recovery is not complete if clients keep reconnecting, duplicate messages continue, or an old backlog is still draining.
Only clean up Connections workspace Docs Proxy Route, its two built-in Client IDs, Proxy Docs Proxy Demo, Topic traffic under mqttable/docs/proxy/temperature, and Toxic latency_downstream, which should already be absent.
Open Connections, open the settings for Docs Proxy Route, and select Delete. Confirm only after checking that the dialog names this dedicated workspace. This disconnects mqttable-docs-proxy-publisher-01 and mqttable-docs-proxy-subscriber-01; it does not delete the authorized Upstream Broker on 1883. Return to Proxy, wait for Connections to reach 0, then select Stop proxy.
The test client is gone, the listener is stopped, and no Toxic remains before the persistent workspace is deleted.
In the current version, exit Zen Mode to expose the workspace-tab delete action. Delete only Docs Proxy Demo; the confirmation states that deletion stops the Proxy and removes its Trace data. Re-enter Zen Mode and verify the final empty state.
The success notice and empty workspace prove that the tutorial Proxy, listener, Trace, Connection, and Toxic state no longer remain.
Do not clear another Proxy's Trace, delete a shared Broker configuration, or stop an unrelated local Broker during this cleanup.
After the first complete latency experiment, use one different Toxic at a time:
ChangeDelay matching packets with optional jitter.
EvidenceTrace timestamp gaps and client duration.
Main riskTimeouts and delayed acknowledgements.
ChangeCap throughput in one direction.
EvidenceTransfer duration, backlog, and Trace progress.
Main riskSlow or incomplete large Payload transfers.
ChangeDrop selected MQTT packet types by percentage.
EvidenceMissing packets, retransmission, or timeout.
Main riskLost acknowledgements and repeated delivery.
ChangeSend TCP RST immediately or after a timeout.
EvidenceConnection loss and bounded reconnect evidence.
Main riskUnacknowledged messages and reconnect storms.
ChangeSplit traffic into chunks with delay.
EvidenceApplication behavior plus PCAP when needed.
Main riskDecoder edge cases and slow reads.
ChangeClose after a cumulative byte limit.
EvidenceTrace stops at the configured boundary.
Main riskPartial transfers and interrupted sessions.
ChangeInject MQTT DISCONNECT by time, packet count, or probability.
EvidenceReason Code and subsequent client state.
Main riskReal session and reconnect side effects.
ChangeDrop or delay PINGREQ/PINGRESP.
EvidenceKeep Alive timeout and state transition.
Main riskHalf-open sessions and delayed detection.
ChangeCreate extra PUBLISH copies with optional DUP flags.
EvidenceMultiple subscriber rows for one source message.
Main riskDuplicate business actions without idempotency.
Every Toxic also has Direction and Toxicity. Always On applies continuously. Periodic adds Duration, Break, Repeat, and Offset; Repeat = 0 is displayed as ∞. Start with one Toxic because stacking Latency and Packet loss makes a timeout harder to attribute.
Current Proxy profiles are TCP, TLS, WS, and WSS, with the same selected profile used downstream and upstream. TLS and WSS certificate setup is outside this loopback tutorial; do not substitute placeholder credentials and claim the route works.
Free supports up to three Proxy workspaces. Pro removes that workspace-count limit. Remote Runtime requires Pro, and 127.0.0.1 then refers to the Runtime host rather than necessarily to your desktop.
Mqttable follows the same route-through-a-proxy idea as Shopify Toxiproxy, but it is not compatible with the Toxiproxy CLI or HTTP API. Its distinctive value is keeping MQTT-aware toxics, active downstream Connections, configuration, and protocol Trace evidence in one workbench.
Proxy Trace proves MQTT protocol and routing behavior, not TCP fragmentation, retransmission, or complete packet capture. Use PCAP analysis for packet-level evidence, or turn the clean and fault messages into a repeatable Replay Scenario.