From 032514dd4a7e6c7a25082606574fb16819815c81 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sun, 8 May 2022 07:58:45 -0700 Subject: [PATCH] Add Jaeger tutorial (#3258) * add Jaeger tutorial * http instr --- docs/trace/getting-started-jaeger/Program.cs | 59 ++++++++ docs/trace/getting-started-jaeger/README.md | 133 ++++++++++++++++++ .../getting-started-jaeger.csproj | 7 + docs/trace/getting-started/README.md | 5 +- src/OpenTelemetry.Exporter.Jaeger/README.md | 7 +- 5 files changed, 207 insertions(+), 4 deletions(-) create mode 100644 docs/trace/getting-started-jaeger/Program.cs create mode 100644 docs/trace/getting-started-jaeger/README.md create mode 100644 docs/trace/getting-started-jaeger/getting-started-jaeger.csproj diff --git a/docs/trace/getting-started-jaeger/Program.cs b/docs/trace/getting-started-jaeger/Program.cs new file mode 100644 index 000000000..6cf3628f3 --- /dev/null +++ b/docs/trace/getting-started-jaeger/Program.cs @@ -0,0 +1,59 @@ +// +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +using System; +using System.Diagnostics; +using System.Net.Http; +using System.Threading.Tasks; +using OpenTelemetry; +using OpenTelemetry.Resources; +using OpenTelemetry.Trace; + +namespace GettingStartedJaeger; + +public class Program +{ + private static readonly ActivitySource MyActivitySource = new("OpenTelemetry.Demo.Jaeger"); + + public static async Task Main() + { + using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService( + serviceName: "DemoApp", + serviceVersion: "1.0.0")) + .AddSource("OpenTelemetry.Demo.Jaeger") + .AddHttpClientInstrumentation() + .AddConsoleExporter() + .AddJaegerExporter() + .Build(); + + using var parent = MyActivitySource.StartActivity("JaegerDemo"); + + using (var client = new HttpClient()) + { + using (var slow = MyActivitySource.StartActivity("SomethingSlow")) + { + await client.GetStringAsync("https://httpstat.us/200?sleep=1000"); + await client.GetStringAsync("https://httpstat.us/200?sleep=1000"); + } + + using (var fast = MyActivitySource.StartActivity("SomethingFast")) + { + await client.GetStringAsync("https://httpstat.us/301"); + } + } + } +} diff --git a/docs/trace/getting-started-jaeger/README.md b/docs/trace/getting-started-jaeger/README.md new file mode 100644 index 000000000..cae7f6a74 --- /dev/null +++ b/docs/trace/getting-started-jaeger/README.md @@ -0,0 +1,133 @@ +# Getting Started with Jaeger + +- [Export traces from the application](#export-traces-from-the-application) + - [Check results in the console](#check-results-in-the-console) +- [Collect and visualize traces using Jaeger](#collect-and-visualize-traces-using-jaeger) +- [Final cleanup](#final-cleanup) +- [Learn more](#learn-more) + +## Export traces from the application + +It is highly recommended to go over the [getting-started](../getting-started/README.md) +doc before following along this document. + +Create a new console application and run it: + +```sh +dotnet new console --output getting-started-jaeger +cd getting-started-jaeger +dotnet run +``` + +Add reference to [Console +Exporter](../../../src/OpenTelemetry.Exporter.Console/README.md), [Jaeger +Exporter](../../../src/OpenTelemetry.Exporter.Jaeger/README.md) and [HttpClient +Instrumentation](../../../src/OpenTelemetry.Instrumentation.Http/README.md): + +```sh +dotnet add package OpenTelemetry.Exporter.Console +dotnet add package OpenTelemetry.Exporter.Jaeger +dotnet add package OpenTelemetry.Instrumentation.Http +``` + +Now copy the code from [Program.cs](./Program.cs). + +### Check results in the console + +Run the application again and we should see the trace output from the console: + +```text +> dotnet run + +Activity.TraceId: a80c920e0aabb50b547e2bb7455cfd39 +Activity.SpanId: 4e45a1d51744f329 +Activity.TraceFlags: Recorded +Activity.ParentSpanId: 4f7e9b78c55dcfad +Activity.ActivitySourceName: OpenTelemetry.Instrumentation.Http +Activity.DisplayName: HTTP GET +Activity.Kind: Client +Activity.StartTime: 2022-05-07T02:54:25.7840762Z +Activity.Duration: 00:00:01.9615540 +Activity.Tags: + http.method: GET + http.host: httpstat.us + http.url: https://httpstat.us/200?sleep=1000 + http.status_code: 200 +Resource associated with Activity: + service.name: DemoApp + service.version: 1.0.0 + service.instance.id: 1b3b3a6f-be43-46b0-819a-4db1200c633d + +... +``` + +Note that we have configured two exporters in the code: + +```csharp +using var tracerProvider = Sdk.CreateTracerProviderBuilder() + ... + .AddConsoleExporter() + .AddJaegerExporter() + .Build(); +``` + +When we run the application, the `ConsoleExporter` was printing the traces on +console, and the `JaegerExporter` was attempting to send the traces to Jaeger +Agent via the default endpoint `udp://localhost:6831`. + +Since we didn't have Jaeger running, the traces received by `JaegerExporter` +were simply dropped on the floor. In the next step, we are going to learn about +how to use Jaeger to collect and visualize the traces. + +## Collect and visualize traces using Jaeger + +### Install and run Jaeger + +Download the [latest binary distribution +archive](https://www.jaegertracing.io/download/) of Jaeger. + +After finished downloading, extract it to a local location that's easy to +access. Run the `jaeger-all-in-one(.exe)` executable: + +```sh +./jaeger-all-in-one +``` + +Now we should be able to see the Jaeger UI at +[http://localhost:16686/](http://localhost:16686/) from a web browser: + +![Jaeger UI](https://user-images.githubusercontent.com/17327289/167234463-1e172ed6-df8e-44bf-8a41-f76efd502394.png) + +Run the application again and refresh the web page, we should be able to see the +traces now: + +![image](https://user-images.githubusercontent.com/17327289/167234922-32e7828a-3a68-4d11-84e9-87f542b99447.png) + +Click on the individual trace to see the [Gantt +Chart](https://en.wikipedia.org/wiki/Gantt_chart): + +![image](https://user-images.githubusercontent.com/17327289/167234792-c53413a1-0e9f-4ec9-8435-5a0c79681c7e.png) + +## Final cleanup + +In the end, remove the Console Exporter so we only have Jaeger Exporter in the +final application: + +```csharp +using var tracerProvider = Sdk.CreateTracerProviderBuilder() + ... + // Remove Console Exporter from the final application + // .AddConsoleExporter() + .AddJaegerExporter() + .Build(); +``` + +```sh +dotnet remove package OpenTelemetry.Exporter.Console +``` + +## Learn more + +- [Jaeger Tracing](https://www.jaegertracing.io/) +- [Jaeger Exporter for OpenTelemetry + .NET](../../../src/OpenTelemetry.Exporter.Jaeger/README.md) diff --git a/docs/trace/getting-started-jaeger/getting-started-jaeger.csproj b/docs/trace/getting-started-jaeger/getting-started-jaeger.csproj new file mode 100644 index 000000000..e9899f2c7 --- /dev/null +++ b/docs/trace/getting-started-jaeger/getting-started-jaeger.csproj @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/trace/getting-started/README.md b/docs/trace/getting-started/README.md index daf1edd1a..b94edfe27 100644 --- a/docs/trace/getting-started/README.md +++ b/docs/trace/getting-started/README.md @@ -120,7 +120,10 @@ to learn more. ## Learn more -* If you want to customize the Sdk, refer to [customizing +* If you want to collect and visualize traces using + [Jaeger](https://www.jaegertracing.io/), refer to [Getting Started with + Jaeger](../getting-started-jaeger/README.md). +* If you want to customize the SDK, refer to [customizing the SDK](../customizing-the-sdk/README.md). * If you want to build a custom exporter/processor/sampler, refer to [extending the SDK](../extending-the-sdk/README.md). diff --git a/src/OpenTelemetry.Exporter.Jaeger/README.md b/src/OpenTelemetry.Exporter.Jaeger/README.md index 5849eac0a..2a67fb66d 100644 --- a/src/OpenTelemetry.Exporter.Jaeger/README.md +++ b/src/OpenTelemetry.Exporter.Jaeger/README.md @@ -6,12 +6,13 @@ The Jaeger exporter converts OpenTelemetry traces into the Jaeger model following the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/jaeger.md). -The exporter communicates to a Jaeger Agent through the thrift protocol on +The exporter communicates to a Jaeger Agent through the Thrift protocol on the Compact Thrift API port, and as such only supports Thrift over UDP. -## Prerequisite +## Getting Started -* [Get Jaeger](https://www.jaegertracing.io/docs/1.13/getting-started/) +Refer to the [Getting Started with +Jaeger](../../docs/trace/getting-started-jaeger/README.md) tutorial. ## Installation