diff --git a/docs/trace/customizing-the-sdk/README.md b/docs/trace/customizing-the-sdk/README.md index 1bac8017d9b..951e0dabffa 100644 --- a/docs/trace/customizing-the-sdk/README.md +++ b/docs/trace/customizing-the-sdk/README.md @@ -108,11 +108,94 @@ name starts with "Abc.". ### Instrumentation -// TODO +While the OpenTelemetry API can be used to instrument any library manually, +[Instrumentation +Libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#instrumentation-libraries) +are available for a lot of commonly used libraries. Such instrumentations can be +added to the `TracerProvider`. It is not required to attach the instrumentation +to the provider, unless the life cycle of the instrumentation must be managed by +the provider. If the instrumentation must be activated/shutdown/disposed along +with the provider, then the instrumentation must be added to the provider. + +Typically, the instrumentation libraries provide extension methods on +`TracerProviderBuilder` to allow adding them to the `TracerProvider`. Please +refer to corresponding documentation of the instrumentation library to know the +exact method name. + +Follow [this](../extending-the-sdk/README.md#instrumentation-library) document +to learn about the instrumentation libraries shipped from this repo. ### Processor -// TODO +[Processors](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor) +allows hooks for start and end of `Activity`. If no processors are configured, +then traces are simply dropped by the SDK. `AddProcessor` method on +`TracerProviderBuilder` should be used to add a processor. There can be any +number of processors added to the provider, and they are invoked in the same +order as they are added. Unlike `Sampler` or `Resource`, processors can be added +to the provider even *after* it is built. + +The snippet below shows how to add processors to the provider before and after +it is built. + +```csharp +using OpenTelemetry; +using OpenTelemetry.Trace; + +using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddProcessor(new MyProcessor1()) + .AddProcessor(new MyProcessor2())) + .Build(); + +// Processors can be added to provider even after it is built. +// Only those traces which are emitted after this line, will be sent to it. +tracerProvider.AddProcessor(new MyProcessor3()); +``` + +A `TracerProvider` assumes ownership of any processors added to it. This means +that, provider will call `Shutdown` method on the processor, when it is +shutdown, and disposes the processor when it is disposed. If multiple providers +are being setup in an application, then separate instances of processors must be +configured on them. Otherwise, shutting down one provider can cause the +processor in other provider to be shut down as well, leading to undesired +results. + +Processors can be used for enriching the telemetry and exporting the telemetry +to an exporter. For enriching purposes, one must write a custom processor, and +override the `OnStart` or `OnEnd` method with logic to enrich the telemetry. For +exporting purposes, the SDK provides the following built-in processors: + +* [BatchExportProcessor<T>](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#batching-processor) + : This is an exporting processor which batches the telemetry before sending to + the configured exporter. + + The following environment variables can be used to override the default + values of the `BatchExportActivityProcessorOptions`. + + | Environment variable | `BatchExportActivityProcessorOptions` property | + | -------------------------------- | ---------------------------------------------- | + | `OTEL_BSP_SCHEDULE_DELAY` | `ScheduledDelayMilliseconds` | + | `OTEL_BSP_EXPORT_TIMEOUT` | `ExporterTimeoutMilliseconds` | + | `OTEL_BSP_MAX_QUEUE_SIZE` | `MaxQueueSize` | + | `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSizeEnvVarKey` | + + `FormatException` is thrown in case of an invalid value for any of the + supported environment variables. + +* [CompositeProcessor<T>](../../../src/OpenTelemetry/CompositeProcessor.cs) + : This is a processor which can be composed from multiple processors. This is + typically used to construct multiple processing pipelines, each ending with + its own exporter. + +* [SimpleExportProcessor<T>](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#simple-processor) + : This is an exporting processor which passes telemetry to the configured + exporter without any batching. + +Follow [this](../extending-the-sdk/README.md#processor) document +to learn about how to write own processors. + +*The processors shipped from this SDK are generics, and supports tracing and +logging, by supporting `Activity` and `LogRecord` respectively.* ### Resource