Doc skeleton (#943)

* skeleton doc

* fix nits

OpenTelemetry.sln

@@ -152,7 +152,16 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Instrumentati
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}"
 	ProjectSection(SolutionItems) = preProject
-		docs\getting-started.md = docs\getting-started.md
+		docs\logs\building-your-own-exporter.md = docs\logs\building-your-own-exporter.md
+		docs\logs\getting-started.md = docs\logs\getting-started.md
+		docs\logs\logging-correlation.md = docs\logs\logging-correlation.md
+		docs\trace\building-your-own-exporter.md = docs\trace\building-your-own-exporter.md
+		docs\metrics\building-your-own-exporter.md = docs\metrics\building-your-own-exporter.md
+		docs\metrics\getting-started.md = docs\metrics\getting-started.md
+		docs\trace\building-your-own-exporter.md = docs\trace\building-your-own-exporter.md
+		docs\trace\building-your-own-instrumentation-library.md = docs\trace\building-your-own-instrumentation-library.md
+		docs\trace\building-your-own-sampler.md = docs\trace\building-your-own-sampler.md
+		docs\trace\getting-started.md = docs\trace\getting-started.md
 	EndProjectSection
 EndProject
 Global

README.md

@@ -11,7 +11,7 @@ The .NET [OpenTelemetry](https://opentelemetry.io/) client.
 
 ## Getting Started
 
-If you are new here, please [get started in 5 minutes](./docs/getting-started.md).
+If you are new here, please [get started in 5 minutes](./docs/trace/getting-started.md).
 
 This repository includes multiple installable components, available on
 [NuGet](https://www.nuget.org/profiles/OpenTelemetry).

docs/logs/building-your-own-exporter.md

@@ -0,0 +1,3 @@
+# Building your own Exporter
+
+Under construction.

docs/logs/getting-started.md

@@ -0,0 +1,3 @@
+# Getting Started with OpenTelemetry .NET in 5 Minutes
+
+Under construction.

docs/logs/logging-correlation.md

@@ -0,0 +1,3 @@
+# Getting Started with OpenTelemetry .NET in 5 Minutes
+
+Under construction.

docs/metrics/building-your-own-exporter.md

@@ -0,0 +1,3 @@
+# Building your own Exporter
+
+Under construction.

docs/metrics/getting-started.md

@@ -0,0 +1,3 @@
+# Getting Started with OpenTelemetry .NET in 5 Minutes
+
+Under construction.

docs/trace/building-your-own-exporter.md

@@ -0,0 +1,51 @@
+# Building your own 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 MyExporter : ActivityExporter
+{
+    public override Task<ExportResult> ExportAsync(
+        IEnumerable<Activity> batch, CancellationToken cancellationToken)
+    {
+        foreach (var activity in batch)
+        {
+            Console.WriteLine(
+                $"[{activity.StartTimeUtc:o}] " +
+                $"{activity.DisplayName} " +
+                $"{activity.Context.TraceId.ToHexString()} " +
+                $"{activity.Context.SpanId.ToHexString()}"
+            );
+        }
+
+        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
+    }
+}
+```
+
+* Users may configure the exporter similarly to other exporters.
+* You should also provide additional methods to simplify configuration
+  similarly to `UseZipkinExporter` extension method.
+
+```csharp
+Sdk.CreateTracerProvider(b => b
+    .AddActivitySource(ActivitySourceName)
+    .UseMyExporter();
+```

docs/trace/building-your-own-instrumentation-library.md

@@ -0,0 +1,3 @@
+# Building your own Instrumentation Library
+
+Under construction.

docs/trace/building-your-own-sampler.md

@@ -0,0 +1,18 @@
+# Building your own Sampler
+
+* 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.
+
+```csharp
+class MySampler : Sampler
+{
+    public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
+    {
+        var shouldSample = true;
+
+        return new SamplingResult(shouldSample);
+    }
+}
+```

docs/trace/getting-started.md

@@ -6,8 +6,8 @@ SDK](https://dotnet.microsoft.com/download) on your computer.
 Create a new console application and run it:
 
 ```sh
-dotnet new console --output Hello
-cd Hello
+dotnet new console --output getting-started
+cd getting-started
 dotnet run
 ```
 
@@ -18,7 +18,7 @@ Hello World!
 ```
 
 Install the
-[OpenTelemetry.Exporter.Console](../src/OpenTelemetry.Exporter.Console/README.md)
+[OpenTelemetry.Exporter.Console](../../src/OpenTelemetry.Exporter.Console/README.md)
 package:
 
 ```sh

docs/trace/getting-started/Program.cs

@@ -0,0 +1,22 @@
+using System.Diagnostics;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+class Program
+{
+    static readonly ActivitySource activitySource = new ActivitySource(
+        "MyCompany.MyProduct.MyLibrary");
+
+    static void Main()
+    {
+        using var otel = Sdk.CreateTracerProvider(b => b
+            .AddActivitySource("MyCompany.MyProduct.MyLibrary")
+            .UseConsoleExporter());
+
+        using (var activity = activitySource.StartActivity("SayHello"))
+        {
+            activity?.AddTag("foo", "1");
+            activity?.AddTag("bar", "Hello, World!");
+        }
+    }
+}

docs/trace/getting-started/getting-started.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="[0.4.0-beta, 1.0)" />
+  </ItemGroup>
+
+</Project>

src/OpenTelemetry/README.md

@@ -12,8 +12,6 @@
   * [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
@@ -42,7 +40,7 @@ the following.
 ## Getting started
 
 Please follow the tutorial and [get started in 5
-minutes](../../docs/getting-started.md).
+minutes](../../docs/trace/getting-started.md).
 
 ## Configuration
 
@@ -76,78 +74,16 @@ using var otel = Sdk.CreateTracerProvider(b => b
 
 ## 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 MyExporter : ActivityExporter
-{
-    public override Task<ExportResult> ExportAsync(
-        IEnumerable<Activity> batch, CancellationToken cancellationToken)
-    {
-        foreach (var activity in batch)
-        {
-            Console.WriteLine(
-                $"[{activity.StartTimeUtc:o}] " +
-                $"{activity.DisplayName} " +
-                $"{activity.Context.TraceId.ToHexString()} " +
-                $"{activity.Context.SpanId.ToHexString()}"
-            );
-        }
-
-        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
-    }
-}
-```
-
-* Users may configure the exporter similarly to other exporters.
-* You should also provide additional methods to simplify configuration
-  similarly to `UseZipkinExporter` extension method.
-
-```csharp
-Sdk.CreateTracerProvider(b => b
-    .AddActivitySource(ActivitySourceName)
-    .UseMyExporter();
-```
-
-### Building your own Sampler
-
-* 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.
-
-```csharp
-class MySampler : Sampler
-{
-    public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
-    {
-        var shouldSample = true;
-
-        return new SamplingResult(shouldSample);
-    }
-}
-```
+* Logs
+  * [Building your own Exporter](../../docs/logs/building-your-own-exporter.md)
+  * [Logging correlation](../../docs/logs/logging-correlation.md)
+* Metrics
+  * [Building your own Exporter](../../docs/metrics/building-your-own-exporter.md)
+* Trace
+  * [Building your own Exporter](../../docs/trace/building-your-own-exporter.md)
+  * [Building your own Instrumentation
+    Library](../../docs/trace/building-your-own-instrumentation-library.md)
+  * [Building your own Sampler](../../docs/trace/building-your-own-sampler.md)
 
 ## References