w3c · SergeyKanzhelev · Jan 28, 2019 · Jan 29, 2019 · AloisReitbauer · Feb 8, 2019
diff --git a/extension-mqtt.html b/extension-mqtt.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset='utf-8'>
+    <title>Trace Context: MQTT protocol</title>
+    <script
+     src='https://www.w3.org/Tools/respec/respec-w3c-common'
+     class='remove' defer></script>
+    <script class='remove'>
+      var respecConfig = {
+        specStatus: "ED",
+        editors: [{
+          name: "Sergey Kanzhelev",
+          company: "Microsoft",
+          companyURL: "https://microsoft.com",
+          w3cid: "103966"
+        },
+        {
+          name: "Clemens Vasters",
+          company: "Microsoft",
+          companyURL: "https://microsoft.com",
+          w3cid: "104128"
+        }],
+        github: {
+          repoURL: "https://github.com/w3c/trace-context/",
+          branch: "master",
+        },
+        edDraftURI: "https://w3c.github.io/trace-context/extension-mqtt.html",
+        shortName: "trace-context",
+        format: "markdown",
+        subjectPrefix: "trace-context",
+        wg: "Distributed Tracing Working Group",
+        wgPublicList: "public-trace-context",
+        wgURI: "https://www.w3.org/2018/distributed-tracing/",
+        otherLinks: [{
+          key: 'Discussions',
+          data: [{
+            value: 'We are on Gitter.',
+            href: 'https://gitter.im/TraceContext/Lobby'
+          }]
+        }],
+        wgPatentURI: "https://www.w3.org/2004/01/pp-impl/108594/status"
+      };
+    </script>
+  </head>
+  <body>
+        <section id='abstract' data-include="spec/MQTT/01-abstract.md" data-include-format='markdown'></section>
+        <section id='sotd' data-include="spec/MQTT/02-sotd.md" data-include-format='markdown'></section>
+
+        <section data-include="spec/MQTT/20-MQTT5_FORMAT.md" data-include-format='markdown'></section>
+
+        <!-- Note, this section is a recommendation and it is not a part of a standard -->
+        <section data-include="spec/MQTT/20-MQTT3_FORMAT.md" data-include-format='markdown'  class="informative"></section>
+  </body>
+</html>
diff --git a/spec/MQTT/01-abstract.md b/spec/MQTT/01-abstract.md
@@ -0,0 +1,3 @@
+This is an extension document for the [Trace
+Context](https://w3c.github.io/trace-context/) specification. It defines the
+mapping of Trace Context fields to the MQTT protocol.
diff --git a/spec/MQTT/02-sotd.md b/spec/MQTT/02-sotd.md
@@ -0,0 +1,3 @@
+This is the First Public Working Draft
+([FPWD](https://www.w3.org/2017/Process-20170301/#working-draft)) of a MQTT
+trace context protocol specification.
diff --git a/spec/MQTT/20-MQTT5_FORMAT.md b/spec/MQTT/20-MQTT5_FORMAT.md
@@ -0,0 +1,35 @@
+# MQTT 5 format
+
+MQTT is a messaging protocol. As any messaging protocol it is commonly used as a
+mechanism for asynchronous or postponed execution of tasks. In those scenarios
+publisher of the message needs to communicate the trace context of execution to
+the consumer of that same message. So publishing and consuming tasks can be
+analyzed as a part of a single distributed trace.
+
+## Trace context fields placement in a message
+
+Starting v5.0 MQTT defines a message as a payload with the associated [User
+Properties](http://docs.oasis-open.org/mqtt/mqtt/v5.0/cos01/mqtt-v5.0-cos01.html#_Toc514847989).
+User properties MUST be used to propagate trace context and MUST follow the
+following convention.
+
+## Field `traceparent`
+
+Field `traceparent` MUST be set in user properties under the name `traceparent`.
+All lower case, no delimiters. Value of the `traceparent` field MUST follow the
+[main specification](index.html) format. Example of `traceparent` field value:
+
+``` http
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+```
+
+## Field `tracestate`
+
+Field `tracestate` MUST be set in user properties under the name `tracestate`.
+All lower case, no delimiters. Value of the `tracestate` field MUST follow the
+[main specification](index.html) format - comma delimited list of name-value
+pairs. Example of `tracestate` field value:
+
+``` http
+tracestate: congo=lZWRzIHRoNhcm5hbCBwbGVhc3VyZS4,rojo=00f067aa0ba902b7
+```
diff --git a/spec/MQTT/21-MQTT3_FORMAT.md b/spec/MQTT/21-MQTT3_FORMAT.md
@@ -0,0 +1,51 @@
+# MQTT 3 recommendation
+
+Before MQTT 5 there wre no extensibility metadata defined for the messages. Thus
+this section is only a set of recommendations on how trace context can be
+implemented, not the specification.
+
+## JSON payload
+
+It is common that MQTT message payload represented as JSON string. In this case
+it is recommended to set `traceparent` and `tracestate` fields as a fields on a
+outermost JSON object.
+
+For example, if original payload looks like following:
+
+``` json
+{
+    "_type": "cmd",
+    "action": "setConfiguration",
+    "configuration": {
+        "_type":"configuration",
+        "settingA": "value A",
+        "settingB": 42
+        }
+}
+```
+
+Payload with trace context configured will look like following:
+
+``` json
+{
+    "_type": "cmd",
+    "action": "setConfiguration",
+    "configuration": {
+        "_type":"configuration",
+        "settingA": "value A",
+        "settingB": 42
+        },
+    "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+    "tracestate": "congo=BleGNlZWRzIHRohbCBwbGVhc3VyZS4"
+}
+```
+
+## Handling e2e encryption
+
+TBD: Should there be a note that for e2e encryption one may decide to send trace
+context un-encrypted while the rest of the message can be encrypted?
+
+## Binary payload
+
+For binary payload - [binary protocol](..\extension-binary.html) may be used to
+propagate trace context fields.
diff --git a/spec/MQTT/22-MQTT_FORMAT_RATIONALE.md b/spec/MQTT/22-MQTT_FORMAT_RATIONALE.md
@@ -0,0 +1,3 @@
+# MQTT format rationale
+
+TBD