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

Minor improvement on the "extending the sdk" doc (#1220) 

* minor improvement on the customization doc

* add code snippet and more details

* make the snippet self-contained
This commit is contained in:
Reiley Yang 2020-09-01 23:03:10 -07:00 committed by GitHub
parent 849df458f6
commit 8fc88d28f6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 66 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -16,22 +16,39 @@ OpenTelemetry .NET SDK has provided the following built-in exporters:
* [Zipkin](../../../src/OpenTelemetry.Exporter.Zipkin/README.md)
Custom exporters can be implemented to send telemetry data to places which are
not covered by the built-in exporters.
not covered by the built-in exporters:
Here is the guidance for writing a custom exporter:
* Exporters should derive from `ActivityExporter` (which belongs to the
[OpenTelemetry](https://www.nuget.org/packages/opentelemetry) package) and
implement `Export` method.
* Exporters can optionally implement `OnShutdown`.
* Exporters should derive from `OpenTelemetry.Trace.ActivityExporter` (which
belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package)
and implement the `Export` method.
* Exporters can optionally implement the `OnShutdown` method.
* Depending on user's choice and load on the application, `Export` may get
called with one or more activities.
* Exporters will only receive sampled-in and ended activities.
* Exporters should not throw exceptions.
* Exporters should not throw exceptions from `Export` and `OnShutdown`.
* Exporters should not modify activities they receive (the same activity may be
exported again by different exporter).
* Exporters are responsible for any retry logic needed by the scenario. The SDK
does not implement any retry logic.
* Exporters should avoid generating telemetry and causing live-loop, this can be
done via `OpenTelemetry.SuppressInstrumentationScope`.
```csharp
class MyExporter : ActivityExporter
{
public override ExportResult Export(in Batch<Activity> batch)
{
using var scope = SuppressInstrumentationScope.Begin();
foreach (var activity in batch)
{
Console.WriteLine($"Export: {activity.DisplayName}");
}
return ExportResult.Success;
}
}
```
A demo exporter which simply writes activity name to the console is shown
[here](./MyExporter.cs).
@ -40,13 +57,6 @@ Apart from the exporter itself, you should also provide extension methods as
shown [here](./MyExporterHelperExtensions.cs). This allows users to add the
Exporter to the `TracerProvider` as shown in the example [here](./Program.cs).
To run the full example code demonstrating the exporter, run the following
command from this folder.
```sh
dotnet run
```
## Instrumentation Library
TBD
@ -60,6 +70,35 @@ OpenTelemetry .NET SDK has provided the following built-in processors:
* [ReentrantExportActivityProcessor](../../../src/OpenTelemetry/Trace/ReentrantExportActivityProcessor.cs)
* [SimpleExportActivityProcessor](../../../src/OpenTelemetry/Trace/SimpleExportActivityProcessor.cs)
Custom processors can be implemented to cover more scenarios:
* Processors should inherit from `OpenTelemetry.Trace.ActivityProcessor` (which
belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package),
and implement the `OnStart` and `OnEnd` methods.
* Processors can optionally implement the `OnForceFlush` and `OnShutdown`
methods. `OnForceFlush` should be thread safe.
* Processors should not throw exceptions from `OnStart`, `OnEnd`, `OnForceFlush`
and `OnShutdown`.
* `OnStart` and `OnEnd` should be thread safe, and should not block or take long
time, since they will be called on critical code path.
```csharp
class MyProcessor : ActivityProcessor
{
public override void OnStart(Activity activity)
{
Console.WriteLine($"OnStart: {activity.DisplayName}");
}
public override void OnEnd(Activity activity)
{
Console.WriteLine($"OnEnd: {activity.DisplayName}");
}
}
```
A demo processor is shown [here](./MyProcessor.cs).
## Sampler
OpenTelemetry .NET SDK has provided the following built-in samplers:
@ -71,12 +110,14 @@ OpenTelemetry .NET SDK has provided the following built-in samplers:
Custom samplers can be implemented to cover more scenarios:
* Samplers should inherit from `Sampler`, and implement `ShouldSample` method.
* `ShouldSample` should not block or take long time, since it will be called on
critical code path.
* Samplers should inherit from `OpenTelemetry.Trace.Sampler` (which belongs to
the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package), and
implement the `ShouldSample` method.
* `ShouldSample` should be thread safe, and should not block or take long time,
since it will be called on critical code path.
```csharp
internal class MySampler : Sampler
class MySampler : Sampler
{
public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
{
@ -85,7 +126,13 @@ internal class MySampler : Sampler
}
```
A demo sampler is shown [here](./MySampler.cs).
## References
* [Exporter
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter)
* [Processor
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-processor)
* [Sampler
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampler)