You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-reliability-features-in-sdks.md
+20-20Lines changed: 20 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,11 +3,11 @@ title: How to manage connectivity and reliable messaging using Azure IoT Hub dev
3
3
description: Learn how to improve your device connectivity and messaging when using the Azure IoT Hub device SDKs
4
4
services: iot-hub
5
5
keywords:
6
-
author: BryanLa
7
-
ms.author: bryanla
8
-
ms.date: 02/10/2018
6
+
author: yzhong94
7
+
ms.author: yizhon
8
+
ms.date: 07/07/2018
9
9
ms.topic: article
10
-
ms.service: iot-dps
10
+
ms.service: iot-hub
11
11
12
12
documentationcenter: ''
13
13
manager: timlt
@@ -17,13 +17,13 @@ ms.custom: mvc
17
17
18
18
# How to manage connectivity and reliable messaging using Azure IoT Hub device SDKs
19
19
20
-
This guide provides high-level guidance for designing resilient device applications, by taking advantage of the connectivity and reliable messaging features in Azure IoT device SDKs. The goal of this article is to help answer questions and handle scenarios such as :
20
+
This guide provides high-level guidance for designing resilient device applications, by taking advantage of the connectivity and reliable messaging features in Azure IoT device SDKs. The goal of this article is to help answer questions and handle these scenarios :
21
21
22
22
- managing a dropped network connection
23
23
- managing switching between different network connections
24
24
- managing reconnection due to service transient connection errors
25
25
26
-
Implementation details may vary by language, so be sure to refer to the linked API documentation or specific SDK for more details.
26
+
Implementation details may vary by language, see linked API documentation or specific SDK for more details.
@@ -33,9 +33,9 @@ Implementation details may vary by language, so be sure to refer to the linked A
33
33
34
34
## Designing for resiliency
35
35
36
-
Internet of Things devices often rely on non-continuous and/or unstable network connections such as GSM or satellite. In addition, when interacting with cloud-based services, errors can occur due to temporary conditions such as intermittent service availability and infrastructure-level faults (commonly referred to as "transient faults"). This makes it difficult for an application running on a device to manage the connection and reconnection mechanisms, as well as the retry logic for sending/receiving messages. Furthermore, the retry strategy requirements depend heavily on the IoT scenario the device participates in, and the device’s context and capabilities.
36
+
IoT devices often rely on non-continuous and/or unstable network connections such as GSM or satellite. In addition, when interacting with cloud-based services, errors can occur due to temporary conditions such as intermittent service availability and infrastructure-level faults (commonly referred to as transient faults). An application running on a device need to manage the connection and reconnection mechanisms, as well as the retry logic for sending/receiving messages. Furthermore, the retry strategy requirements depend heavily on the IoT scenario the device participates in, and the device’s context and capabilities.
37
37
38
-
The Azure IoT Hub device SDKs aim to simplify connecting and communicating from cloud-to-device and device-to-cloud. We want to ensure that the Azure IoT device client SDKs provide a simple, robust and comprehensive way of connecting and sending/receiving messages to and from Azure IoT Hub. This also requires providing the right set of information and settings for a developer to implement the right retry strategy for a given scenario.
38
+
The Azure IoT Hub device SDKs aim to simplify connecting and communicating from cloud-to-device and device-to-cloud by providing a robust and comprehensive way of connecting and sending/receiving messages to and from Azure IoT Hub. Developers can also modify existing implementation to develop the right retry strategy for a given scenario.
39
39
40
40
The relevant SDK features that support connectivity and reliable messaging are covered in the following sections.
41
41
@@ -46,37 +46,37 @@ This section provides an overview of the reconnection and retry patterns availab
46
46
### Error patterns
47
47
Connection failures can happen in many levels:
48
48
49
-
1. Network errors such as a disconnected socket and name resolution errors
50
-
2. Protocol-level errors for HTTP, AMQP and MQTT transports such as links detached or sessions expired
51
-
3. Application-level errors that result from either local mistakes such as invalid credentials or service behavior such as exceeding quota or throttling
49
+
- Network errors such as a disconnected socket and name resolution errors
50
+
- Protocol-level errors for HTTP, AMQP, and MQTT transport such as links detached or sessions expired
51
+
- Application-level errors that result from either local mistakes such as invalid credentials or service behavior such as exceeding quota or throttling
52
52
53
53
The device SDKs detect errors in all three levels. OS-related errors and hardware errors are not detected and handled by the device SDKs. The design is based on [The Transient Fault Handling Guidance](https://docs.microsoft.com/azure/architecture/best-practices/transient-faults#general-guidelines) from Azure Architecture Center.
54
54
55
55
### Retry patterns
56
56
57
57
The overall process for retry when connection errors are detected is:
58
58
1. The SDK detects the error and the associated error in network, protocol, or application.
59
-
2. Based on the error type, the SDK uses the error filter to decide if retry needs to be performed. If an **unrecoverable error** is identified by the SDK, operations (connection and send/receive) will be stopped and the SDK will notify the user. An unrecoverable error is an error that the SDK can identify and determine that it can not be required, for example, an authentication or bad endpoint error.
59
+
2. Based on the error type, the SDK uses the error filter to decide if retry needs to be performed. If an **unrecoverable error** is identified by the SDK, operations (connection and send/receive) will be stopped and the SDK will notify the user. An unrecoverable error is an error that the SDK can identify and determine that it cannot be recovered, for example, an authentication or bad endpoint error.
60
60
3. If a **recoverable error** is identified, the SDK begins to retry using the retry policy specified until a defined timeout expires.
61
61
4. When the defined timeout expires, the SDK stops trying to connect or send, and notifies the user.
62
62
5. The SDK allows the user to attach a callback to receive connection status changes.
63
63
64
64
Three retry policies are provided:
65
65
1)**Exponential back-off with jitter**: This is the default retry policy applied. It tends to be aggressive at the start, slows down, and then hits a maximum delay that is not exceeded. The design is based on [Retry guidance from Azure Architecture Center](https://docs.microsoft.com/azure/architecture/best-practices/retry-service-specific).
66
66
2)**Custom retry**: You can implement a custom retry policy and inject it in the RetryPolicy depending on the language you choose. You can design a retry policy that is suited for your scenario. This is not available on the C SDK.
67
-
3)**No retry**: There is an option to set retry policy to "no retry," which disables the retry logic. The SDK tries to connect once and send a message once, assuming the connection is established. This policy would typically be used in cases where there are bandwidth or cost concerns. Please be aware that if this option is chosen, messages that fail to send are lost and cannot be recovered.
67
+
3)**No retry**: There is an option to set retry policy to "no retry," which disables the retry logic. The SDK tries to connect once and send a message once, assuming the connection is established. This policy would typically be used in cases where there are bandwidth or cost concerns. If this option is chosen, messages that fail to send are lost and cannot be recovered.
| C/Python/iOS |[IOTHUB_CLIENT_RESULT IoTHubClient_SetRetryPolicy](https://github.com/Azure/azure-iot-sdk-c/blob/2018-05-04/iothub_client/inc/iothub_client.h#L188)|**Default**: [IOTHUB_CLIENT_RETRY_EXPONENTIAL_BACKOFF](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/connection_and_messaging_reliability.md#connection-retry-policies)<BR>**Custom:** use available [retryPolicy](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/connection_and_messaging_reliability.md#connection-retry-policies)<BR>**No retry:**[IOTHUB_CLIENT_RETRY_NONE](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/connection_and_messaging_reliability.md#connection-retry-policies)|[C/Python/iOS implementation](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/connection_and_messaging_reliability.md#)|
Below are code examples that illustrates this flow.
79
+
Below are code samples that illustrate this flow.
80
80
81
81
#### .NET implementation guidance
82
82
@@ -88,7 +88,7 @@ The code sample below shows how to define and set the default retry policy:
88
88
SetRetryPolicy(retryPolicy);
89
89
```
90
90
91
-
To avoid high CPU usage, the retries are throttled if the code fails immediately (e.g. when there is no network or route to destination) so that the minimum time to execute the next retry is 1 second.
91
+
To avoid high CPU usage, the retries are throttled if the code fails immediately (for example, when there is no network or route to destination) so that the minimum time to execute the next retry is 1 second.
92
92
93
93
If the service is responding with a throttling error, the retry policy is different and cannot be changed via public API:
94
94
@@ -101,7 +101,7 @@ If the service is responding with a throttling error, the retry policy is differ
101
101
The retry mechanism will stop after `DefaultOperationTimeoutInMilliseconds`, which is currently set at 4 minutes.
102
102
103
103
#### Other languages implementation guidance
104
-
For other languages, please review the implementation documentation below. Samples demonstrating the use of retry policy APIs are provided in the repository.
104
+
For other languages, review the implementation documentation below. Samples demonstrating the use of retry policy APIs are provided in the repository.
0 commit comments