diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9aa487e4afa..6f713ae1146 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,7 +59,7 @@ of Windows. * Visual Studio 2022+ or Visual Studio Code * .NET Framework 4.6.2+ -**NOTE** : Visual Studio 2022 preview is **recommended** due to projects +**Note:** : Visual Studio 2022 preview is **recommended** due to projects targeting `.net7.0` which is in preview currently. ### Public API diff --git a/docs/metrics/customizing-the-sdk/README.md b/docs/metrics/customizing-the-sdk/README.md index 84363673a33..d700d6da54f 100644 --- a/docs/metrics/customizing-the-sdk/README.md +++ b/docs/metrics/customizing-the-sdk/README.md @@ -276,7 +276,7 @@ default boundaries. This requires the use of }) ``` -**NOTE:** The SDK currently does not support any changes to `Aggregation` type +**Note:** The SDK currently does not support any changes to `Aggregation` type by using Views. See [Program.cs](./Program.cs) for a complete example. @@ -329,9 +329,9 @@ ignored. The SDK chooses the key/value combinations in the order in which they are emitted. `SetMaxMetricPointsPerMetricStream` can be used to override the default. -**NOTE**: One `MetricPoint` is reserved for every `MetricStream` for the special -case where there is no key/value pair associated with the metric. The maximum -number of `MetricPoint`s has to accommodate for this special case. +**Note:**: One `MetricPoint` is reserved for every `MetricStream` for the +special case where there is no key/value pair associated with the metric. The +maximum number of `MetricPoint`s has to accommodate for this special case. Consider the below example. Here we set the maximum number of `MetricPoint`s allowed to be `3`. This means that for every `MetricStream`, the SDK will export @@ -395,7 +395,7 @@ AnotherFruitCounter.Add(5, new("name", "banana"), new("color", "yellow")); // Ex AnotherFruitCounter.Add(4, new("name", "mango"), new("color", "yellow")); // Not exported ``` -**NOTE:** The above limit is *per* metric stream, and applies to all the metric +**Note:** The above limit is *per* metric stream, and applies to all the metric streams. There is no ability to apply different limits for each instrument at this moment. diff --git a/docs/trace/customizing-the-sdk/README.md b/docs/trace/customizing-the-sdk/README.md index 66dfb3c3dd4..c97b7c07636 100644 --- a/docs/trace/customizing-the-sdk/README.md +++ b/docs/trace/customizing-the-sdk/README.md @@ -109,7 +109,7 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder() See [Program.cs](./Program.cs) for complete example. -**Note** A common mistake while configuring `TracerProvider` is forgetting to +**Note:** A common mistake while configuring `TracerProvider` is forgetting to add all `ActivitySources` to the provider. It is recommended to leverage the wild card subscription model where it makes sense. For example, if your application is expecting to enable tracing from a number of libraries from a @@ -153,8 +153,8 @@ processor classes `SimpleExportProcessor` & `BatchExportProcessor` are provided to support invoking exporters through the processor pipeline and implement the standard behaviors prescribed by the OpenTelemetry specification. -**Note** The SDK only ever invokes processors and has no direct knowledge of any -registered exporters. +**Note:** The SDK only ever invokes processors and has no direct knowledge of +any registered exporters. #### Processor Configuration @@ -175,11 +175,11 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder() tracerProvider.AddProcessor(new MyProcessor3()); ``` -**Note** A `TracerProvider` assumes ownership of **all** processors added to it. -This means that the provider will call the `Shutdown` method on all registered -processors when it is shutting down and call the `Dispose` method on all -registered processors when it is disposed. If multiple providers are being set -up in an application then separate instances of processors **MUST** be +**Note:** A `TracerProvider` assumes ownership of **all** processors added to +it. This means that the provider will call the `Shutdown` method on all +registered processors when it is shutting down and call the `Dispose` method on +all registered processors when it is disposed. If multiple providers are being +set up in an application then separate instances of processors **MUST** be registered on each provider. Otherwise shutting down one provider will cause the shared processor(s) in other providers to be shut down as well which may lead to undesired results. @@ -213,12 +213,12 @@ For exporting purposes, the SDK provides the following built-in processors: : This is an exporting processor which passes telemetry to the configured exporter immediately without any batching. -**Note** A special processor +**Note:** A special processor [CompositeProcessor<T>](../../../src/OpenTelemetry/CompositeProcessor.cs) is used by the SDK to chain multiple processors together and may be used as needed by users to define sub-pipelines. -**Note** The processors shipped from this SDK are generic implementations and +**Note:** The processors shipped from this SDK are generic implementations and support tracing and logging by implementing `Activity` and `LogRecord` respectively. @@ -361,7 +361,7 @@ Sdk.SetDefaultTextMapPropagator(new MyCustomPropagator()); ## Dependency injection support -**Note** This information applies to the OpenTelemetry SDK version 1.4.0 and +**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and newer only. The SDK implementation of `TracerProviderBuilder` is backed by an @@ -405,13 +405,13 @@ When using the `Sdk.CreateTracerProviderBuilder` method the `TracerProvider` owns its own `IServiceCollection`. It will only be able to see services registered into that collection. -**Note** It is important to correctly manage the lifecycle of the +**Note:** It is important to correctly manage the lifecycle of the `TracerProvider`. See [Building a TracerProvider](#building-a-tracerprovider) for details. #### Using the OpenTelemetry.Extensions.Hosting package -**Note** If you are authoring an ASP.NET Core application or using the [.NET +**Note:** If you are authoring an ASP.NET Core application or using the [.NET Generic Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) the [OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md) @@ -436,7 +436,7 @@ is used to automatically start the `TracerProvider` when the host starts and the host will automatically shutdown and dispose the `TracerProvider` when it is shutdown. -**Note** Multiple calls to `AddOpenTelemetryTracing` will configure the same +**Note:** Multiple calls to `AddOpenTelemetryTracing` will configure the same `TracerProvider`. Only a single `TraceProvider` may exist in an `IServiceCollection` \ `IServiceProvider`. @@ -455,7 +455,7 @@ shutdown. for the `TracerProvider`. * `ConfigureServices`: Registers a callback function for configuring the - `IServiceCollection` used by the `TracerProviderBuilder`. **Note** + `IServiceCollection` used by the `TracerProviderBuilder`. **Note:** `ConfigureServices` may only be called before the `IServiceProvider` has been created after which point service can no longer be added. @@ -476,14 +476,14 @@ shutdown. })); ``` - **Note** `ConfigureBuilder` is an advanced API and is expected to be used + **Note:** `ConfigureBuilder` is an advanced API and is expected to be used primarily by library authors. Services may NOT be added to the `IServiceCollection` during `ConfigureBuilder` because the `IServiceProvider` has already been created. ## Configuration files and environment variables -**Note** This information applies to the OpenTelemetry SDK version 1.4.0 and +**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and newer only. The OpenTelemetry .NET SDK integrates with the standard @@ -546,7 +546,7 @@ variables users may also manage these settings via the command-line, configuration files, or any other source registered with the .NET configuration engine. This provides greater flexibility than what the specification defines. -**Note** Not all of the environment variables defined in the specification are +**Note:** Not all of the environment variables defined in the specification are supported. Consult the individual project README files for details on specific environment variable support. @@ -580,7 +580,7 @@ environment variables. dotnet run --OTEL_SERVICE_NAME "MyService" ``` -**Note** The [.NET +**Note:** The [.NET Configuration](https://learn.microsoft.com/dotnet/core/extensions/configuration) pattern is hierarchical meaning the order of registered configuration sources controls which value will seen by the SDK when it is defined in multiple diff --git a/docs/trace/extending-the-sdk/README.md b/docs/trace/extending-the-sdk/README.md index 7a4c68fba08..fd0358ddb15 100644 --- a/docs/trace/extending-the-sdk/README.md +++ b/docs/trace/extending-the-sdk/README.md @@ -124,7 +124,7 @@ guidelines. This section describes the steps required to write a custom instrumentation library. -**Note** If you are writing a new library or modifying an existing library the +**Note:** If you are writing a new library or modifying an existing library the recommendation is to use the [ActivitySource API/OpenTelemetry API](../../../src/OpenTelemetry.Api/README.md#introduction-to-opentelemetry-net-tracing-api) to emit activity/span instances directly. If a library is instrumented using the @@ -204,7 +204,7 @@ Writing an instrumentation library typically involves 3 steps. * If an extension is not provided, then the name of the `ActivitySource` used by the instrumented library must be documented so that end users can enable it by calling `AddSource` on the `TracerProviderBuilder` - being configured. **Note** Changing the name of the source should be + being configured. **Note:** Changing the name of the source should be considered a breaking change. ### Special case : Instrumentation for libraries producing legacy Activity @@ -354,7 +354,7 @@ A demo ResourceDetector is shown [here](./MyResourceDetector.cs). ## Registration extension method guidance for library authors -**Note** This information applies to the OpenTelemetry SDK version 1.4.0 and +**Note:** This information applies to the OpenTelemetry SDK version 1.4.0 and newer only. Library authors are encouraged to provide extension methods users may call to @@ -388,7 +388,7 @@ When providing registration extensions: from starting. The OpenTelemetry SDK is allowed to crash if it cannot be started. It **MUST NOT** crash once running. -**Note** The SDK implementation of `TracerProviderBuilder` ensures that the +**Note:** The SDK implementation of `TracerProviderBuilder` ensures that the [.NET Configuration](https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration) engine is always available by creating a root `IConfiguration` from environment @@ -611,7 +611,7 @@ single `AddMyLibrary` extension to configure the library itself and optionally turn on OpenTelemetry integration for multiple signals (tracing & metrics in this case). -**Note** `ConfigureOpenTelemetryTracing` does not automatically start +**Note:** `ConfigureOpenTelemetryTracing` does not automatically start OpenTelemetry. The host is responsible for either calling `AddOpenTelemetryTracing` in the [OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md) diff --git a/test/OpenTelemetry.Tests.Stress.Metrics/README.md b/test/OpenTelemetry.Tests.Stress.Metrics/README.md index 88a7168ed79..ec8eba4c3cc 100644 --- a/test/OpenTelemetry.Tests.Stress.Metrics/README.md +++ b/test/OpenTelemetry.Tests.Stress.Metrics/README.md @@ -5,7 +5,7 @@ This stress test is specifically for Metrics SDK, and is based on the * [Running the stress test](#running-the-stress-test) -**NOTE:** To run the stress tests for Histogram, comment out the `Run` method +**Note:** To run the stress tests for Histogram, comment out the `Run` method for `Counter` and uncomment everything related to `Histogram` in the [Program.cs](../OpenTelemetry.Tests.Stress.Metrics/Program.cs).