Merge pull request #50599 from ShawnKupfer/WB1799

v-ccolin · web-flow · commit 534f4dfd8e52 · 2025-05-30T15:18:54.000+01:00
AB#1055036: Use telemetry in a .NET Aspire project
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/1-introduction.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/1-introduction.yml
@@ -7,7 +7,7 @@ metadata:
   author: camsoper
   ms.author: casoper
   ms.topic: unit
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.custom: devx-track-dotnet
 durationInMinutes: 1
 content: |
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/2-telemetry-apis-dotnet.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/2-telemetry-apis-dotnet.yml
@@ -6,7 +6,7 @@ metadata:
   description: In this unit, you'll learn about the different sources of telemetry data in .NET.
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
   ms.custom: devx-track-dotnet
 durationInMinutes: 7
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/3-telemetry-dotnet-aspire.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/3-telemetry-dotnet-aspire.yml
@@ -6,7 +6,7 @@ metadata:
   description: In this unit, you'll learn how to use OpenTelemetry APIs to instrument a microservice in a .NET Aspire cloud-native app.
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
   ms.custom: devx-track-dotnet
 durationInMinutes: 7
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/4-dotnet-aspire-dashboard.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/4-dotnet-aspire-dashboard.yml
@@ -7,7 +7,7 @@ metadata:
   author: camsoper
   ms.author: casoper
   ms.topic: unit
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.custom: devx-track-dotnet
 durationInMinutes: 7
 content: |
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/5-ilogger-custom-log-messages.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/5-ilogger-custom-log-messages.yml
@@ -6,7 +6,7 @@ metadata:
   description: In this unit, you'll learn how to add messages to structured logs by using a logger object.
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
 durationInMinutes: 5
 content: |
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/6-exercise-use-telemetry-dotnet-aspire.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/6-exercise-use-telemetry-dotnet-aspire.yml
@@ -6,7 +6,7 @@ metadata:
   description: In this unit, you'll instrument a .NET Aspire cloud-native app and examine the data it emits in the dashboard.
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
   ms.custom: devx-track-dotnet
 durationInMinutes: 10
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/7-knowledge-check.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/7-knowledge-check.yml
@@ -6,24 +6,24 @@ metadata:
   description: "In this unit, you'll answer questions about telemetry in .NET Aspire to check the knowledge you've gained in this module."
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
   ms.custom: team=cloud_advocates, devx-track-dotnet
 durationInMinutes: 5
 content: |
 quiz:
   questions:
-  - content: "You have deployed your cloud-native app to production. Some users are complaining that the product catalog is slow to load. You want to see how request durations vary over time. Which type of telemetry should you use?"
+  - content: "You deployed your cloud-native app to production. Some users are complaining that the product catalog is slow to load. You want to see how request durations vary over time. Which type of telemetry should you use?"
     choices:
     - content: "Logs"
       isCorrect: false
-      explanation: "Incorrect. Logs provided a timestamped record of what happened, but it's not straight forward to display visually how durations vary."
+      explanation: "Incorrect. Logs provide a timestamped record of what happened, but it's not straightforward to display visually how durations vary."
     - content: "Metrics"
       isCorrect: true
       explanation: "Correct. By using the request duration counter, you can display a graph in the .NET Aspire dashboard that shows how durations vary over various time periods."
     - content: "Distributed traces"
       isCorrect: false
-      explanation: "Incorrect. Distributed traces can show the duration of a single request but it's not straight forward to display visually how durations vary."
+      explanation: "Incorrect. Distributed traces can show the duration of a single request, but it's not straightforward to display visually how durations vary."
   - content: "You're troubleshooting an issue with a microservice, which is experiencing crashes. Which type of telemetry should you use?"
     choices:
     - content: "Logs"
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/8-summary.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/8-summary.yml
@@ -6,7 +6,7 @@ metadata:
   description: In this unit, you'll review what you've learned about telemetry in .NET Aspire cloud-native applications.
   author: camsoper
   ms.author: casoper
-  ms.date: 8/20/2024
+  ms.date: 05/21/2025
   ms.topic: unit
   ms.custom: devx-track-dotnet
 durationInMinutes: 5
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/1-introduction.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/1-introduction.md
@@ -1,8 +1,8 @@
-Cloud-native applications consist of independent microservices that may execute as a distributed set of containers. It can be difficult to study the behavior of the entire application to diagnose bugs or performance issues. You should consider early how to record telemetry data. .NET Aspire provides a dashboard that displays telemetry in a developer focused view.
-   
+Cloud-native applications consist of independent microservices that may execute as a distributed set of containers. It can be difficult to study the entire application's behavior to diagnose bugs or performance issues. You should consider early how to record telemetry data. .NET Aspire provides a dashboard that displays telemetry in a developer focused view.
+
 Imagine you're an employee at an outdoor equipment retailer. You've started to build your new cloud-native app and you've integrated .NET Aspire to manage and connect your microservices. Now, you want to study the performance of the microservices and obtain details when bugs arise in your code.
 
-In this module, you'll see how .NET Aspire makes it easy to both record and examine telemetry in a cloud-native app.
+In this module, you'll learn how .NET Aspire makes it easy to both record and examine telemetry in a cloud-native app.
 
 ## Learning objectives
 
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/2-telemetry-apis-dotnet.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/2-telemetry-apis-dotnet.md
@@ -1,12 +1,12 @@
-How can you investigate the behavior of an app for troubleshooting or performance optimization? The more data you have about what the app did, the easier it is to diagnose problems.
+How can you investigate an app's behavior for troubleshooting or performance optimization? The more data you have about what the app did, the easier it is to diagnose problems.
 
-Imagine you work for an outdoor equipment retailer. Your teams are building their microservices, ready for the testing phase. You want to ensure that your cloud-native app emits telemetry about its behavior so that you can diagnose problems during testing, staging, and production.
+Imagine you work for an outdoor equipment retailer. Your teams are building their microservices and are ready for the testing phase. You want to ensure that your cloud-native app emits telemetry about its behavior so that you can diagnose problems during testing, staging, and production.
 
 In this unit, you'll learn about telemetry and the different kinds of data you can record with it.
 
 ## What is telemetry?
 
-In engineering, telemetry is the measurement of data and its automatic transmission to a central system for monitoring. For example, a racing car may record data about its performance and send it back to the paddock where engineers analyze it. Similarly a space capsule might record information about conditions in the capsule and send it back to mission control. In recent years, it's become common to record and analyze telemetry data in more common systems. For example, your central heating may send telemetry to the manufacturer to assist in troubleshooting.
+In engineering, telemetry is the measurement of data and its automatic transmission to a central system for monitoring. For example, a racing car might record data about its performance and send it back to the paddock where engineers analyze it. Similarly, a space capsule might record information about conditions in the capsule and send it back to mission control. In recent years, it's become common to record and analyze telemetry data in more common systems. For example, your central heating might send telemetry to the manufacturer to assist in troubleshooting.
 
 If you're writing cloud-native apps, telemetry is helpful when:
 
@@ -17,37 +17,37 @@ If you're writing cloud-native apps, telemetry is helpful when:
 
 We can describe a system that emits rich telemetry as:
 
-- **Observable**: An observable system is one that enables you to understand its behavior from outside it.
+- **Observable**: An observable system is one that allows you to understand its behavior from outside the system.
 - **Instrumented**: An instrumented system is one that emits all the data developers need to troubleshoot an issue.
 
 **OpenTelemetry** is an observability framework and toolkit that you can use in your app to create, process, and emit telemetry data. You can easily add it to any .NET application, including microservices in a cloud-native app. It emits data in forms that common observability tools like Jaeger and Prometheus can use and analyze.
 
 ## Pillars of observability
 
-The nature of cloud-native apps, which consist of distributed microservices that use disparate technologies, can make it difficult to build observable and properly instrumented code. All teams must integrate observability into their microservices, otherwise you may find that part of your app is difficult to monitor and troubleshoot.
+The nature of cloud-native apps, which consist of distributed microservices that use disparate technologies, can make it difficult to build observable and properly instrumented code. All teams must integrate observability into their microservices, otherwise you might find that part of your app is difficult to monitor and troubleshoot.
 
 > [!IMPORTANT]
 > To ensure that your entire app is observable, you should ensure that all development teams consider the three pillars of observability in their microservices: **Logging**, **Metrics**, and **Tracing**.
 
 The three pillars of observability are three different types of records that store the behavior of software integrations for later analysis:
 
