open-telemetry
/
opentelemetry-dotnet
mirror of https://github.com/open-telemetry/opentelemetry-dotnet.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[Hosting] README updates (#3913) 

* OpenTelemetry.Extensions.Hosting README updates.

* Review.

Co-authored-by: Cijo Thomas <cijo.thomas@gmail.com>
This commit is contained in:
Mikel Blanchard 2022-11-16 21:23:25 -08:00 committed by GitHub
parent 425a59effe
commit 656bd7c8b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 63 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/trace/customizing-the-sdk/README.md
View File

@ -38,9 +38,10 @@ tracerProvider.Dispose()
```
**Note:** The `Sdk.CreateTracerProviderBuilder()` API is available for all
runtimes. Additionally, for `ASP.NET Core` and [.NET Generic
Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) users,
helper extensions are provided in the
runtimes. Additionally, for [ASP.NET
Core](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host) and
[.NET Generic](https://learn.microsoft.com/dotnet/core/extensions/generic-host)
host users, helper extensions are provided in the
[OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md)
package to simplify configuration and management of the `TracerProvider`.
@ -411,9 +412,10 @@ for details.
#### Using the OpenTelemetry.Extensions.Hosting package
**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
**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
[OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md)
package is the recommended mechanism.
@ -500,9 +502,10 @@ and OpenTelemetry API being used.
#### Using .NET hosts with the OpenTelemetry.Extensions.Hosting package
`ASP.NET Core` and [.NET Generic
Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) users
using the
[ASP.NET
Core](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host) and
[.NET Generic](https://learn.microsoft.com/dotnet/core/extensions/generic-host)
host users using the
[OpenTelemetry.Extensions.Hosting](../../../src/OpenTelemetry.Extensions.Hosting/README.md)
package do not need to do anything extra to enable `IConfiguration` support. The
OpenTelemetry SDK will automatically use whatever `IConfiguration` has been

128
src/OpenTelemetry.Extensions.Hosting/README.md
View File

@ -9,92 +9,66 @@
dotnet add package --prerelease OpenTelemetry.Extensions.Hosting
```
## Overview
The OpenTelemetry.Extensions.Hosting package provides extension methods for
automatically starting (and stopping) OpenTelemetry tracing (`TracerProvider`)
and metrics (`MeterProvider`) in [ASP.NET
Core](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host) and
[.NET Generic](https://learn.microsoft.com/dotnet/core/extensions/generic-host)
hosts. These are completely optional extensions meant to simplify the
management of the OpenTelemetry SDK lifecycle.
## Extension method reference
**Note:** The below extension methods target
`Microsoft.Extensions.DependencyInjection.IServiceCollection`.
**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
providers. To establish multiple providers use the
`Sdk.CreateTracerProviderBuilder()` and/or `Sdk.CreateMeterProviderBuilder()`
methods. See [TracerProvider
configuration](../../docs/trace/customizing-the-sdk/README.md#tracerprovider-configuration)
and [Building a
MeterProvider](../../docs/metrics/customizing-the-sdk/README.md#building-a-meterprovider)
for more details.
* `AddOpenTelemetryTracing`: Configure OpenTelemetry and register an
[IHostedService](https://learn.microsoft.com/dotnet/api/microsoft.extensions.hosting.ihostedservice)
to automatically start tracing services in the supplied
[IServiceCollection](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection).
* `AddOpenTelemetryMetrics`: Configure OpenTelemetry and register an
[IHostedService](https://learn.microsoft.com/dotnet/api/microsoft.extensions.hosting.ihostedservice)
to automatically start metric services in the supplied
[IServiceCollection](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection).
## Usage
### Tracing
#### Simple Configuration
The following example registers tracing using the `ZipkinExporter` and binds
options to the "Zipkin" configuration section:
The following example shows how to register OpenTelemetry tracing & metrics in
an ASP.NET Core host using the OpenTelemetry.Extensions.Hosting extensions.
```csharp
services.AddOpenTelemetryTracing((builder) => builder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddZipkinExporter());
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
services.Configure<ZipkinExporterOptions>(this.Configuration.GetSection("Zipkin"));
```
var appBuilder = WebApplication.CreateBuilder(args);
#### Using Dependency Injection
appBuilder.Services.AddOpenTelemetryTracing(
builder => builder.AddConsoleExporter());
The following example registers a processor of the type "MyProcessor" which has
been registered as a singleton with the `IServiceCollection`:
appBuilder.Services.AddOpenTelemetryMetrics(
builder => builder.AddConsoleExporter());
```csharp
services.AddSingleton<MyProcessor>();
var app = appBuilder.Build();
services.AddOpenTelemetryTracing((builder) => builder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddProcessor<MyProcessor>());
```
Similar methods exist for registering instrumentation (`AddInstrumentation<T>`)
and setting a sampler (`SetSampler<T>`).
You can also access the application `IServiceProvider` directly and accomplish
the same registration using the `ConfigureBuilder` extension like this:
```csharp
services.AddSingleton<MyProcessor>();
services.AddOpenTelemetryTracing(hostingBuilder => hostingBuilder
.ConfigureBuilder((sp, builder) => builder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddProcessor(sp.GetRequiredService<MyProcessor>())));
```
**Note:** `ConfigureBuilder` is called _after_ the `IServiceProvider` has been built
from the application `IServiceCollection` so any services registered in the
`ConfigureBuilder` callback will be ignored.
#### Building Extension Methods
Library authors may want to configure the OpenTelemetry `TracerProvider` and
register application services to provide more complex features. This can be
accomplished concisely by using the `TracerProviderBuilder.ConfigureServices`
extension method inside of a more general `TracerProviderBuilder` configuration
extension like this:
```csharp
public static class MyLibraryExtensions
{
public static TracerProviderBuilder AddMyFeature(this TracerProviderBuilder tracerProviderBuilder)
{
return tracerProviderBuilder
.ConfigureServices(services =>
services
.AddHostedService<MyHostedService>()
.AddSingleton<MyService>()
.AddSingleton<MyProcessor>()
.AddSingleton<MySampler>())
.AddProcessor<MyProcessor>()
.SetSampler<MySampler>();
}
}
```
Such an extension method can be consumed like this:
```csharp
services.AddOpenTelemetryTracing((builder) => builder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddMyFeature()
.AddZipkinExporter());
app.Run();
```
## References