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

Move more SDK docs to docs folder (#3794)

This commit is contained in:
Cijo Thomas 2022-10-20 13:10:15 -04:00 committed by GitHub
parent 079d4115b4
commit 13ea238abb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 85 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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