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

[docs] Updates for DI tweaks (#4127)

This commit is contained in:
Mikel Blanchard 2023-01-31 13:37:16 -08:00 committed by GitHub
parent 3a491b14b2
commit 0b69b37136
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 62 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -193,6 +193,11 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
tracerProvider.AddProcessor(new MyProcessor3());
```
**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
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
@ -202,7 +207,7 @@ 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.
Processors can be used for enriching. exporting, and/or filtering telemetry.
Processors can be used for enriching, exporting, and/or filtering telemetry.
To enrich telemetry, users may write custom processors overriding the `OnStart`
and/or `OnEnd` methods (as needed) to implement custom logic to change the data
@ -329,9 +334,9 @@ reducing the number of samples of traces collected and sent to the processors.
If no sampler is explicitly configured, the default is to use
`ParentBased(root=AlwaysOn)`. `SetSampler` method on `TracerProviderBuilder` can
be used to set sampler. Only one sampler can be associated with a provider. If
multiple `SetSampler` is called, the last one wins. Also, it is not possible to
change the sampler *after* the provider is built, by calling the `Build()`
method on the `TracerProviderBuilder`.
`SetSampler` is called multiple times, the last one wins. Also, it is not
possible to change the sampler *after* the provider is built, by calling the
`Build()` method on the `TracerProviderBuilder`.
The snippet below shows configuring a custom sampler to the provider.
@ -446,45 +451,34 @@ it is shutdown.
`TracerProvider`. Only a single `TraceProvider` may exist in an
`IServiceCollection` \ `IServiceProvider`.
### Dependency injection `TracerProviderBuilder` extension method reference
### Dependency injection TracerProviderBuilder extension method reference
* `AddInstrumentation<T>`: Adds instrumentation of type `T` into the
`TracerProvider`.
* `AddInstrumentation<T>(Func<IServiceProvider, T> instrumentationFactory)`:
Adds instrumentation of type `T` into the
`TracerProvider` using a factory function to create the instrumentation
instance.
* `AddProcessor<T>`: Adds a processor of type `T` (must derive from
`BaseProcessor<Activity>`) into the `TracerProvider`.
* `SetSampler<T>`: Register type `T` (must derive from `Sampler`) as the sampler
for the `TracerProvider`.
* `AddProcessor(Func<IServiceProvider, BaseProcessor<Activity>>
implementationFactory)`: Adds a processor into the `TracerProvider` using a
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 service can no longer be added.
created after which point services can no longer be added.
* `ConfigureBuilder`: Registers a callback function for configuring the
`TracerProviderBuilder` once the `IServiceProvider` is available.
* `SetSampler<T>`: Register type `T` (must derive from `Sampler`) as the sampler
for the `TracerProvider`.
```csharp
var appBuilder = WebApplication.CreateBuilder(args);
appBuilder.Services.AddOpenTelemetry()
.WithTracing(builder => builder
.ConfigureBuilder((sp, builder) =>
{
builder.AddProcessor(
new MyCustomProcessor(
// Note: This example uses the final IServiceProvider once it is available.
sp.GetRequiredService<MyCustomService>(),
sp.GetRequiredService<IOptions<MyOptions>>().Value));
}))
.StartWithHost();
```
**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.
* `SetSampler(Func<IServiceProvider, Sampler>
implementationFactory)`: Adds a sampler into the `TracerProvider` using a
factory function to create the sampler instance.
## Configuration files and environment variables

61
docs/trace/extending-the-sdk/README.md
View File

@ -362,6 +362,15 @@ 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,
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
`OpenTelemetry.Api.ProviderBuilderExtensions` package.
`OpenTelemetry.Api.ProviderBuilderExtensions` exposes interfaces for accessing
the `IServiceCollection` which is a requirement for supporting the [.NET Options
pattern](https://learn.microsoft.com/dotnet/core/extensions/options).
When providing registration extensions:
* **DO** support the [.NET Options
@ -449,7 +458,7 @@ namespace OpenTelemetry.Trace
services.TryAddSingleton<MyCustomService>();
});
builder.ConfigureBuilder((sp, builder) =>
builder.AddProcessor(serviceProvider =>
{
// Retrieve MyExporterOptions instance using name.
var exporterOptions = serviceProvider.GetRequiredService<IOptionsMonitor<MyExporterOptions>>().Get(name);
@ -458,16 +467,15 @@ namespace OpenTelemetry.Trace
var batchOptions = serviceProvider.GetRequiredService<IOptionsMonitor<BatchExportActivityProcessorOptions>>().Get(name);
// Retrieve MyCustomService singleton.
var myCustomService = sp.GetRequiredService<MyCustomService>();
var myCustomService = serviceProvider.GetRequiredService<MyCustomService>();
// Registers MyCustomExporter with a batch processor.
builder.AddProcessor(
new BatchActivityExportProcessor(
new MyCustomExporter(exporterOptions, myCustomService),
batchOptions.MaxQueueSize,
batchOptions.ScheduledDelayMilliseconds,
batchOptions.ExporterTimeoutMilliseconds,
batchOptions.MaxExportBatchSize));
// Return a batch export processor using MyCustomExporter.
return new BatchActivityExportProcessor(
new MyCustomExporter(exporterOptions, myCustomService),
batchOptions.MaxQueueSize,
batchOptions.ScheduledDelayMilliseconds,
batchOptions.ExporterTimeoutMilliseconds,
batchOptions.MaxExportBatchSize);
});
// Return builder for call chaining.
@ -519,8 +527,10 @@ When providing `TracerProviderBuilder` registration extensions:
* **DO** Use the `TracerProviderBuilder.ConfigureServices` extension method to
register dependent services.
* **DO** Use the `TracerProviderBuilder.ConfigureBuilder` extension method to
peform configuration once the final `IServiceProvider` is available.
* **DO** Use [the dependency injection extension
methods](../customizing-the-sdk/README.md#dependency-injection-tracerproviderbuilder-extension-method-reference)
utilizing factory patterns to perform configuration once the final
`IServiceProvider` is available.
### IServiceCollection extension methods
@ -530,7 +540,8 @@ the target type for registration extension methods.
The following example shows how a library might enable tracing and metric
support using an `IServiceCollection` extension by calling
`ConfigureOpenTelemetryTracerProvider`.
`ConfigureOpenTelemetryTracerProvider` and
`ConfigureOpenTelemetryMeterProvider`.
```csharp
using Microsoft.Extensions.DependencyInjection.Extensions;
@ -554,7 +565,7 @@ namespace Microsoft.Extensions.DependencyInjection
services.TryAddSingleton<IMyLibraryService, MyLibraryService>();
// Support named options.
name ??= Options.DefaultName;
name ??= Options.Options.DefaultName;
if (configure != null)
{
@ -570,7 +581,7 @@ namespace Microsoft.Extensions.DependencyInjection
{
builder.AddSource("MyLibrary");
}
}));
});
// Configure OpenTelemetry metrics.
services.ConfigureOpenTelemetryMeterProvider((sp, builder) =>
@ -580,7 +591,7 @@ namespace Microsoft.Extensions.DependencyInjection
{
builder.AddMeter("MyLibrary");
}
}));
});
return services;
}
@ -614,12 +625,14 @@ single `AddMyLibrary` extension to configure the library itself and optionally
turn on OpenTelemetry integration for multiple signals (tracing & metrics in
this case).
**Note:** `ConfigureOpenTelemetryTracerProvider` does not automatically start
OpenTelemetry. The host is responsible for either calling `StartWithHost` in the
**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)
package, calling `Build` when using the `Sdk.CreateTracerProviderBuilder`
method, or by accessing the `TracerProvider` from the `IServiceCollection` where
`ConfigureOpenTelemetryTracerProvider` was performed.
package, calling `Build` when using the `Sdk.CreateTracerProviderBuilder` and
`Sdk.CreateMeterProviderBuilder` methods, or by accessing the `TracerProvider`
and `MeterProvider` from the `IServiceCollection` where configuration was
performed.
When providing `IServiceCollection` registration extensions:
@ -631,8 +644,10 @@ When providing `IServiceCollection` registration extensions:
* **DO** Use the `IServiceCollection` directly to register dependent services.
* **DO** Use the `TracerProviderBuilder.ConfigureBuilder` extension method to
peform configuration once the final `IServiceProvider` is available.
* **DO** Use [the dependency injection extension
methods](../customizing-the-sdk/README.md#dependency-injection-tracerproviderbuilder-extension-method-reference)
utilizing factory patterns to perform configuration once the final
`IServiceProvider` is available.
## References