diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index e9d9e8e8b..605d5c8f2 100644 --- a/OpenTelemetry.sln +++ b/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 diff --git a/README.md b/README.md index 03c317b72..011275291 100644 --- a/README.md +++ b/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). diff --git a/docs/logs/building-your-own-exporter.md b/docs/logs/building-your-own-exporter.md new file mode 100644 index 000000000..158fb82e4 --- /dev/null +++ b/docs/logs/building-your-own-exporter.md @@ -0,0 +1,3 @@ +# Building your own Exporter + +Under construction. diff --git a/docs/logs/getting-started.md b/docs/logs/getting-started.md new file mode 100644 index 000000000..156566172 --- /dev/null +++ b/docs/logs/getting-started.md @@ -0,0 +1,3 @@ +# Getting Started with OpenTelemetry .NET in 5 Minutes + +Under construction. diff --git a/docs/logs/logging-correlation.md b/docs/logs/logging-correlation.md new file mode 100644 index 000000000..156566172 --- /dev/null +++ b/docs/logs/logging-correlation.md @@ -0,0 +1,3 @@ +# Getting Started with OpenTelemetry .NET in 5 Minutes + +Under construction. diff --git a/docs/metrics/building-your-own-exporter.md b/docs/metrics/building-your-own-exporter.md new file mode 100644 index 000000000..158fb82e4 --- /dev/null +++ b/docs/metrics/building-your-own-exporter.md @@ -0,0 +1,3 @@ +# Building your own Exporter + +Under construction. diff --git a/docs/metrics/getting-started.md b/docs/metrics/getting-started.md new file mode 100644 index 000000000..156566172 --- /dev/null +++ b/docs/metrics/getting-started.md @@ -0,0 +1,3 @@ +# Getting Started with OpenTelemetry .NET in 5 Minutes + +Under construction. diff --git a/docs/trace/building-your-own-exporter.md b/docs/trace/building-your-own-exporter.md new file mode 100644 index 000000000..27facaacb --- /dev/null +++ b/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 ExportAsync( + IEnumerable 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(); +``` diff --git a/docs/trace/building-your-own-instrumentation-library.md b/docs/trace/building-your-own-instrumentation-library.md new file mode 100644 index 000000000..9c3f4d546 --- /dev/null +++ b/docs/trace/building-your-own-instrumentation-library.md @@ -0,0 +1,3 @@ +# Building your own Instrumentation Library + +Under construction. diff --git a/docs/trace/building-your-own-sampler.md b/docs/trace/building-your-own-sampler.md new file mode 100644 index 000000000..2271ad58e --- /dev/null +++ b/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); + } +} +``` diff --git a/docs/getting-started.md b/docs/trace/getting-started.md similarity index 93% rename from docs/getting-started.md rename to docs/trace/getting-started.md index e950687b0..646b563ba 100644 --- a/docs/getting-started.md +++ b/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 diff --git a/docs/trace/getting-started/Program.cs b/docs/trace/getting-started/Program.cs new file mode 100644 index 000000000..adf257965 --- /dev/null +++ b/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!"); + } + } +} diff --git a/docs/trace/getting-started/getting-started.csproj b/docs/trace/getting-started/getting-started.csproj new file mode 100644 index 000000000..7d6dc6d3f --- /dev/null +++ b/docs/trace/getting-started/getting-started.csproj @@ -0,0 +1,12 @@ + + + + Exe + netcoreapp3.1 + + + + + + + diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index ba2ca67af..43c7bf787 100644 --- a/src/OpenTelemetry/README.md +++ b/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 ExportAsync( - IEnumerable 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