From 0fa42b8a535595e3cb4c84dd2b347c86682dd224 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 8 Feb 2024 19:29:52 -0800 Subject: [PATCH 1/2] Update the docs based on Copilot review feedback --- docs/logs/README.md | 6 +++--- docs/metrics/README.md | 36 ++++++++++++++++++------------------ docs/trace/README.md | 17 ++++++++--------- 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/logs/README.md b/docs/logs/README.md index 478734ef829..fd57847ef4e 100644 --- a/docs/logs/README.md +++ b/docs/logs/README.md @@ -32,7 +32,7 @@ OpenTelemetry .NET: :heavy_check_mark: You should use structured logging. * Structured logging is more efficient than unstructured logging. - * Filtering and redaction can happen on invidual key-value pairs instead of + * Filtering and redaction can happen on indvidual key-value pairs instead of the entire log message. * Storage and indexing are more efficient. * Structured logging makes it easier to manage and consume logs. @@ -63,8 +63,8 @@ from the latest stable version of [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging/) package, regardless of the .NET runtime version being used: -* If you're using the latest stable version of [OpenTelemetry .NET - SDK](../../src/OpenTelemetry/README.md), you don't have to worry about the +* If you are using the latest stable version of [OpenTelemetry .NET + SDK](../../src/OpenTelemetry/README.md), you do not have to worry about the version of `Microsoft.Extensions.Logging` package because it is already taken care of for you via [package dependency](../../Directory.Packages.props). * Starting from version `3.1.0`, the .NET runtime team is holding a high bar for diff --git a/docs/metrics/README.md b/docs/metrics/README.md index b58d55023c4..bd03ff1126b 100644 --- a/docs/metrics/README.md +++ b/docs/metrics/README.md @@ -22,8 +22,8 @@ ## Best Practices -The following tutorials have demonstrated the best practices for while using -metrics with OpenTelemetry .NET: +The following tutorials have demonstrated the best practices for using metrics +with OpenTelemetry .NET: * [Getting Started - ASP.NET Core Application](./getting-started-aspnetcore/README.md) @@ -37,8 +37,8 @@ APIs from the latest stable version of [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) package, regardless of the .NET runtime version being used: -* If you're using the latest stable version of [OpenTelemetry .NET - SDK](../../src/OpenTelemetry/README.md), you don't have to worry about the +* If you are using the latest stable version of [OpenTelemetry .NET + SDK](../../src/OpenTelemetry/README.md), you do not have to worry about the version of `System.Diagnostics.DiagnosticSource` package because it is already taken care of for you via [package dependency](../../Directory.Packages.props). @@ -163,9 +163,9 @@ Here is the rule of thumb: > [!NOTE] > When reporting measurements with more than 8 tags, the API allocates memory on - the hot-path. You SHOULD try to keep the number of tags less than or equal to 8. - If you are exceeding this, check if you can model some of the tags as Resource, - as [shown here](#metrics-enrichment). + the hot code path. You SHOULD try to keep the number of tags less than or + equal to 8. If you are exceeding this, check if you can model some of the tags + as Resource, as [shown here](#metrics-enrichment). ## MeterProvider Management @@ -232,9 +232,9 @@ In OpenTelemetry, [measurements](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#measurement) are reported via the metrics API. The SDK [aggregates](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#aggregation) -metrics using certain algorithm and memory management strategy to achieve good -performance and efficiency. Here are the rules which OpenTelemetry .NET follows -while implementing the metrics aggregation logic: +metrics using certain algorithms and memory management strategies to achieve +good performance and efficiency. Here are the rules which OpenTelemetry .NET +follows while implementing the metrics aggregation logic: 1. [**Pre-Aggregation**](#pre-aggregation): aggregation occurs within the SDK. 2. [**Cardinality Limits**](#cardinality-limits): the aggregation logic respects @@ -249,7 +249,7 @@ while implementing the metrics aggregation logic: ### Example -Let's take the following example: +Let us take the following example: * During the time range (T0, T1]: * value = 1, name = `apple`, color = `red` @@ -285,7 +285,7 @@ Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/ * attributes: {name = `apple`, color = `red`}, count: `1` * attributes: {verb = `lemon`, color = `yellow`}, count: `2` * (T1, T2] - * nothing since we don't have any measurement received + * nothing since we do not have any measurement received * (T2, T3] * attributes: {name = `apple`, color = `red`}, count: `5` * attributes: {name = `apple`, color = `green`}, count: `2` @@ -294,8 +294,8 @@ Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/ ### Pre-Aggregation Taking the [fruit example](#example), there are 6 measurements reported during -`(T2, T3]`. Instead of exporting every individual measurement events, the SDK -aggregates them and only export the summarized results. This approach, as +`(T2, T3]`. Instead of exporting every individual measurement event, the SDK +aggregates them and only exports the summarized results. This approach, as illustrated in the following diagram, is called pre-aggregation: ```mermaid @@ -312,7 +312,7 @@ end Pre-Aggregation --> | Metrics | Aggregation ``` -Pre-aggregation brings serveral benefits: +Pre-aggregation brings several benefits: 1. Although the amount of calculation remains the same, the amount of data transmitted can be significantly reduced using pre-aggregation, thus @@ -364,12 +364,12 @@ table to summarize the total number of fruits based on the name and color. In other words, we know how much storage and network are needed to collect and transmit these metrics, regardless of the traffic pattern. -In real world applications, the cardinality can be very high. Imagine if we have -a long running service and we collect metrics with 7 attributes and each +In real world applications, the cardinality can be extremely high. Imagine if we +have a long running service and we collect metrics with 7 attributes and each attribute can have 30 different values. We might eventually end up having to remember the complete set of all 21,870,000,000 combinations! This cardinality explosion is a well-known challenge in the metrics space. For example, it can -cause surprisingly high cost in the observability system, or even be leveraged +cause surprisingly high costs in the observability system, or even be leveraged by hackers to launch a denial-of-service attack. [Cardinality diff --git a/docs/trace/README.md b/docs/trace/README.md index 4b678482102..c472800b3ba 100644 --- a/docs/trace/README.md +++ b/docs/trace/README.md @@ -17,8 +17,8 @@ ## Best Practices -The following tutorials have demonstrated the best practices for while using -traces with OpenTelemetry .NET: +The following tutorials have demonstrated the best practices for using traces +with OpenTelemetry .NET: * [Getting Started - ASP.NET Core Application](./getting-started-aspnetcore/README.md) @@ -32,8 +32,8 @@ APIs from the latest stable version of [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) package, regardless of the .NET runtime version being used: -* If you're using the latest stable version of [OpenTelemetry .NET - SDK](../../src/OpenTelemetry/README.md), you don't have to worry about the +* If you are using the latest stable version of [OpenTelemetry .NET + SDK](../../src/OpenTelemetry/README.md), you do not have to worry about the version of `System.Diagnostics.DiagnosticSource` package because it is already taken care of for you via [package dependency](../../Directory.Packages.props). @@ -150,10 +150,9 @@ information, as opposed to creating a new one. ### Modelling static tags as Resource Tags such as `MachineName`, `Environment` etc. which are static throughout the -process lifetime should be be modelled as `Resource`, instead of adding them -to each `Activity`. Refer to this -[doc](./customizing-the-sdk/README.md#resource) for details and -examples. +process lifetime should be modelled as `Resource`, instead of adding them to +each `Activity`. Refer to this [doc](./customizing-the-sdk/README.md#resource) +for details and examples. ## Common issues that lead to missing traces @@ -166,7 +165,7 @@ examples. and is disposed of at application shutdown. For an ASP.NET Core application, use `AddOpenTelemetry` and `WithTraces` methods from the `OpenTelemetry.Extensions.Hosting` package to correctly setup - `TracerProvider`. Here's a [sample ASP.NET Core + `TracerProvider`. Here is a [sample ASP.NET Core app](../../examples/AspNetCore/Program.cs) for reference. For simpler applications such as Console apps, refer to this [example](../../docs/trace/getting-started-console/Program.cs). From 1c78cd75b4596b577580d7ae02aca66aa5361744 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 9 Feb 2024 11:48:33 -0800 Subject: [PATCH 2/2] Update docs/logs/README.md Co-authored-by: Mikel Blanchard --- docs/logs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/logs/README.md b/docs/logs/README.md index fd57847ef4e..8172dd33569 100644 --- a/docs/logs/README.md +++ b/docs/logs/README.md @@ -32,7 +32,7 @@ OpenTelemetry .NET: :heavy_check_mark: You should use structured logging. * Structured logging is more efficient than unstructured logging. - * Filtering and redaction can happen on indvidual key-value pairs instead of + * Filtering and redaction can happen on individual key-value pairs instead of the entire log message. * Storage and indexing are more efficient. * Structured logging makes it easier to manage and consume logs.