Document Details

## Collect logs for connections and device telemetry IoT Hub emits resource logs for several categories of operation. To view these logs, you must create a diagnostic setting to send them to a destination. One such destination is Azure Monitor Logs, which are collected in a Log Analytics workspace. IoT Hub resource logs are grouped into different categories. You can select which categories you want sent to Azure Monitor Logs in the diagnostic setting. In this article, we'll collect logs for operations and errors having to do with connections and device telemetry. For a full list of the categories supported for IoT Hub, see [IoT Hub resource logs](monitor-iot-hub-reference.md#resource-logs). To create a diagnostic setting to send IoT Hub resource logs to Azure Monitor Logs, follow these steps: 1. In the [Azure portal](https://portal.azure.com), navigate to your IoT hub. If you used the CLI commands to create your resources, then your IoT hub is in the resource group **ContosoResources**. 1. Select **Diagnostic settings** from the **Monitoring** section of the navigation menu. Then select **Add diagnostic setting**. :::image type="content" source="media/tutorial-use-metrics-and-diags/open-diagnostic-settings.png" alt-text="Screenshot that highlights Diagnostic settings in the Monitoring section."::: 1. On the **Diagnostics setting** page, provide the following details: | Parameter | Value | | --------- | ----- | | **Diagnostic setting name** | Give your setting a descriptive name, such as "Send connections and telemetry to logs". | | **Logs** | Select **Connections** and **Device Telemetry** from the **Categories** list. | | **Destination details** | Select **Send to Log Analytics workspace**, then use the Log Analytics workspace picker to select the workspace you noted previously. :::image type="content" source="media/tutorial-use-metrics-and-diags/add-diagnostic-setting.png" alt-text="Screenshot showing the final diagnostic log settings."::: 1. Select **Save** to save the settings. Close the **Diagnostics setting** pane. You can see your new setting in the list of diagnostic settings. ## Set up metrics Now we'll use metrics explorer to create a chart that displays metrics you want to track. You'll pin this chart to your default dashboard in the Azure portal. 1. In your IoT hub menu, select **Metrics** from the **Monitoring** section. 1. At the top of the screen, select **Last 24 hours (Automatic)**. In the dropdown that appears, select **Last 4 hours** for **Time range**, set **Time granularity** to **1 minute**, and select **Local** for **Show time as**. Select **Apply** to save these settings. The setting should now say **Local Time: Last 4 hours (1 minute)**. :::image type="content" source="media/tutorial-use-metrics-and-diags/metrics-select-time-range.png" alt-text="Screenshot showing the metrics time settings."::: 1. On the chart, there's a partial metric setting displayed scoped to your IoT hub. Leave the **Scope** and **Metric Namespace** values at their defaults. Select the **Metric** setting and type "Telemetry", then select **Telemetry messages sent** from the dropdown. **Aggregation** will be automatically set to **Sum**. Notice that the title of your chart also changes. :::image type="content" source="media/tutorial-use-metrics-and-diags/metrics-telemetry-messages-sent.png" alt-text="Screenshot that shows adding Telemetry messages sent metric to chart."::: 1. Now select **Add metric** to add another metric to the chart. Under **Metric**, select **Total number of messages used**. For **Aggregation**, select **Avg**. Notice again that the title of the chart has changed to include this metric. Now your screen shows the minimized metric for *Telemetry messages sent*, plus the new metric for *Total number of messages used*. :::image type="content" source="media/tutorial-use-metrics-and-diags/metrics-total-number-of-messages-used.png" alt-text="Screenshot that shows adding Total number of messages used metric to chart."::: 1. In the upper right of the chart, select **Save to dashboard** and choose **Pin to dashboard** from the dropdown list. :::image type="content" source="media/tutorial-use-metrics-and-diags/metrics-total-number-of-messages-used-pin.png" alt-text="Screenshot that highlights the Save to dashboard button."::: 1. On the **Pin to dashboard** pane, select the **Existing** tab. Select **Private** and then select **Dashboard** from the Dashboard dropdown. Finally, select **Pin** to pin the chart to your default dashboard in Azure portal. If you don't pin your chart to a dashboard, your settings aren't retained when you exit metric explorer. :::image type="content" source="media/tutorial-use-metrics-and-diags/pin-to-dashboard.png" alt-text="Screenshot that shows settings for Pin to dashboard."::: ## Set up metric alerts Now we'll set up alerts to trigger on two metrics: *Telemetry messages sent* and *Total number of messages used*. **Telemetry messages sent** is a good metric to track message throughput and avoid being throttled. For an IoT hub in the free tier, the throttling limit is 100 messages/sec. With a single device, we won't be able to achieve that kind of throughput, so instead, we'll set up the alert to trigger if the number of messages exceeds 1000 in a 5-minute period. In production, you can set the signal to a more significant value based on the tier, edition, and number of units of your IoT hub. **Total number of messages used** tracks the daily number of messages used. This metric resets every day at 00:00 UTC. If you exceed your daily quota past a certain threshold, your IoT Hub will no longer accept messages. For an IoT hub in the free tier, the daily message quota is 8000. We'll set up the alert to trigger if the total number of messages exceeds 4000, 50% of the quota. In practice, you'd probably set this percentage to a higher value. The daily quota value is dependent on the tier, edition, and number of units of your IoT hub. For more information about quota and throttling limits with IoT Hub, see [Quotas and throttling](iot-hub-devguide-quotas-throttling.md). To set up metric alerts: 1. In your IoT hub menu, select **Alerts** from the **Monitoring** section. 1. Select **Create alert rule**. On the **Create alert rule** pane, there are four sections: * **Scope** is already set to your IoT hub, so we'll leave this section alone. * **Condition** sets the signal and conditions that will trigger the alert. * **Actions** configures what happens when the alert triggers. * **Details** lets you set a name and a description for the alert. 1. First configure the condition that the alert will trigger on. 1. The **Condition** tab opens with the **Select a signal** pane open. Type "telemetry" in the signal name search box and select **Telemetry messages sent**. :::image type="content" source="media/tutorial-use-metrics-and-diags/configure-signal-logic-telemetry-messages-sent.png" alt-text="Screenshot showing selecting the metric."::: 1. On the **Configure signal logic** pane, set or confirm the following fields under **Alert logic** (you can ignore the chart): | Parameter | Value | | --------- | ----- | | **Threshold** | *Static* | | **Operator** | *Greater than* | | **Aggregation type** | *Total* | | **Threshold value** | *1000* | | **Unit** | *Count* | | **Aggregation granularity (Period)** | *5 minutes* | | **Frequency of evaluation** | *Every 1 Minute* | :::image type="content" source="media/tutorial-use-metrics-and-diags/configure-signal-logic-set-conditions.png" alt-text="Screenshot showing alert conditions settings."::: These settings set the signal to total the number of messages over a period of 5 minutes. This total will be evaluated every minute, and, if the total for the preceding 5 minutes exceeds 1000 messages, the alert will trigger. Select **Done** to save the signal logic. 1. Select **Next: Actions** to configure the action for the alert. 1. Select **Create action group**. 1. On the **Basics** tab on the **Create action group** pane, give your action group a name and a display name. :::image type="content" source="media/tutorial-use-metrics-and-diags/create-action-group-basics.png" alt-text="Screenshot showing Basics tab of Create action group pane."::: 1. Select the **Notifications** tab. For **Notification type**, select **Email/SMS message/Push/Voice** from the dropdown. The **Email/SMS message/Push/Voice** pane opens. 1. On the **Email/SMS message/Push/Voice** pane, select email and enter your email address, then select **OK**. :::image type="content" source="media/tutorial-use-metrics-and-diags/set-email-address.png" alt-text="Screenshot showing email address setting."::: 1. Back on the **Notifications** pane, enter a name for the notification. :::image type="content" source="media/tutorial-use-metrics-and-diags/create-action-group-notification-complete.png" alt-text="Screenshot showing completed notifications pane."::: 1. (Optional) On the action group **Actions** tab, the **Action type** dropdown lists the kinds of actions that you can trigger with an alert. For this article, we'll only use notifications, so you can ignore the settings under this tab. :::image type="content" source="media/tutorial-use-metrics-and-diags/action-types.png" alt-text="Screenshot showing action types available on the Actions pane."::: 1. Select the **Review and Create** tab, verify your settings, and select **Create**. 1. Back on the alert rule **Actions** tab, notice that your new action group has been added to the actions for the alert. 1. Select **Next: Details** to configure the alert rule details and save the alert rule. 1. On the **Details** tab, provide a name and a description for your alert; for example, "Alert if more than 1000 messages over 5 minutes". 1. Select **Review + create** to review the details of your alert rule. If everything looks correct, select **Create** to save your new rule. 1. Now set up another alert for the *Total number of messages used*. This metric is useful if you want to send an alert when the number of messages used is approaching the daily quota for the IoT hub, at which point the IoT hub will start rejecting messages. Follow the steps you did before, with the following differences. * For the signal on the **Configure signal logic** pane, select **Total number of messages used**. * On the **Configure signal logic** pane, set or confirm the following fields (you can ignore the chart): | Parameter | Value | | --------- | ----- | | **Threshold** | *Static* | | **Operator** | *Greater than* | | **Aggregation type** | *Total* | | **Threshold value** | *4000* | | **Unit** | *Count* | | **Aggregation granularity (Period)** | *1 minute* | | **Frequency of evaluation** | *Every 1 Minute* | These settings set the signal to fire when the number of messages reaches 4000. The metric is evaluated every minute. * When you specify the action for your alert rule, select same the action group that you created for the previous rule. * For the alert details, choose a different name and description than you did previously. 1. Select **Alerts**, under **Monitoring** on the left pane of your IoT hub. Now select **Alert rules** on the menu at the top of the **Alerts** pane. The **Alert rules** pane opens. You should see your two alerts: :::image type="content" source="media/tutorial-use-metrics-and-diags/rules-management.png" alt-text="Screenshot showing the Rules pane with the new alert rules."::: 1. Close the **Alert rules** pane. With these settings, an alert will trigger and you'll get an email notification when more than 1000 messages are sent within a 5-minute time span and also when the total number of messages used exceeds 4000 (50% of the daily quota for an IoT hub in the free tier). ## Run the simulated device app In the [Set up resources](#set-up-resources) section, you registered a device identity to use to simulate using an IoT device. In this section, you download a .NET console app that simulates a device that sends device-to-cloud messages to an IoT hub, configure it to send these messages to your IoT hub, and then run it. > [!IMPORTANT] > > Alerts can take up to 10 minutes to be fully configured and enabled by IoT Hub. Wait at least 10 minutes between the time you configure your last alert and running the simulated device app. Download or clone the solution for the [Azure IoT C# SDK repo](https://github.com/Azure/azure-iot-sdk-csharp) from GitHub. This repo contains several sample applications. For this tutorial, we'll use iothub/device/samples/getting started/SimulatedDevice/. 1. In a local terminal window, navigate to the root folder of the solution. Then navigate to the **iothub\device\samples\getting started\SimulatedDevice** folder. 1. Open the **SimulatedDevice.cs** file in a text editor of your choice. 1. Replace the value of the `s_connectionString` variable with the device connection string you noted when you ran the script to set up resources. 1. In the `SendDeviceToCloudMessagesAsync` method, change the `Task.Delay` from 1000 to 1, which reduces the amount of time between sending messages from 1 second to 0.001 second. Shortening this delay increases the number of messages sent. (You'll likely not get a message rate of 100 messages per second.)