-- **Log**: a timestamped text record of what happened during the processing of a request.
-- **Metric**: a measurement of a service captured at runtime. Metric values can be aggregated into statistics about a process, including:
-  - .NET Runtime statistics such as the memory used, or the number of garbage collections that occurred.
-  - ASP.NET or NuGet package statistics such as the number of completed requests, request durations, or error counts.
+- **Log**: A timestamped text record of what happened during the processing of a request.
+- **Metric**: A measurement of a service captured at runtime. Metric values can be aggregated into statistics about a process, including:
+  - .NET Runtime statistics, such as the memory used or the number of garbage collections that occurred.
+  - ASP.NET or NuGet package statistics, such as the number of completed requests, request durations, or error counts.
   - Custom statistics that are specific to your app, such as the number of orders placed.
-- **Distributed Trace**: a record of all the units of work, often referred to as **Spans**, needed to handle an individual request. In a cloud-native app, many microservices and backing services may be involved in a single request and a distributed trace would show all of them as they collaborate to prepare the response.
+- **Distributed Trace**: A record of all the units of work, often referred to as *Spans*, needed to handle an individual request. In a cloud-native app, many microservices and backing services might be involved in a single request, and a distributed trace would show all of them as they collaborate to prepare the response.
 
 > [!NOTE]
-> In OpenTelemetry, any data that is not part of a distributed trace or a metric is considered to be a log, for example, events.
+> In OpenTelemetry, any data that is not part of a distributed trace or a metric is considered to be a log; for example, events.
 
 ## Using telemetry in .NET
 
 .NET has built-in types to represent the three pillars:
 
 - **ILogger**: This interface provides a standard interface you can use when you what to log events from any .NET code.
 - **Meter**: You can use this class to create a group of instruments, each of which measures a value associated with the performance or behavior of your code. For example, you could add an instrument that counts the sales of a product, or another that measures the length of time a message waited in a queue. .NET also provides many built-in metrics.
-- **Activity**: You can use this class to record the tracing information. Start by creating an `ActivitySource` object for your namespace. Then call the `StartActivity` method to begin recording data.
+- **Activity**: You can use this class to record the tracing information. Start by creating an `ActivitySource` object for your namespace, then call the `StartActivity` method to begin recording data.
 
 You can use these classes in any .NET code. In the next unit you'll see how .NET Aspire makes it easier to use OpenTelemetry classes in cloud-native apps.
 
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/3-telemetry-dotnet-aspire.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/3-telemetry-dotnet-aspire.md
@@ -10,7 +10,7 @@ A principal aim in the design and implementation of .NET Aspire is to ensure tha
 
 .NET Aspire integrations also have built-in support for telemetry.
 
-.NET Aspire provides the .NET Aspire dashboard when you debug locally. This web interface includes rich tools that display logs, metrics in graphical formats, and traces in timelines. 
+.NET Aspire provides the .NET Aspire dashboard when you debug locally. This web interface includes rich tools that display logs, metrics in graphical formats, and traces in timelines.
 
 :::image type="content" source="../media/aspire-dashboard-traces.png" lightbox="../media/aspire-dashboard-traces.png" alt-text="Screenshot showing the Traces page in the .NET Aspire dashboard.":::
 
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/4-dotnet-aspire-dashboard.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/4-dotnet-aspire-dashboard.md
@@ -16,24 +16,24 @@ When you start an app built with .NET Aspire on your development computer, and t
 
 ## Logs in the dashboard
 
-Logged events describe what happens as your app starts and runs. You can see two types of logged information in the dashboard: console logs and structured logs.
+Logged events describe what happens as your app starts and runs. You can see two types of logged information in the dashboard: *console logs* and *structured logs*.
 
 ### Console logs
 
-Console logs display text that your app has sent to standard output. A command-line program would display such text as lines in the console but microservices and backing services have no intrinsic place to display standard output. .NET Aspire helps by providing the **Console logs** page in the dashboard.
+Console logs display text that your app has sent to standard output. A command-line program would display such text as lines in the console, but microservices and backing services have no intrinsic place to display standard output. .NET Aspire helps by providing the **Console logs** page in the dashboard.
 
 When you open the page, you must first select a source integration, such as one of your microservices. The tool displays all the standard output from that source in the main window with some formatting. For example, the information events are shown in green while failures are shown in red.
 
