From 9d3f2b98dc6ec1efeaa9fc686ff3f41a1fc601a3 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 4 Jun 2024 11:23:52 +0300 Subject: [PATCH 1/4] Update add status functionality description Replace SetTag to SetStatus --- ...distributed-tracing-instrumentation-walkthroughs.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md index d03cfbf533abe..f682ad007b01b 100644 --- a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md +++ b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md @@ -312,12 +312,9 @@ with the distributed trace. OpenTelemetry allows each Activity to report a [Status](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status) -that represents the pass/fail result of the work. .NET does not currently have a strongly typed API for this purpose but -there is an established convention using Tags: +that represents the pass/fail result of the work. .NET have a strongly typed API for this purpose: -- `otel.status_code` is the Tag name used to store `StatusCode`. Values for the StatusCode tag must be one of the -strings "UNSET", "OK", or "ERROR", which correspond respectively to the enums `Unset`, `Ok`, and `Error` from StatusCode. -- `otel.status_description` is the Tag name used to store the optional `Description` +Values for the ActivityStatusCode respectively to the enums `Unset`, `Ok`, and `Error`. Update DoSomeWork() to set status: @@ -334,8 +331,7 @@ Update DoSomeWork() to set status: activity?.AddEvent(new ActivityEvent("Done now")); // Pretend something went wrong - activity?.SetTag("otel.status_code", "ERROR"); - activity?.SetTag("otel.status_description", "Use this text give more information about the error"); + activity?.SetStatus(ActivityStatusCode.Error, "Use this text give more information about the error"); } } ``` From c075700d22287c153c2e9141dbbd274ca3f06ac5 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 4 Jun 2024 23:09:07 +0300 Subject: [PATCH 2/4] Update docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md Co-authored-by: David Pine --- .../distributed-tracing-instrumentation-walkthroughs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md index f682ad007b01b..89ab207e12d90 100644 --- a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md +++ b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md @@ -312,7 +312,7 @@ with the distributed trace. OpenTelemetry allows each Activity to report a [Status](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status) -that represents the pass/fail result of the work. .NET have a strongly typed API for this purpose: +that represents the pass/fail result of the work. .NET has a strongly-typed API for this purpose: Values for the ActivityStatusCode respectively to the enums `Unset`, `Ok`, and `Error`. From d8c02ef5361f95d99ac29f6134265e9930397b9f Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 4 Jun 2024 23:09:30 +0300 Subject: [PATCH 3/4] Update docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md Co-authored-by: David Pine --- .../distributed-tracing-instrumentation-walkthroughs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md index 89ab207e12d90..b5c3326625a58 100644 --- a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md +++ b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md @@ -314,7 +314,7 @@ OpenTelemetry allows each Activity to report a [Status](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status) that represents the pass/fail result of the work. .NET has a strongly-typed API for this purpose: -Values for the ActivityStatusCode respectively to the enums `Unset`, `Ok`, and `Error`. +The values are represented as either, `Unset`, `Ok`, and `Error`. Update DoSomeWork() to set status: From e8796d4f38ccd32ad4b594d7ee981a24986e3e7a Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 5 Jun 2024 18:51:02 -0500 Subject: [PATCH 4/4] Update distributed-tracing-instrumentation-walkthroughs.md --- ...ed-tracing-instrumentation-walkthroughs.md | 130 +++++++++--------- 1 file changed, 63 insertions(+), 67 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md index b5c3326625a58..5365970e922c3 100644 --- a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md +++ b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md @@ -2,7 +2,7 @@ title: Add distributed tracing instrumentation - .NET description: A tutorial to instrument distributed traces in .NET applications ms.topic: tutorial -ms.date: 03/14/2021 +ms.date: 06/05/2024 --- # Adding distributed tracing instrumentation @@ -132,7 +132,7 @@ namespace Sample.DistributedTracing static async Task Main(string[] args) { - ... + // ... ``` #### Best practices @@ -163,14 +163,14 @@ Use the ActivitySource object to Start and Stop Activity objects around meaningf DoSomeWork() with the code shown here: ```csharp - static async Task DoSomeWork(string foo, int bar) - { - using (Activity activity = source.StartActivity("SomeWork")) - { - await StepOne(); - await StepTwo(); - } - } +static async Task DoSomeWork(string foo, int bar) +{ + using (Activity activity = source.StartActivity("SomeWork")) + { + await StepOne(); + await StepTwo(); + } +} ``` Running the app now shows the new Activity being logged: @@ -195,27 +195,23 @@ the created Activity object after executing the block. Disposing the Activity ob doesn't need to explicitly call . That simplifies the coding pattern. -- internally determines if -there are any listeners recording the Activity. If there are no registered listeners or there are listeners that -are not interested, `StartActivity()` will return `null` and avoid creating the Activity object. This -is a performance optimization so that the code pattern can still be used in functions that are called frequently. +- internally determines if there are any listeners recording the Activity. If there are no registered listeners or there are listeners that are not interested, `StartActivity()` will return `null` and avoid creating the Activity object. This is a performance optimization so that the code pattern can still be used in functions that are called frequently. ## Optional: Populate tags -Activities support key-value data called Tags, commonly used to store any parameters of the work that -may be useful for diagnostics. Update DoSomeWork() to include them: +Activities support key-value data called Tags, commonly used to store any parameters of the work that may be useful for diagnostics. Update `DoSomeWork()` to include them: ```csharp - static async Task DoSomeWork(string foo, int bar) - { - using (Activity activity = source.StartActivity("SomeWork")) - { - activity?.SetTag("foo", foo); - activity?.SetTag("bar", bar); - await StepOne(); - await StepTwo(); - } - } +static async Task DoSomeWork(string foo, int bar) +{ + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + await StepTwo(); + } +} ``` ```dotnetcli @@ -265,18 +261,18 @@ Events are timestamped messages that can attach an arbitrary stream of additiona some events to the Activity: ```csharp - static async Task DoSomeWork(string foo, int bar) - { - using (Activity activity = source.StartActivity("SomeWork")) - { - activity?.SetTag("foo", foo); - activity?.SetTag("bar", bar); - await StepOne(); - activity?.AddEvent(new ActivityEvent("Part way there")); - await StepTwo(); - activity?.AddEvent(new ActivityEvent("Done now")); - } - } +static async Task DoSomeWork(string foo, int bar) +{ + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + activity?.AddEvent(new ActivityEvent("Part way there")); + await StepTwo(); + activity?.AddEvent(new ActivityEvent("Done now")); + } +} ``` ```dotnetcli @@ -319,21 +315,21 @@ The values are represented as eithe Update DoSomeWork() to set status: ```csharp - static async Task DoSomeWork(string foo, int bar) - { - using (Activity activity = source.StartActivity("SomeWork")) - { - activity?.SetTag("foo", foo); - activity?.SetTag("bar", bar); - await StepOne(); - activity?.AddEvent(new ActivityEvent("Part way there")); - await StepTwo(); - activity?.AddEvent(new ActivityEvent("Done now")); - - // Pretend something went wrong - activity?.SetStatus(ActivityStatusCode.Error, "Use this text give more information about the error"); - } - } +static async Task DoSomeWork(string foo, int bar) +{ + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + activity?.AddEvent(new ActivityEvent("Part way there")); + await StepTwo(); + activity?.AddEvent(new ActivityEvent("Done now")); + + // Pretend something went wrong + activity?.SetStatus(ActivityStatusCode.Error, "Use this text give more information about the error"); + } +} ``` ## Optional: Add additional Activities @@ -347,21 +343,21 @@ verbose traces, so it's not recommended. Update StepOne and StepTwo to add more tracing around these separate steps: ```csharp - static async Task StepOne() - { - using (Activity activity = source.StartActivity("StepOne")) - { - await Task.Delay(500); - } - } +static async Task StepOne() +{ + using (Activity activity = source.StartActivity("StepOne")) + { + await Task.Delay(500); + } +} - static async Task StepTwo() - { - using (Activity activity = source.StartActivity("StepTwo")) - { - await Task.Delay(1000); - } - } +static async Task StepTwo() +{ + using (Activity activity = source.StartActivity("StepTwo")) + { + await Task.Delay(1000); + } +} ``` ```dotnetcli