From 8fc88d28f60196adb2207ba11d1f4403fcd99f18 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 1 Sep 2020 23:03:10 -0700 Subject: [PATCH] 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 --- docs/trace/extending-the-sdk/README.md | 85 ++++++++++++++++++++------ 1 file changed, 66 insertions(+), 19 deletions(-) diff --git a/docs/trace/extending-the-sdk/README.md b/docs/trace/extending-the-sdk/README.md index 495731c99..75b861d19 100644 --- a/docs/trace/extending-the-sdk/README.md +++ b/docs/trace/extending-the-sdk/README.md @@ -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 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)