-Console logs are simply lines of text. They are easy for applications to create and emit, but they are hard to read for humans and difficult to process for analysis purposes because they lack structure.
+Console logs are simply lines of text. They are easy for applications to create and emit, but they are hard for humans to read and difficult to process for analysis purposes because they lack structure.
 
 :::image type="content" source="../media/dashboard-console-logs.png" lightbox="../media/dashboard-console-logs.png" alt-text="Screenshot showing the console logs in the .NET Aspire dashboard.":::
 
 ### Structured logs
 
-Instead of flat text, structured logs preserve logged messages with their template and message parameters. This structure makes it easier to filter out events that are irrelevant so you can drill down to troubleshoot a specific problem. In a production environment, the logs can be persisted, indexed, and then queried like a database. In this way you can perform rich analytics on the data that they contain.
+Instead of flat text, structured logs preserve logged messages with their template and message parameters. This structure makes it easier to filter out events that are irrelevant so you can drill down to troubleshoot a specific problem. In a production environment, the logs can be persisted, indexed, and then queried like a database. In this way, you can perform rich analytics on the data that they contain.
 
 > [!NOTE]
-> Structured logs are also often called semantic logs.
+> Structured logs are also often called *semantic logs*.
 
 In your code, send an event to the structured logs by using an OpenTelemetry `ILogger` object:
 
@@ -47,21 +47,21 @@ In the .NET dashboard, the **Structured logs** page shows events from every reso
 
 ## Distributed traces in the dashboard
 
-A trace is a record that describes how a request was processed and returned to the caller. Each trace might involve calls to multiple integrations in your app. For example, when a user requests the product catalog web page, the web UI microservice might receive the request, which may call the authentication microservice, the catalog microservice, and the Redis cache, before returning a web page to the user.
+A trace is a record that describes how a request was processed and returned to the caller. Each trace might involve calls to multiple integrations in your app. For example, when a user requests the product catalog web page, the web UI microservice might receive the request, which might call the authentication microservice, the catalog microservice, and the Redis cache before returning a web page to the user.
 
 :::image type="content" source="../media/dashboard-traces.png" lightbox="../media/dashboard-traces.png" alt-text="Screenshot showing the list of traces in the .NET Aspire dashboard.":::
 
-Each trace is composed of spans, such as the call to the catalog microservice. The system records each span with its timing and parent information, so that you can see which integration responds rapidly and which causes delays. Further details are available for each span.
+Each trace is composed of spans, such as the call to the catalog microservice. The system records each span with its timing and parent information so you can see which integration responds rapidly and which causes delays. Further details are available for each span.
 
 :::image type="content" source="../media/dashboard-single-trace.png" lightbox="../media/dashboard-single-trace.png" alt-text="Screenshot showing an individual trace in the .NET Aspire dashboard.":::
 
 Similar to structured logs, you can select the source and apply filters to drill down and locate traces for the specific problem you're interested in diagnosing.
 
 ## Metrics in the dashboard
 
-Metrics are values that vary over time, recorded by a integration of your app. For example, metrics may record the duration of a request and response or a count of the active connections to your catalog microservice. Some metrics are built into .NET, some come with the OpenTelemetry SDK libraries, and developers can add custom OpenTelemetry metrics that are unique to their integration.
+Metrics are values that vary over time, recorded by an integration of your app. For example, metrics might record the duration of a request and response or a count of the active connections to your catalog microservice. Some metrics are built into .NET, some come with the OpenTelemetry SDK libraries, and developers can add custom OpenTelemetry metrics that are unique to their integration.
 
-The .NET Aspire dashboard includes the **Metrics** section, which you can use to investigate and display how metrics vary over time. 
+The .NET Aspire dashboard includes the **Metrics** section, which you can use to investigate and display how metrics vary over time.
 
 For example, the **http.server.active_requests** metric displays the number of requests being processed at any given moment:
 
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/5-ilogger-custom-log-messages.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/5-ilogger-custom-log-messages.md
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/6-exercise-use-telemetry-dotnet-aspire.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/6-exercise-use-telemetry-dotnet-aspire.md
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/8-summary.md b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/includes/8-summary.md
diff --git a/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/index.yml b/learn-pr/aspnetcore/use-telemetry-dotnet-aspire/index.yml
