|
| 1 | +# Customizing OpenTelemetry .NET SDK |
| 2 | + |
| 3 | +**This doc is work-in-progress.** |
| 4 | + |
| 5 | +## TracerProvider |
| 6 | + |
| 7 | +As shown in the [getting-started](../getting-started/README.md) doc, a valid |
| 8 | +[`TracerProvider`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#tracer-provider) |
| 9 | +must be configured and built to collect traces with OpenTelemetry .NET Sdk. |
| 10 | +`TracerProvider` holds all the configuration for tracing like samplers, |
| 11 | +processors, etc. Naturally, almost all the customizations must be done on the |
| 12 | +`TracerProvider`. |
| 13 | + |
| 14 | +## Building a TracerProvider |
| 15 | + |
| 16 | +Building a `TracerProvider` is done using `TracerProviderBuilder` which must be |
| 17 | +obtained by calling `Sdk.CreateTracerProviderBuilder()`. `TracerProviderBuilder` |
| 18 | +exposes various methods which configures the provider it is going to build. These |
| 19 | +includes methods like `SetSampler`, `AddProcessor` etc, and are explained in |
| 20 | +subsequent sections of this document. Once configuration is done, calling |
| 21 | +`Build()` on the `TracerProviderBuilder` builds the `TracerProvider` instance. |
| 22 | +Once built, changes to its configuration is not allowed, with the exception of |
| 23 | +adding more processors. In most cases, a single `TracerProvider` is created at |
| 24 | +the application startup, and is disposed when application shuts down. |
| 25 | + |
| 26 | +The snippet below shows how to build a basic `TracerProvider`. This will create |
| 27 | +a provider with default configuration, and is not particularly useful. The |
| 28 | +subsequent sections shows how to build a more useful provider. |
| 29 | + |
| 30 | +```csharp |
| 31 | +using OpenTelemetry; |
| 32 | +using OpenTelemetry.Trace; |
| 33 | + |
| 34 | +using var tracerProvider = Sdk.CreateTracerProviderBuilder().Build(); |
| 35 | +``` |
| 36 | + |
| 37 | +## TracerProvider configuration |
| 38 | + |
| 39 | +`TracerProvider` holds the tracing configuration, which includes the following: |
| 40 | + |
| 41 | +1. The list of `ActivitySource`s (aka Tracers) from which traces are collected. |
| 42 | +2. The list of instrumentations enabled via |
| 43 | + [InstrumentationLibrary](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library). |
| 44 | +3. The list of |
| 45 | + [Processors](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor), |
| 46 | + including exporting processors which exports traces to |
| 47 | + [Exporters](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter) |
| 48 | +4. The |
| 49 | + [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) |
| 50 | + associated with the traces. |
| 51 | +5. The |
| 52 | + [Sampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampler) |
| 53 | + to be used. |
| 54 | + |
| 55 | +### Activity Source |
| 56 | + |
| 57 | +`ActivitySource` denotes a |
| 58 | +[`Tracer`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer), |
| 59 | +which is used to start activities. The SDK follows an explicit opt-in model for |
| 60 | +listening to activity sources. i.e, by default, it listens to no sources. Every |
| 61 | +activity source which produce telemetry must be explicitly added to the tracer |
| 62 | +provider to start collecting traces from them. |
| 63 | + |
| 64 | +`AddSource` method on `TracerProviderBuilder` can be used to add a |
| 65 | +`ActivitySource` to the provider. The name of the `ActivitySource` |
| 66 | +(case-insensitive) must be the argument to this method. Multiple `AddSource` can |
| 67 | +be called to add more than one source. It also supports wild-card subscription |
| 68 | +model as well. |
| 69 | + |
| 70 | +It is not possible to add sources *after* the provider is built, by calling the |
| 71 | +`Build()` method on the `TracerProviderBuilder`. |
| 72 | + |
| 73 | +The snippet below shows how to add activity sources to the provider. |
| 74 | + |
| 75 | +```csharp |
| 76 | +using OpenTelemetry; |
| 77 | +using OpenTelemetry.Trace; |
| 78 | + |
| 79 | +using var tracerProvider = Sdk.CreateTracerProviderBuilder() |
| 80 | + // The following subscribes to activities from Activity Source |
| 81 | + // named "MyCompany.MyProduct.MyLibrary" only. |
| 82 | + .AddSource("MyCompany.MyProduct.MyLibrary") |
| 83 | + // The following subscribes to activities from all Activity Sources |
| 84 | + // whose name starts with "AbcCompany.XyzProduct.". |
| 85 | + .AddSource("AbcCompany.XyzProduct.*") |
| 86 | + .Build(); |
| 87 | +``` |
| 88 | + |
| 89 | +See [Program.cs](./Program.cs) for complete example. |
| 90 | + |
| 91 | +**Note** |
| 92 | +A common mistake while configuring `TracerProvider` is forgetting to add |
| 93 | +all `ActivitySources` to the provider. It is recommended to leverage the |
| 94 | +wild card subscription model where it makes sense. For example, if your |
| 95 | +application is expecting to enable tracing from a number of libraries |
| 96 | +from a company "Abc", the you can use `AddSource("Abc.*")` to enable |
| 97 | +all sources whose name starts with "Abc.". |
| 98 | + |
| 99 | +### Instrumentation |
| 100 | + |
| 101 | +// TODO |
| 102 | + |
| 103 | +### Processor |
| 104 | + |
| 105 | +// TODO |
| 106 | + |
| 107 | +### Resource |
| 108 | + |
| 109 | +// TODO |
| 110 | + |
| 111 | +### Sampler |
| 112 | + |
| 113 | +// TODO |
| 114 | + |
| 115 | +## Context Propagation |
| 116 | + |
| 117 | +// TODO: OpenTelemetry Sdk contents about Context. |
| 118 | +// TODO: Links to built-in instrumentations doing Propagation. |
0 commit comments