[docs] Update "note" styling (#4130)
* Clean up. * Update notes to use github styling. * Clean up. * MD028 lint hack.
This commit is contained in:
Mikel Blanchard
GitHub
parent
6e7505af19
commit
074c0196f1
|
|
@ -59,8 +59,9 @@ of Windows.
|
|||
* Visual Studio 2022+ or Visual Studio Code
|
||||
* .NET Framework 4.6.2+
|
||||
|
||||
**Note:** : Visual Studio 2022 preview is **recommended** due to projects
|
||||
targeting `.net7.0` which is in preview currently.
|
||||
> **Note**
|
||||
> Visual Studio 2022 preview is **recommended** due to projects needing
|
||||
to target .NET preview versions.
|
||||
|
||||
### Public API
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,8 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder()
|
|||
|
||||
See [Program.cs](./Program.cs) for complete example.
|
||||
|
||||
**Note:** A common mistake while configuring `MeterProvider` is forgetting to
|
||||
> **Note**
|
||||
> A common mistake while configuring `MeterProvider` is forgetting to
|
||||
add the required `Meter`s to the provider. It is recommended to leverage the
|
||||
wildcard subscription model where it makes sense. For example, if your
|
||||
application is expecting to enable instruments from a number of libraries from a
|
||||
|
|
@ -276,7 +277,8 @@ 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,7 +331,8 @@ 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
|
||||
> **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.
|
||||
|
||||
|
|
@ -395,7 +398,8 @@ 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -38,7 +38,8 @@ appBuilder.Services.AddOpenTelemetry()
|
|||
.StartWithHost();
|
||||
```
|
||||
|
||||
**Note:** The
|
||||
> **Note**
|
||||
> The
|
||||
[StartWithHost](../../../src/OpenTelemetry.Extensions.Hosting/README.md#extension-method-reference)
|
||||
extension automatically starts and stops the `TracerProvider` with the host.
|
||||
|
||||
|
|
@ -51,7 +52,8 @@ required.
|
|||
Call `Sdk.CreateTracerProviderBuilder()` to obtain a builder and then call
|
||||
`Build()` once configuration is done to retrieve the `TracerProvider` instance.
|
||||
|
||||
**Note:** Once built changes to `TracerProvider` configuration are not allowed,
|
||||
> **Note**
|
||||
> Once built changes to `TracerProvider` configuration are not allowed,
|
||||
with the exception of adding more processors.
|
||||
|
||||
In most cases a single `TracerProvider` is created at the application startup,
|
||||
|
|
@ -127,7 +129,8 @@ 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
|
||||
|
|
@ -171,7 +174,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
|
||||
> **Note**
|
||||
> The SDK only ever invokes processors and has no direct knowledge of
|
||||
any registered exporters.
|
||||
|
||||
#### Processor Configuration
|
||||
|
|
@ -193,12 +197,14 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
|
|||
tracerProvider.AddProcessor(new MyProcessor3());
|
||||
```
|
||||
|
||||
**Note:** The order of processor registration is important. Each processor added
|
||||
> **Note**
|
||||
> The order of processor registration is important. Each processor added
|
||||
is invoked in order by the SDK. For example if a simple exporting processor is
|
||||
added before an enrichment processor the exported data will not contain anything
|
||||
added by the enrichment because it happens after the export.
|
||||
|
||||
**Note:** A `TracerProvider` assumes ownership of **all** processors added to
|
||||
<!-- This comment is to make sure the two notes above and below are not merged -->
|
||||
> **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
|
||||
|
|
@ -233,14 +239,15 @@ 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
|
||||
support tracing and logging by implementing `Activity` and `LogRecord`
|
||||
respectively.
|
||||
<!-- This comment is to make sure the two notes above and below are not merged -->
|
||||
> **Note**
|
||||
> The processors shipped from this SDK are generic implementations and support
|
||||
tracing and logging by implementing `Activity` and `LogRecord` respectively.
|
||||
|
||||
Follow [this](../extending-the-sdk/README.md#processor) document to learn about
|
||||
writing custom processors.
|
||||
|
|
@ -368,7 +375,8 @@ 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
|
||||
|
|
@ -412,13 +420,15 @@ 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
|
||||
> **Note**
|
||||
> If you are authoring an [ASP.NET Core
|
||||
application](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host)
|
||||
or using the [.NET Generic
|
||||
Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) the
|
||||
|
|
@ -447,7 +457,8 @@ which 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 `WithTracing` will configure the same
|
||||
> **Note**
|
||||
> Multiple calls to `WithTracing` will configure the same
|
||||
`TracerProvider`. Only a single `TraceProvider` may exist in an
|
||||
`IServiceCollection` \ `IServiceProvider`.
|
||||
|
||||
|
|
@ -469,9 +480,11 @@ it is shutdown.
|
|||
factory function to create the processor instance.
|
||||
|
||||
* `ConfigureServices`: Registers a callback function for configuring the
|
||||
`IServiceCollection` used by the `TracerProviderBuilder`. **Note:**
|
||||
`ConfigureServices` may only be called before the `IServiceProvider` has been
|
||||
created after which point services can no longer be added.
|
||||
`IServiceCollection` used by the `TracerProviderBuilder`.
|
||||
|
||||
> **Note**
|
||||
> `ConfigureServices` may only be called before the `IServiceProvider`
|
||||
has been created after which point services can no longer be added.
|
||||
|
||||
* `SetSampler<T>`: Register type `T` (must derive from `Sampler`) as the sampler
|
||||
for the `TracerProvider`.
|
||||
|
|
@ -480,7 +493,8 @@ it is shutdown.
|
|||
implementationFactory)`: Adds a sampler into the `TracerProvider` using a
|
||||
factory function to create the sampler instance.
|
||||
|
||||
**Note:** The factory functions accepting `IServiceProvider` may always be used
|
||||
> **Note**
|
||||
> The factory functions accepting `IServiceProvider` may always be used
|
||||
regardless of how the SDK is initialized. When using an external service
|
||||
collection (ex: `appBuilder.Services.AddOpenTelemetry()`), as is common in
|
||||
ASP.NET Core hosts, the `IServiceProvider` will be the instance shared and
|
||||
|
|
@ -490,7 +504,8 @@ build an `IServiceProvider` from it to make available to extensions.
|
|||
|
||||
## 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
|
||||
|
|
@ -554,7 +569,8 @@ 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.
|
||||
|
||||
|
|
@ -588,7 +604,8 @@ 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
|
||||
|
|
|
|||
|
|
@ -124,7 +124,8 @@ 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,8 +205,11 @@ 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
|
||||
considered a breaking change.
|
||||
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 +358,8 @@ 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
|
||||
|
|
@ -362,7 +367,8 @@ register custom OpenTelemetry components into their `TracerProvider`s. These
|
|||
extension methods can target either the `TracerProviderBuilder` or the
|
||||
`IServiceCollection` classes. Both of these patterns are described below.
|
||||
|
||||
**Note:** Libraries providing SDK plugins such as exporters, resource detectors,
|
||||
> **Note**
|
||||
> Libraries providing SDK plugins such as exporters, resource detectors,
|
||||
and/or samplers should take a dependency on the [OpenTelemetry SDK
|
||||
package](https://www.nuget.org/packages/opentelemetry). Library authors
|
||||
providing instrumentation should take a dependency on `OpenTelemetry.Api` or
|
||||
|
|
@ -397,7 +403,8 @@ 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
|
||||
|
|
@ -625,7 +632,8 @@ single `AddMyLibrary` extension to configure the library itself and optionally
|
|||
turn on OpenTelemetry integration for multiple signals (tracing & metrics in
|
||||
this case).
|
||||
|
||||
**Note:** `ConfigureOpenTelemetryTracerProvider` and
|
||||
> **Note**
|
||||
> `ConfigureOpenTelemetryTracerProvider` and
|
||||
`ConfigureOpenTelemetryMeterProvider` do not automatically start OpenTelemetry.
|
||||
The host is responsible for either calling `StartWithHost` in the
|
||||
[OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md)
|
||||
|
|
|
|||
|
|
@ -142,7 +142,8 @@ It might be useful to automatically capture the unhandled exceptions, travel
|
|||
through the unfinished activities and export them for troubleshooting. Here goes
|
||||
one possible way of doing this:
|
||||
|
||||
**WARNING:** Use `AppDomain.UnhandledException` with caution. A throw in the
|
||||
> **Warning**
|
||||
> Use `AppDomain.UnhandledException` with caution. A throw in the
|
||||
handler puts the process into an unrecoverable state.
|
||||
|
||||
```csharp
|
||||
|
|
|
|||
|
|
@ -488,7 +488,8 @@ Windows-based .NET implementation).
|
|||
|
||||
The above requires import of the `System.Diagnostics.Metrics` namespace.
|
||||
|
||||
**Note:** It is important to note that `Meter` instances are created by
|
||||
> **Note**
|
||||
> It is important to note that `Meter` instances are created by
|
||||
using its constructor, and *not* by calling a `GetMeter` method on the
|
||||
`MeterProvider`. This is an important distinction from the [OpenTelemetry
|
||||
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter),
|
||||
|
|
|
|||
|
|
@ -6,7 +6,8 @@
|
|||
The console exporter prints data to the Console window.
|
||||
ConsoleExporter supports exporting logs, metrics and traces.
|
||||
|
||||
**Note:** this exporter is intended to be used during learning how telemetry
|
||||
> **Note**
|
||||
> This exporter is intended to be used during learning how telemetry
|
||||
data are created and exported. It is not recommended for any production
|
||||
environment.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,11 +32,13 @@ Targeting `OpenTelemetry.OpenTelemetryBuilder`:
|
|||
|
||||
### Obsolete OpenTelemetry SDK pre-1.4.0 extensions
|
||||
|
||||
**Note:** The below extension methods should be called by application host code
|
||||
> **Note**
|
||||
> The below extension methods should be called by application host code
|
||||
only. Library authors see: [Registration extension method guidance for library
|
||||
authors](../../docs/trace/extending-the-sdk/README.md#registration-extension-method-guidance-for-library-authors).
|
||||
|
||||
**Note:** Multiple calls to the below extensions will **NOT** result in multiple
|
||||
<!-- This comment is to make sure the two notes above and below are not merged -->
|
||||
> **Note**
|
||||
> Multiple calls to the below extensions will **NOT** result in multiple
|
||||
providers. To establish multiple providers use the
|
||||
`Sdk.CreateTracerProviderBuilder()` and/or `Sdk.CreateMeterProviderBuilder()`
|
||||
methods. See [TracerProvider
|
||||
|
|
|
|||
|
|
@ -11,7 +11,8 @@ and
|
|||
[System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient)
|
||||
and collects traces about database operations.
|
||||
|
||||
**Note: This component is based on the OpenTelemetry semantic conventions for
|
||||
> **Note**
|
||||
> This component is based on the OpenTelemetry semantic conventions for
|
||||
[traces](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions).
|
||||
These conventions are
|
||||
[Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md),
|
||||
|
|
@ -19,7 +20,7 @@ and hence, this package is a [pre-release](../../VERSIONING.md#pre-releases).
|
|||
Until a [stable
|
||||
version](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md)
|
||||
is released, there can be breaking changes. You can track the progress from
|
||||
[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).**
|
||||
[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).
|
||||
|
||||
## Steps to enable OpenTelemetry.Instrumentation.SqlClient
|
||||
|
||||
|
|
@ -142,14 +143,16 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder()
|
|||
.Build();
|
||||
```
|
||||
|
||||
**Note:** When using the built-in `System.Data.SqlClient` only stored procedure
|
||||
> **Note**
|
||||
> When using the built-in `System.Data.SqlClient` only stored procedure
|
||||
command names will ever be captured. When using the `Microsoft.Data.SqlClient`
|
||||
NuGet package (v1.1+) stored procedure command names, full query text, and other
|
||||
command text will be captured.
|
||||
|
||||
### EnableConnectionLevelAttributes
|
||||
|
||||
**Note:** EnableConnectionLevelAttributes is supported on all runtimes.
|
||||
> **Note**
|
||||
> EnableConnectionLevelAttributes is supported on all runtimes.
|
||||
|
||||
By default, `EnabledConnectionLevelAttributes` is disabled and this
|
||||
instrumentation sets the `peer.service` attribute to the
|
||||
|
|
@ -172,7 +175,8 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder()
|
|||
|
||||
### Enrich
|
||||
|
||||
**Note:** Enrich is supported on .NET and .NET Core runtimes only.
|
||||
> **Note**
|
||||
> Enrich is supported on .NET and .NET Core runtimes only.
|
||||
|
||||
This option can be used to enrich the activity with additional information from
|
||||
the raw `SqlCommand` object. The `Enrich` action is called only when
|
||||
|
|
@ -208,7 +212,8 @@ access to `SqlCommand` object.
|
|||
|
||||
### RecordException
|
||||
|
||||
**Note:** RecordException is supported on .NET and .NET Core runtimes only.
|
||||
> **Note**
|
||||
> RecordException is supported on .NET and .NET Core runtimes only.
|
||||
|
||||
This option can be set to instruct the instrumentation to record SqlExceptions
|
||||
as Activity
|
||||
|
|
@ -226,7 +231,8 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder()
|
|||
|
||||
### Filter
|
||||
|
||||
**Note:** Filter is supported on .NET and .NET Core runtimes only.
|
||||
> **Note**
|
||||
> Filter is supported on .NET and .NET Core runtimes only.
|
||||
|
||||
This option can be used to filter out activities based on the properties of the
|
||||
`SqlCommand` object being instrumented using a `Func<object, bool>`. The
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ 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).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue