From e86e49a2e9b6f475f65c63cdd725a35c9104b109 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Wed, 12 Aug 2020 08:48:31 -0700 Subject: [PATCH] Replace docs example with actual code (#1054) * Replace doc with actual program * fix * min * fix * review coment * fix format * fix docfx build --- OpenTelemetry.sln | 1 - README.md | 3 +- docs/docfx.json | 3 +- docs/trace/getting-started.md | 81 --------------------- docs/trace/getting-started/Program.cs | 1 - docs/trace/getting-started/README.md | 54 ++++++++++++++ src/OpenTelemetry.Exporter.ZPages/README.md | 1 + src/OpenTelemetry/README.md | 2 +- 8 files changed, 59 insertions(+), 87 deletions(-) delete mode 100644 docs/trace/getting-started.md create mode 100644 docs/trace/getting-started/README.md diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 6bbdbc9c7..45f7e04b2 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -167,7 +167,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "trace", "trace", "{5B7FB835 docs\trace\building-your-own-instrumentation-library.md = docs\trace\building-your-own-instrumentation-library.md docs\trace\building-your-own-processor.md = docs\trace\building-your-own-processor.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 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "building-your-own-processor", "docs\trace\building-your-own-processor\building-your-own-processor.csproj", "{B1891B31-B021-4074-8E42-B4AC170CD208}" diff --git a/README.md b/README.md index 652e334ed..202fb53f5 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,7 @@ The .NET [OpenTelemetry](https://opentelemetry.io/) client. ## Getting Started -If you are new here, please [get started in 5 minutes](./docs/trace/getting-started.md). - +If you are new here, please [get started in 5 minutes](./docs/trace/getting-started/README.md). This repository includes multiple installable components, available on [NuGet](https://www.nuget.org/profiles/OpenTelemetry). diff --git a/docs/docfx.json b/docs/docfx.json index e8b5a9b1b..fea80f746 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -30,7 +30,8 @@ "files": [ "docs/**.png", "examples/**.cs", - "src/**.cs" + "src/**.cs", + "docs/**.cs" ] } ], diff --git a/docs/trace/getting-started.md b/docs/trace/getting-started.md deleted file mode 100644 index e251e0c63..000000000 --- a/docs/trace/getting-started.md +++ /dev/null @@ -1,81 +0,0 @@ -# Getting Started with OpenTelemetry .NET in 5 Minutes - -First, download and install the [.NET Core -SDK](https://dotnet.microsoft.com/download) on your computer. - -Create a new console application and run it: - -```sh -dotnet new console --output getting-started -cd getting-started -dotnet run -``` - -You should see the following output: - -```console -Hello World! -``` - -Install the -[OpenTelemetry.Exporter.Console](../../src/OpenTelemetry.Exporter.Console/README.md) -package: - -```sh -dotnet add package OpenTelemetry.Exporter.Console -v 0.4.0-beta.2 -``` - -Update the `Program.cs` file with the following code: - -```csharp -using System.Diagnostics; -using OpenTelemetry; -using OpenTelemetry.Trace; - -public class Program -{ - private static readonly ActivitySource MyActivitySource = new ActivitySource( - "MyCompany.MyProduct.MyLibrary"); - - public static void Main() - { - using var otel = Sdk.CreateTracerProvider(b => b - .AddActivitySource("MyCompany.MyProduct.MyLibrary") - .UseConsoleExporter()); - - using (var activity = MyActivitySource.StartActivity("SayHello")) - { - activity?.SetTag("foo", 1); - activity?.SetTag("bar", "Hello, World!"); - } - } -} -``` - -Run the application again (using `dotnet run`) and you should see the trace -output from the console. - -```text -Activity ID - 00-3ae67370100cdc44a8d461d1b2cf846f-d80f2b1ab6d3bc4b-01 -Activity DisplayName - SayHello -Activity Kind - Internal -Activity StartTime - 7/24/2020 1:16:21 AM -Activity Duration - 00:00:00.0018754 -Activity Tags - foo : 1 - bar : Hello, World! -``` - -Congratulations! You are now collecting traces using OpenTelemetry. - -What does the above program do? - -The program creates an `ActivitySource` which represents [OpenTelemetry -Tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracer). -The activitysource instance is used to start an `Activity` which represent -[OpenTelemetry -Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span). -`Sdk.CreateTracerProvider` sets up the OpenTelemetry Sdk, and -configures it to subscribe to the activities from the source -`MyCompany.MyProduct.MyLibrary`, and export it to `ConsoleExporter`, which -simply displays it on the console. diff --git a/docs/trace/getting-started/Program.cs b/docs/trace/getting-started/Program.cs index def1cbf76..48b821c39 100644 --- a/docs/trace/getting-started/Program.cs +++ b/docs/trace/getting-started/Program.cs @@ -16,7 +16,6 @@ using System.Diagnostics; using OpenTelemetry; -using OpenTelemetry.Exporter.Console; using OpenTelemetry.Trace; public class Program diff --git a/docs/trace/getting-started/README.md b/docs/trace/getting-started/README.md new file mode 100644 index 000000000..24cf71a21 --- /dev/null +++ b/docs/trace/getting-started/README.md @@ -0,0 +1,54 @@ +# Getting Started with OpenTelemetry .NET in 5 Minutes + +First, download and install the [.NET Core +SDK](https://dotnet.microsoft.com/download) on your computer. + +Create a new console application and run it: + +```sh +dotnet new console --output getting-started cd getting-started dotnet run +``` + +You should see the following output: + +```console +Hello World! +``` + +Install the +[OpenTelemetry.Exporter.Console](../../../src/OpenTelemetry.Exporter.Console/README.md) +package: + +```sh +dotnet add package OpenTelemetry.Exporter.Console -v 0.4.0-beta.2 +``` + +Update the `Program.cs` file with the code from [Program.cs](./Program.cs): + +Run the application again (using `dotnet run`) and you should see the trace +output from the console. + +```text +Activity.Id: +00-55c1ae1c6c23784bbc4fca463d7e15ca-bfe3220d9e489e4b-01 Activity.ParentId: +00-55c1ae1c6c23784bbc4fca463d7e15ca-0000000000000000-00 Activity.DisplayName: +SayHello Activity.Kind: Internal Activity.StartTime: +2020-08-12T07:37:40.9681787Z Activity.Duration: 00:00:00.0047972 +Activity.TagObjects: + foo: 1 bar: Hello, World! baz: [1, 2, 3] +``` + +Congratulations! You are now collecting traces using OpenTelemetry. + +What does the above program do? + +The program creates an `ActivitySource` which represents [OpenTelemetry +Tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracer). +The activitysource instance is used to start an `Activity` which represent +[OpenTelemetry +Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span). +An OpenTelemetry +[TracerProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracerprovider) +configured to subscribe to the activities from the source +`MyCompany.MyProduct.MyLibrary`, and export it to `ConsoleExporter`. +`ConsoleExporter` simply displays it on the console. diff --git a/src/OpenTelemetry.Exporter.ZPages/README.md b/src/OpenTelemetry.Exporter.ZPages/README.md index a32eb14fb..a6b8b2cc2 100644 --- a/src/OpenTelemetry.Exporter.ZPages/README.md +++ b/src/OpenTelemetry.Exporter.ZPages/README.md @@ -23,3 +23,4 @@ for an example of how to use the exporter. ## References * [OpenTelemetry Project](https://opentelemetry.io/) +* [zPages](https://opencensus.io/zpages/) diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index a1dd13a95..c5eea6cce 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -40,7 +40,7 @@ the following. ## Getting started Please follow the tutorial and [get started in 5 -minutes](../../docs/trace/getting-started.md). +minutes](../../docs/trace/getting-started/README.md). ## Configuration