From 71430c3ef891496797f0ecbc897a30a629f6bdc4 Mon Sep 17 00:00:00 2001 From: Yun-Ting Date: Mon, 25 Aug 2025 14:20:49 -0700 Subject: [PATCH 1/4] first pass --- docs/docs/Demos.0.DurableID.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/docs/Demos.0.DurableID.md b/docs/docs/Demos.0.DurableID.md index 08db5535..a740b2fd 100644 --- a/docs/docs/Demos.0.DurableID.md +++ b/docs/docs/Demos.0.DurableID.md @@ -6,7 +6,7 @@ description : Demo Showing DurableID # Demo 0 - Durable ID's Explanation -## Using DurableID in OpenTelemetry, to locate the source of the the expense +## Using DurableID in OpenTelemetry, to locate the source of the expense This demonstration will showcase and contrast two logging messages in OpenTelemetry. One will use a Durable ID, and the other will not. It's @@ -16,10 +16,11 @@ considered a best practice. A Durable ID functions like a GPS or homing beacon, mapping any row of telemetry to a specific line of code. In Microsoft .NET platform, a Durable ID is created automatically at -compile time for OpenTelemetry user using 'ILogger', when the author of the -software follows best practices. +compile-time for an OpenTelemetry user using +[ILogger](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger?view=net-8.0-pp), +when the author of the software follows best practices. -### Contrasting C# that makes use of Durable ID's, with C# that does not +### Contrasting C# that makes use of Durable IDs, with C# that does not Let's examine code that makes use of a Durable ID versus one that doesn't. We'll inspect both in the Application Insights Log database, to spot @@ -27,8 +28,8 @@ the difference. ### Seeing the DurableID in Azure's Application Insights -Let's start with the recommended way to log in .NET: using 'ILogger', with a -compiler-generated Durable ID. +Let's start with the recommended way to log in .NET: using ``ILogger``, with a +[compiler-time generated](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator) Durable ID. #### Recommended Way to Log @@ -53,13 +54,13 @@ compiler-generated Durable ID. ```cdocs_include {{ CSharp_Include("../Samples/DurableIds/Pages/Index.cshtml.cs", "// StartExample:ContrastDurableID", - "// EndExample:ContrastDurableID") + "// EndExample:ContrastDurableID") }} ``` #### Spotting the difference in your database -While both of these logging methods result in the same printf() ('flatted') log, +While both of these logging methods result in the same printf() ('flattened') log, the one with the Durable ID offers many extra goodies. Please recall the source snippets above; when these two lines of code manifest @@ -96,7 +97,7 @@ as any number of the Dynamic Telemetry scenarios. ## Use Azure Monitor and KQL language to locate an expensive OpenTelemetry log -Lets go back to the original code; and use the compiler generated Durable ID to +Let's go back to the original code; and use the compiler generated Durable ID to quickly count the ILogger log, that followed recommended guidance. ```cdocs_include @@ -114,7 +115,7 @@ quickly count the ILogger log, that followed recommended guidance. ``` This time, instead of trying to deduplicate with the message (where the GUID all -bug guarantees each row is unique), we will deduplicate with the +but guarantees each row is unique), we will deduplicate with the extracted EventName field. ![](../orig_media/Demo.0.DurableID.GroupedByEventName.png) From 81a56f3832bc7ef6cccba8f88c302d2bb190facf Mon Sep 17 00:00:00 2001 From: Yun-Ting Date: Mon, 25 Aug 2025 14:27:49 -0700 Subject: [PATCH 2/4] second pass --- docs/docs/Demos.0.DurableID.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/docs/Demos.0.DurableID.md b/docs/docs/Demos.0.DurableID.md index a740b2fd..c1e65b5b 100644 --- a/docs/docs/Demos.0.DurableID.md +++ b/docs/docs/Demos.0.DurableID.md @@ -4,9 +4,9 @@ status: ReviewLevel1 description : Demo Showing DurableID --- -# Demo 0 - Durable ID's Explanation +# Demo 0 - Durable IDs Explanation -## Using DurableID in OpenTelemetry, to locate the source of the expense +## Using DurableID in OpenTelemetry to locate the source of the expense This demonstration will showcase and contrast two logging messages in OpenTelemetry. One will use a Durable ID, and the other will not. It's @@ -15,21 +15,22 @@ identifier, even though, in Dynamic Telemetry, the use of the DurableID is considered a best practice. A Durable ID functions like a GPS or homing beacon, mapping any row of telemetry to a specific line of code. -In Microsoft .NET platform, a Durable ID is created automatically at +In the Microsoft .NET platform, a Durable ID is created automatically at compile-time for an OpenTelemetry user using [ILogger](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger?view=net-8.0-pp), when the author of the software follows best practices. ### Contrasting C# that makes use of Durable IDs, with C# that does not -Let's examine code that makes use of a Durable ID versus one that -doesn't. We'll inspect both in the Application Insights Log database, to spot +Let's examine code that uses a Durable ID versus code that does not. +We'll inspect both in the Application Insights Log database, to spot the difference. ### Seeing the DurableID in Azure's Application Insights -Let's start with the recommended way to log in .NET: using ``ILogger``, with a -[compiler-time generated](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator) Durable ID. +Let's start with the recommended way to log in .NET: using `ILogger`, with a +[compiler-time generated](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator) +Durable ID. #### Recommended Way to Log @@ -63,7 +64,7 @@ Let's start with the recommended way to log in .NET: using ``ILogger``, with a While both of these logging methods result in the same printf() ('flattened') log, the one with the Durable ID offers many extra goodies. -Please recall the source snippets above; when these two lines of code manifest +Please recall the source snippets above: when these two lines of code manifest in our database, they look as follows. ![](../orig_media/Demo.0.DurableID.WithAndWithoutContrast.png) @@ -80,25 +81,25 @@ You can see an expanded version of these fields below. #### Trying to reason over lots of Logs -Scenarios that require performant study and aggregation of clusters of Logs, -really struggle with 'flattened' logs. This is discussed more in the +Scenarios that require performant study and aggregation of clusters of Logs +really struggle with "flattened" logs. This is discussed more in the [Position Paper on Durable -ID's](./PositionPaper.DurableIds_StructuredPayloads.document.md), but in short, +IDs](./PositionPaper.DurableIds_StructuredPayloads.document.md), but in short, due to the addition of a GUID, each row of telemetry is different from another. You can see this quickly, with a quick dcount (distinct count) of each message. ![](../orig_media/Demo.0.DurableID.ShowCollisions.png) -Notice in this screenshot, that the number of distinct messages is similar to +Notice in this screenshot that the number of distinct messages is similar to the number of absolute messages - without a Durable ID, spotting the -differences can be difficult. This in turn complicates cost reductions, as well +differences can be difficult. This, in turn, complicates cost reductions, as well as any number of the Dynamic Telemetry scenarios. ## Use Azure Monitor and KQL language to locate an expensive OpenTelemetry log -Let's go back to the original code; and use the compiler generated Durable ID to -quickly count the ILogger log, that followed recommended guidance. +Let's go back to the original code, and use the compiler-generated Durable ID to +quickly count the ILogger log that followed recommended guidance. ```cdocs_include {{ CSharp_Include("../Samples/DurableIds/Pages/Index.cshtml.cs", @@ -120,7 +121,7 @@ extracted EventName field. ![](../orig_media/Demo.0.DurableID.GroupedByEventName.png) -You'll notice "LogRandomGuid" quickly stands out, with a tidy dcount(), whereas +You'll notice "LogRandomGuid" quickly stands out with a tidy dcount(), whereas the other similar log is still unclear. With the event name in hand, we can quickly do all sorts of quick study and From 03d950195ac989ac4225f8f64b53fe1c6258ea13 Mon Sep 17 00:00:00 2001 From: Yun-Ting Lin Date: Mon, 25 Aug 2025 14:31:14 -0700 Subject: [PATCH 3/4] Update docs/docs/Demos.0.DurableID.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/docs/Demos.0.DurableID.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/Demos.0.DurableID.md b/docs/docs/Demos.0.DurableID.md index c1e65b5b..eb7ecf39 100644 --- a/docs/docs/Demos.0.DurableID.md +++ b/docs/docs/Demos.0.DurableID.md @@ -29,7 +29,7 @@ the difference. ### Seeing the DurableID in Azure's Application Insights Let's start with the recommended way to log in .NET: using `ILogger`, with a -[compiler-time generated](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator) +[compile-time generated](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator) Durable ID. #### Recommended Way to Log From b14ab088ebf711527747aadf851c9c7e805cf7fd Mon Sep 17 00:00:00 2001 From: Yun-Ting Date: Mon, 25 Aug 2025 16:00:57 -0700 Subject: [PATCH 4/4] lint --- docs/docs/Demos.0.DurableID.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/Demos.0.DurableID.md b/docs/docs/Demos.0.DurableID.md index c1e65b5b..44208c15 100644 --- a/docs/docs/Demos.0.DurableID.md +++ b/docs/docs/Demos.0.DurableID.md @@ -55,7 +55,7 @@ Durable ID. ```cdocs_include {{ CSharp_Include("../Samples/DurableIds/Pages/Index.cshtml.cs", "// StartExample:ContrastDurableID", - "// EndExample:ContrastDurableID") + "// EndExample:ContrastDurableID") }} ```