Clean up SDK doc (#889)

* consolidate SDK doc * clean up * update the name * update the doc to reflect API change * update the doc to reflect API change * fix ci * Revert "fix ci" This reverts commit 00dd532. Co-authored-by: Cijo Thomas <[email protected]>
open-telemetry · Jul 23, 2020 · 62613e4 · 62613e4
1 parent a03af9e
commit 62613e4
Showing 1 changed file with 85 additions and 76 deletions.
diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md
@@ -5,14 +5,15 @@
 
 * [Installation](#installation)
 * [Introduction](#introduction)
-* [Basic usage](#basic-usage)
-* [Advanced usage scenarios](#advanced-usage-scenarios)
-  * [Customize Exporter](#customize-exporter)
-  * [Customize Sampler](#customize-sampler)
-  * [Customize Resource](#customize-resource)
-  * [Filtering and enriching activities using
-    Processor](#filtering-and-enriching-activities-using-processor)
-  * [OpenTelemetry Instrumentation](#opentelemetry-instrumentation)
+* [Getting started](#getting-started)
+* [Configuration](#configuration)
+  * [Instrumentation](#instrumentation)
+  * [Processor](#processor)
+  * [Resource](#resource)
+  * [Sampler](#sampler)
+* [Advanced topics](#advanced-topics)
+  * [Building your own Exporter](#building-your-own-exporter)
+  * [Building your own Sampler](#building-your-own-sampler)
 * [References](#references)
 
 ## Installation
@@ -33,57 +34,25 @@ the following.
   samplers](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#built-in-samplers)
 * Set of [Built-in
   processors](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#built-in-span-processors).
-  * SimpleProcessor which sends Activities to the exporter without any batching.
+  * SimpleProcessor which sends Activities to the exporter without any
+    batching.
   * BatchingProcessor which batches and sends Activities to the exporter.
 * Extensibility options for users to customize SDK.
 
-## Basic usage
+## Getting started
 
-The following examples show how to start collecting OpenTelemetry traces from a
-console application, and have the traces displayed in the console.
+Please follow the tutorial and [get started in 5
+minutes](../../docs/getting-started.md).
 
-1. Create a console application and install the `OpenTelemetry.Exporter.Console`
-   package to your project.
+## Configuration
 
-    ```xml
-    <ItemGroup>
-      <PackageReference
-        Include="OpenTelemetry.Exporter.Console"
-        Version="0.3.0"
-      />
-    </ItemGroup>
-    ```
+### Instrumentation
 
-2. At the beginning of the application, enable OpenTelemetry SDK with
-   ConsoleExporter as shown below. It also configures to collect activities from
-   the source named "companyname.product.library".
+### Processor
 
-    ```csharp
-    using var openTelemetry = OpenTelemetrySdk.CreateTracerProvider(builder => builder
-                    .AddActivitySource("companyname.product.library")
-                    .UseConsoleExporter())
-    ```
+### Resource
 
-    The above requires import of namespace `OpenTelemetry.Trace`.
-
-3. Generate some activities in the application as shown below.
-
-    ```csharp
-    var activitySource = new ActivitySource("companyname.product.library");
-
-    using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server))
-    {
-        activity?.AddTag("http.method", "GET");
-    }
-    ```
-
-Run the application. Traces will be displayed in the console.
-
-## Advanced usage scenarios
-
-### Customize Exporter
-
-### Customize Sampler
+### Sampler
 
 [Samplers](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampler)
 are used to control the noise and overhead introduced by OpenTelemetry by
@@ -95,48 +64,88 @@ The following sample shows how to change it to
 with sampling probability of 25%.
 
 ```csharp
-using var openTelemetry = OpenTelemetrySdk.CreateTracerProvider(builder => builder
-                .AddActivitySource("companyname.product.library")
-                .SetSampler(new ProbabilitySampler(.25))
-                .UseConsoleExporter());
+using OpenTelemetry.Trace.Samplers;
+
+using var otel = OpenTelemetrySdk.CreateTracerProvider(b => b
+    .AddActivitySource("MyCompany.MyProduct.MyLibrary")
+    .SetSampler(new ProbabilitySampler(0.25))
+    .UseConsoleExporter());
 ```
 
-  The above requires import of the namespace `OpenTelemetry.Trace.Samplers`.
-
-  You can also implement a custom sampler by subclassing `Sampler`
+## Advanced topics
+
+### Building your own Exporter
+
+#### Trace Exporter
+
+* Exporters should inherit from `ActivityExporter` and implement `ExportAsync`
+  and `ShutdownAsync` methods.
+* Depending on user's choice and load on the application `ExportAsync` may get
+  called concurrently with zero or more activities.
+* Exporters should expect to receive only sampled-in ended activities.
+* Exporters must not throw.
+* Exporters should not modify activities they receive (the same activity may be
+  exported again by different exporter).
 
 ```csharp
-class MySampler : Sampler
+class MyExporter : ActivityExporter
 {
-    public override string Description { get; } = "mysampler";
-
-    public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
+    public override Task<ExportResult> ExportAsync(
+        IEnumerable<Activity> batch, CancellationToken cancellationToken)
     {
-        bool sampledIn;
-        var parentContext = samplingParameters.ParentContext;
-        if (parentContext != null && parentContext.IsValid())
-        {
-            sampledIn = (
-                parentContext.TraceFlags & ActivityTraceFlags.Recorded
-            ) != 0;
-        }
-        else
+        foreach (var activity in batch)
         {
-            sampledIn = Stopwatch.GetTimestamp() % 2 == 0;
+            Console.WriteLine(
+                $"[{activity.StartTimeUtc:o}] " +
+                $"{activity.DisplayName} " +
+                $"{activity.Context.TraceId.ToHexString()} " +
+                $"{activity.Context.SpanId.ToHexString()}"
+            );
         }
 
-        return new SamplingResult(sampledIn);
+        return Task.FromResult(ExportResult.Success);
+    }
+
+    public override Task ShutdownAsync(CancellationToken cancellationToken)
+    {
+        return Task.CompletedTask;
+    }
+
+    protected override void Dispose(bool disposing)
+    {
+        // flush the data and clean up the resource
     }
 }
 ```
 
-### Customize Resource
+* Users may configure the exporter similarly to other exporters.
+* You should also provide additional methods to simplify configuration
+  similarly to `UseZipkinExporter` extension method.
+
+```csharp
+OpenTelemetrySdk.CreateTracerProvider(b => b
+    .AddActivitySource(ActivitySourceName)
+    .UseMyExporter();
+```
+
+### Building your own Sampler
 
-### Filtering and enriching activities using Processor
+* 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.
 
-### OpenTelemetry Instrumentation
+```csharp
+class MySampler : Sampler
+{
+    public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
+    {
+        var shouldSample = true;
 
-This should link to the Instrumentation documentation.
+        return new SamplingResult(shouldSample);
+    }
+}
+```
 
 ## References