Readthrough edits to dh article

baanders · baanders · commit 671b7894a35a · 2024-01-22T10:08:54.000-05:00
diff --git a/articles/digital-twins/how-to-create-data-history-connection.md b/articles/digital-twins/how-to-create-data-history-connection.md
@@ -4,7 +4,7 @@ titleSuffix: Azure Digital Twins
 description: See how to set up a data history connection for historizing Azure Digital Twins updates into Azure Data Explorer.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 06/29/2023
+ms.date: 01/22/2024
 ms.topic: how-to
 ms.service: digital-twins
 ms.custom: event-tier1-build-2022, devx-track-azurecli
@@ -83,6 +83,12 @@ If you don't have an Azure Digital Twins instance, follow the instructions in [C
 
 Then, make sure you have *Azure Digital Twins Data Owner* role on the instance. You can find instructions in [Set up user access permissions](how-to-set-up-instance-cli.md#set-up-user-access-permissions).
 
+If you'd like to add the name of your instance to your local CLI variables so it will automatically be plugged into later commands copied from this article, store it in the variable `dtname` like this:
+
+```dotnetcli
+dtname="<name-of-your-instance>"
+```
+
 ## Create an Event Hubs namespace and event hub
 
 The next step is to create an Event Hubs namespace and an event hub. This hub will receive graph lifecycle and property update notifications from the Azure Digital Twins instance and then forward the messages to the target Azure Data Explorer cluster. 
@@ -172,7 +178,7 @@ Use the command in this section to create a data history connection and the tabl
 
 The command below uses local variables that were created earlier in [Set up local variables for CLI session](#set-up-local-variables-for-cli-session) and has several parameters, including...
 * The names of the relationship lifecycle and twin lifecycle tables in Azure Data Explorer (these parameters are optional if you don't want to historize these event types, but required if you do want to historize these event types)
-* An optional parameter to specify the name of the twin property event table (if this value is not provided, this table will be named *AdtPropertyEvents* by default) 
+* An optional parameter to specify the name of the twin property event table (if this value is not provided, this table will be named *AdtPropertyEvents* by default). If you don't want to specify another name, remove the `--adx-property-events-table` parameter from the command before running it.
 * The optional parameter `--adx-record-removals` to turn on historization for twin property deletions (events that remove properties entirely)
 
 ```azurecli-interactive
@@ -277,37 +283,21 @@ You'll see confirmation messages on the screen as models, twins, and relationshi
 
 When the simulation is ready, the **Start simulation** button will become enabled. Scroll down and select **Start simulation** to push simulated data to your Azure Digital Twins instance. To continuously update the twins in your Azure Digital Twins instance, keep this browser window in the foreground on your desktop and complete other browser actions in a separate window. This will continuously generate twin property updates events that will be historized to Azure Data Explorer.
 
-#### Verify data flow
-
-To verify that data is flowing through the data history pipeline, you can use the [data history validation in Azure Digital Twins Explorer](how-to-use-azure-digital-twins-explorer.md#validate-and-explore-historized-properties). 
-
-1. Navigate to the [Azure Digital Twins Explorer](https://explorer.digitaltwins.azure.net/) and ensure it's [connected to the right instance](how-to-use-azure-digital-twins-explorer.md#switch-contexts-within-the-app).
-
-1. Use the instructions in [Validate and explore historized properties](how-to-use-azure-digital-twins-explorer.md#validate-and-explore-historized-properties) to choose a historized twin property to visualize in the chart.
-
-If you see data being populated in the chart, this means that Azure Digital Twins update events are being successfully stored in Azure Data Explorer.
-
-:::image type="content" source="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png" alt-text="Screenshot of the Data history explorer showing a chart of historized values for a property." lightbox="media/how-to-use-azure-digital-twins-explorer/data-history-explorer-chart.png":::
-
-If you *don't* see data in the chart, the historization data flow isn't working properly. You can investigate the issue by viewing your Event Hubs namespace in the [Azure portal](https://portal.azure.com), which displays charts showing the flow of messages into and out of the namespace. This will allow you to verify both the flow of incoming messages from Azure Digital Twins and the outgoing messages to Azure Data Explorer, to help you identify which part of the flow isn't working.
-
-:::image type="content"  source="media/how-to-create-data-history-connection/simulated-environment-portal.png" alt-text="Screenshot of the Azure portal showing an Event Hubs namespace for the simulated environment." lightbox="media/how-to-create-data-history-connection/simulated-environment-portal.png":::
-
 ### View the historized updates in Azure Data Explorer
 
-Now that you've verified the data history flow is sending data to Azure Data Explorer, this section will show you how to view all three types of historized updates that were generated by the simulator and stored in Azure Data Explorer tables.
+This section will show you how to view all three types of historized updates that were generated by the simulator and stored in Azure Data Explorer tables.
 
 Start in the [Azure portal](https://portal.azure.com) and navigate to the Azure Data Explorer cluster you created earlier. Choose the **Databases** pane from the left menu to open the database view. Find the database you created for this article and select the checkbox next to it, then select **Query**.
 
 :::image type="content"  source="media/how-to-create-data-history-connection/azure-data-explorer-database.png" alt-text="Screenshot of the Azure portal showing a database in an Azure Data Explorer cluster.":::
 
-Next, expand the cluster and database in the left pane to see the name of the data history tables. There should be three: one for relationship lifecycle events, one for twin lifecycle events, and one for twin property update events. You'll use these table names to run queries on the table to verify and view the historized data.
+Next, expand the cluster and database in the left pane to see the name of the data history tables. There should be three: one for relationship lifecycle events, one for twin lifecycle events, and one for twin property update events. You'll use these table names to run queries on the tables to verify and view the historized data.
 
 :::image type="content"  source="media/how-to-create-data-history-connection/data-history-table.png" alt-text="Screenshot of the Azure portal showing the query view for the database. The name of the data history table is highlighted." lightbox="media/how-to-create-data-history-connection/data-history-table.png":::
 
-#### Verify relationship and twin lifecycle updates
+#### Verify table entries
 
-To verify that relationship and twin lifecycle events are being historized to the database, start by copying the following command. It has a placeholder for the name of the relationship lifecycle events table, and it will change the ingestion for the table to [batched mode](concepts-data-history.md#batch-ingestion-default) so it ingests data from the live simulation every 10 seconds.
+To verify that events are being historized to the database, start by copying the following command. It has a placeholder for the name of the **relationship lifecycle events table**, and it will change the ingestion for the table to [batched mode](concepts-data-history.md#batch-ingestion-default) so it ingests data from the live simulation every 10 seconds.
 
 ```kusto
 .alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
@@ -317,13 +307,9 @@ Paste the command into the query window, replacing the placeholder with the name
 
 :::image type="content"  source="media/how-to-create-data-history-connection/data-history-run-query-1.png" alt-text="Screenshot of the Azure portal showing the query view for the database. The Run button is highlighted." lightbox="media/how-to-create-data-history-connection/data-history-run-query-1.png":::
 
-Repeat the process with the following command to update the ingestion mode of the twin lifecycle events table.
-
-```kusto
-.alter table <twin-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
-```
+Repeat the command two more times using the name of the **twin lifecycle events table** and then the **property update table** to update the ingestion mode of the other tables as well.
 
-Next, add the following commands to the query window and run them. Each command contains a placeholder for the name of either the relationship lifecycle events table or the twin lifecycle events table, and the commands will output the number of items in the tables.
+Next, add the following commands to the query window and run them. Each command contains a placeholder for the name of one of the tables, and the commands will output the number of items in the tables.
 
 >[!NOTE]
 > It may take up to 5 minutes for the first batch of ingested data to appear.
@@ -334,33 +320,18 @@ Next, add the following commands to the query window and run them. Each command
 
 <twin-lifecycle-events-table-name>
 | count
-```
-
-You should see in the results that the count of items in each table is something greater than 0, indicating that relationship lifecycle and twin lifecycle events are being historized to their respective tables.
 
-#### Verify and explore twin property updates table
-
-In this section you'll verify that twin property updates are being historized to the corresponding table, and do some more exploration with the data that's coming through.
-
-Start by running the command below. The command has a placeholder for the name of the twin property update table, and it will change the ingestion for the table to [batched mode](concepts-data-history.md#batch-ingestion-default) so it ingests data from the live simulation every 10 seconds.
-
-```kusto
-.alter table <twin-property-updates-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
-```
-
-Next, add the following command to the query window, and run it to verify that Azure Data Explorer has ingested twin updates into the table.
-
->[!NOTE]
-> It may take up to 5 minutes for the first batch of ingested data to appear.
-
-```kusto
 <twin-property-updates-table-name>
 | count
 ```
 
-You should see in the results that the count of items in the table is something greater than 0, indicating that twin property update events are being historized to the table.
+You should see in the results that the count of items in each table is something greater than 0, indicating that relationship lifecycle, twin lifecycle, and property update events are being historized to their respective tables.
+
+#### Explore twin property updates table
+
+In this section you'll do some more exploration with the twin property update data that's in the table.
 
-You can also add and run the following command to view 100 records in the table:
+First, run the following command to view 100 records in the table:
 
 ```kusto
 <twin-property-updates-table-name>
@@ -388,7 +359,13 @@ evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
 
 The results should show the outflow numbers changing over time.
 
-:::image type="content"  source="media/how-to-create-data-history-connection/data-history-run-query-2.png" alt-text="Screenshot of the Azure portal showing the query view for the database. The result for the example query is a line graph showing changing values over time for the salt machine outflows." lightbox="media/how-to-create-data-history-connection/data-history-run-query-2.png":::
+:::image type="content"  source="media/how-to-create-data-history-connection/data-history-run-query-2.png" alt-text="Screenshot of the Azure portal showing the query view for the database." lightbox="media/how-to-create-data-history-connection/data-history-run-query-2.png":::
+
+### Troubleshoot connection
+
+If you don't see data in Azure Data Explorer, the historization data flow isn't working properly. You can investigate the issue by viewing your Event Hubs namespace in the [Azure portal](https://portal.azure.com), which displays charts showing the flow of messages into and out of the namespace. This will allow you to verify both the flow of incoming messages from Azure Digital Twins and the outgoing messages to Azure Data Explorer, to help you identify which part of the flow isn't working.
+
+:::image type="content"  source="media/how-to-create-data-history-connection/simulated-environment-portal.png" alt-text="Screenshot of the Azure portal showing an Event Hubs namespace for the simulated environment." lightbox="media/how-to-create-data-history-connection/simulated-environment-portal.png":::
 
 ## Next steps 
 
