Merge pull request #271557 from kgremban/apr8-feedback

prmerger-automator[bot] · web-flow · commit c55fc3789218 · 2024-04-09T00:17:02.000Z
Address customer feedback
diff --git a/articles/iot-hub/iot-hub-distributed-tracing.md b/articles/iot-hub/iot-hub-distributed-tracing.md
@@ -45,7 +45,7 @@ Consider the following limitations to determine if this preview feature is right
 
 - The proposal for the W3C Trace Context standard is currently a working draft.
 - The only development language that the client SDK currently supports is C, in the [public preview branch of the Azure IoT device SDK for C](https://github.com/Azure/azure-iot-sdk-c/blob/public-preview/readme.md)
-- Cloud-to-device twin capability isn't available for the [IoT Hub basic tier](iot-hub-scaling.md#basic-and-standard-tiers). However, IoT Hub still logs to Azure Monitor if it sees a properly composed trace context header.
+- Cloud-to-device twin capability isn't available for the [IoT Hub basic tier](iot-hub-scaling.md). However, IoT Hub still logs to Azure Monitor if it sees a properly composed trace context header.
 - To ensure efficient operation, IoT Hub imposes a throttle on the rate of logging that can occur as part of distributed tracing.
 - The distributed tracing feature is supported only for IoT hubs created in the following regions:
 
diff --git a/articles/iot-hub/iot-hub-scaling.md b/articles/iot-hub/iot-hub-scaling.md
@@ -6,7 +6,7 @@ author: kgremban
 ms.author: kgremban
 ms.service: iot-hub
 ms.topic: concept-article
-ms.date: 02/09/2023
+ms.date: 04/08/2024
 ms.custom: [amqp, mqtt, 'Role: Cloud Development', 'Role: Operations']
 ---
 
@@ -18,15 +18,21 @@ To decide which IoT Hub tier is right for your solution, ask yourself two questi
 
 **What features do I plan to use?**
 
-Azure IoT Hub offers two tiers, basic and standard, that differ in the number of features they support. If your IoT solution is based around collecting data from devices and analyzing it centrally, then the basic tier is probably right for you. If you want to use more advanced configurations to control IoT devices remotely or distribute some of your workloads onto the devices themselves, then you should consider the standard tier. For a detailed breakdown of which features are included in each tier, continue to [Basic and standard tiers](#basic-and-standard-tiers).
+Azure IoT Hub offers two tiers, basic and standard, that differ in the features that they support. If your IoT solution is based around collecting data from devices and analyzing it centrally, then the basic tier is probably right for you. If you want to use more advanced configurations to control IoT devices remotely or distribute some of your workloads onto the devices themselves, then you should consider the standard tier.
+
+For a detailed breakdown of which features are included in each tier, continue to [Basic and standard tiers](#choose-your-features-basic-and-standard-tiers).
 
 **How much data do I plan to move daily?**
 
-Each IoT Hub tier is available in three sizes, based around how much data throughput they can handle in any given day. These sizes are numerically identified as 1, 2, and 3. For example, each unit of a level 1 IoT hub can handle 400 thousand messages a day, while a level 3 unit can handle 300 million. For more details about the data guidelines, continue to [Tier editions and units](#tier-editions-and-units).
+Each IoT Hub tier is available in three sizes, based around how much data throughput they can handle in a day. These sizes are numerically identified as 1, 2, and 3. The size determines the baseline daily message limit, and then you can scale out an IoT hub by adding *units*. For example, each unit of a level 1 IoT hub can handle 400,000 messages a day. A level 1 IoT hub with five units can handle 2,000,000 messages a day. Or, go up to a level 2 hub where each unit has a 6,000,000 messages daily limit.
+
+For more details about determining your message requirements and limits, continue to [Tier editions and units](#choose-your-size-editions-and-units).
 
-## Basic and standard tiers
+## Choose your features: basic and standard tiers
 
-The standard tier of IoT Hub enables all features, and is required for any IoT solutions that want to make use of the bi-directional communication capabilities. The basic tier enables a subset of the features and is intended for IoT solutions that only need uni-directional communication from devices to the cloud. Both tiers offer the same security and authentication features.
+The basic tier of IoT Hub enables a subset of available features and is intended for IoT solutions that only need uni-directional communication from devices to the cloud. The standard tier of IoT Hub enables all features, and is meant for IoT solutions that want to make use of the bi-directional communication capabilities. The basic tier enables a subset of the features and is intended for IoT solutions that only need uni-directional communication from devices to the cloud.
+
+Both tiers offer the same security and authentication features.
 
 | Capability | Basic tier | Standard tier |
 | ---------- | ---------- | ------------- |
@@ -85,15 +91,17 @@ The partition configuration remains unchanged when you migrate from basic tier t
 > [!NOTE]
 > The free tier does not support upgrading to basic or standard tier.
 
-## Tier editions and units
+## Choose your size: editions and units
 
 Once you've chosen the tier that provides the best features for your solution, determine the size that provides the best data capacity for your solution.
 
 Each IoT Hub tier is available in three sizes, based around how much data throughput they can handle in any given day. These sizes are numerically identified as 1, 2, and 3.
 
-Tiers and sizes are represented as *editions*. A basic tier IoT hub of size 2 is represented by the edition **B2**. Similarly, a standard tier IoT hub of size 3 is represented by the edition **S3**.
+A tier-size pair is represented as an *edition*. A basic tier IoT hub of size 2 is represented by the edition **B2**. Similarly, a standard tier IoT hub of size 3 is represented by the edition **S3**. For more information, includig pricing details, see [IoT Hub edition](https://azure.microsoft.com/pricing/details/iot-hub/)
+
+Once you choose an edition for your IoT hub, you can multiple its messaging capacity by increasing the number of *units*.
 
-Only one type of [IoT Hub edition](https://azure.microsoft.com/pricing/details/iot-hub/) within a tier can be chosen per IoT hub. For example, you can create an IoT hub with multiple units of S1. However, you can't create an IoT hub with a mix of units from different editions, such as S1 and B3 or S1 and S2.
+Each IoT hub can only be one edition. For example, you can create an IoT hub with multiple units of S1. However, you can't create an IoT hub with a mix of units from different editions, such as S1 and B3 or S1 and S2.
 
 The following table shows the capacity for device-to-cloud messages for each size.
 
@@ -116,7 +124,7 @@ After you create your IoT hub, without interrupting your existing operations, yo
 
 For more information, see [How to upgrade your IoT hub](iot-hub-upgrade.md).  
 
-## Auto-scale
+### Auto-scale
 
 If you're approaching the allowed message limit on your IoT hub, you can use these [steps to automatically scale](https://azure.microsoft.com/resources/samples/iot-hub-dotnet-autoscale/) to increment an IoT Hub unit in the same IoT Hub tier.
 
diff --git a/articles/iot/iot-mqtt-5-preview.md b/articles/iot/iot-mqtt-5-preview.md
@@ -1,14 +1,14 @@
 ---
 title: Azure IoT Hub MQTT 5 support (preview)
-description: Learn about MQTT 5 support in IoT Hub
+description: Learn about MQTT 5 support in IoT Hub.
 services: iot
 ms.service: iot
 ms.custom:
   - ignite-2023
 author: kgremban
 ms.author: kgremban
 ms.topic: conceptual
-ms.date: 04/24/2023
+ms.date: 04/08/2024
 ---
 
 # IoT Hub MQTT 5 support (preview)
@@ -23,8 +23,8 @@ This document defines IoT Hub data plane API over MQTT version 5.0 protocol. See
 
 ## Prerequisites
 
-- [Enable preview mode](../iot-hub/iot-hub-preview-mode.md) on a brand new IoT hub to try MQTT 5.
-- Prior knowledge of [MQTT 5 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) is required.
+- Create a brand new IoT hub with preview mode enabled. MQTT 5 is only available in preview mode, and you can't switch an existing IoT hub to preview mode. For more information, see [Enable preview mode](../iot-hub/iot-hub-preview-mode.md)
+- Prior knowledge of [MQTT 5 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html).
 
 ## Level of support and limitations
 
@@ -41,8 +41,7 @@ IoT Hub support for MQTT 5 is in preview and limited in following ways (communic
 - `Topic Alias Maximum` is `10`.
 - `Response Information` isn't supported; `CONNACK` doesn't return `Response Information` property even if `CONNECT` contains `Request Response Information` property.
 - `Receive Maximum` (maximum number of allowed outstanding unacknowledged `PUBLISH` packets (in client-server direction) with `QoS: 1`) is `16`.
-- Single client can have no more than `50` subscriptions.
-  When the limit's reached, `SUBACK` returns `0x97` (Quota exceeded) reason code for subscriptions.
+- Single client can have no more than `50` subscriptions. If a client reaches the subscription limit, `SUBACK` returns `0x97` (Quota exceeded) reason code for subscriptions.
 
 ## Connection lifecycle
 
@@ -112,7 +111,7 @@ Username/password authentication used in previous API versions isn't supported.
 
 #### SAS
 
-With SAS-based authentication, a client must provide the signature of the connection context. The signature proves authenticity of the MQTT connection. The signature must be based on one of two authentication keys in the client's configuration in IoT Hub.  Or it must be based on one of two shared access keys of a [shared access policy](../iot-hub/iot-hub-dev-guide-sas.md).
+With SAS-based authentication, a client must provide the signature of the connection context. The signature proves authenticity of the MQTT connection. The signature must be based on one of two authentication keys in the client's configuration in IoT Hub. Or it must be based on one of two shared access keys of a [shared access policy](../iot-hub/iot-hub-dev-guide-sas.md).
 
 String to sign must be formed as follows:
 
@@ -160,17 +159,17 @@ If reauthentication succeeds, IoT Hub sends `AUTH` packet with `Reason Code: 0x0
 
 ### Disconnection
 
-Server can disconnect client for a few reasons:
+Server can disconnect client for a few reasons, including:
 
-- client is misbehaving in a way that is impossible to respond to with negative acknowledgment (or response) directly,
-- server is failing to keep state of the connection up to date,
-- client with the same identity has connected.
+- client misbehaves in a way that is impossible to respond to with negative acknowledgment (or response) directly,
+- server fails to keep state of the connection up to date,
+- another client connects with the same identity.
 
 Server may disconnect with any reason code defined in MQTT 5.0 specification. Notable mentions:
 
-- `135` (Not authorized) when reauthentication fails, current SAS token expires or device's credentials change
+- `135` (Not authorized) when reauthentication fails, current SAS token expires, or device's credentials change.
 - `142` (Session taken over) when new connection with the same client identity has been opened.
-- `159` (Connection rate exceeded) when connection rate for the IoT hub exceeds  
+- `159` (Connection rate exceeded) when connection rate for the IoT hub exceeds the limit.
 - `131` (Implementation-specific error) is used for any custom errors defined in this API. `status` and `reason` properties are used to communicate further details about the cause for disconnection (see [Response](#response) for details).
 
 ## Operations
@@ -224,7 +223,7 @@ For example, Send Telemetry is Client-to-Server operation of "Message with ackno
 
 #### Message-acknowledgement interactions
 
-Message with optional Acknowledgment (MessageAck) interaction is expressed as an exchange of `PUBLISH` and `PUBACK` packets in MQTT. Acknowledgment is optional and sender may choose to not request it by sending `PUBLISH` packet with `QoS: 0`.
+Message with optional Acknowledgment (MessageAck) interaction is expressed as an exchange of `PUBLISH` and `PUBACK` packets in MQTT. Acknowledgment is optional and sender can choose to not request it by sending `PUBLISH` packet with `QoS: 0`.
 
 > [!NOTE]
 > If properties in `PUBACK` packet must be truncated due to `Maximum Packet Size` declared by the client, IoT Hub will retain as many User properties as it can fit within the given limit. User properties listed first have higher chance to be sent than those listed later; `Reason String` property has the least priority.
@@ -318,7 +317,7 @@ Interactions can result in different outcomes: `Success`, `Bad Request`, `Not Fo
 Outcomes are distinguished from each other by `status` user property. `Reason Code` in `PUBACK` packets (for MessageAck interactions) matches `status` in meaning where possible.
 
 > [!NOTE]
-> If client specifies `Request Problem Information: 0` in CONNECT packet, no user properties will be sent on `PUBACK` packets to comply with MQTT 5 specification, including `status` property. In this case, client can still rely on `Reason Code` to determine whether acknowledge is positive or negative. 
+> If client specifies `Request Problem Information: 0` in CONNECT packet, no user properties will be sent on `PUBACK` packets to comply with MQTT 5 specification, including `status` property. In this case, client can still rely on `Reason Code` to determine whether acknowledge is positive or negative.
 
 Every interaction has a default (or success). It has `Reason Code` of `0` and `status` property of "not set". Otherwise:
 
@@ -363,7 +362,7 @@ When needed, IoT Hub sets the following user properties:
 
 > [!NOTE]
 > If client sets `Maximum Packet Size` property in CONNECT packet to a very small value, not all user properties may fit and would not appear in the packet.
-> 
+>
 > `reason` is meant only for people and should not be used in client logic. This API allows for messages to be changed at any point without warning or change of version.
 >
 > If client sends `RequestProblemInformation: 0` in CONNECT packet, user properties won't be included in acknowledgements per [MQTT 5 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901053).
@@ -583,6 +582,7 @@ Response:
     status: 0100
     reason: "`Correlation Data` property is missing"
 ```
+
 ## Next steps
 
 - To review the MQTT 5 preview API reference, see [IoT Hub data plane MQTT 5 API reference (preview)](iot-mqtt-5-preview-reference.md).
