From 00ee600fc75e296836eb6713e618ce643d0c4a46 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Mon, 20 Jul 2020 11:49:47 -0700 Subject: [PATCH] Basic docs (#847) Basic API usage doc, SDK usage doc. --- README.md | 6 +- docs/instrumentation.md | 26 ++ docs/sdk-usage.md | 90 ++++++ .../Exporters/Console/TestConsoleExporter.cs | 1 - src/OpenTelemetry.Api/README.md | 257 ++++++++++++++++++ 5 files changed, 378 insertions(+), 2 deletions(-) create mode 100644 docs/instrumentation.md create mode 100644 docs/sdk-usage.md create mode 100644 src/OpenTelemetry.Api/README.md diff --git a/README.md b/README.md index 795f6a00a..9f9aa3e1a 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,11 @@ The API and SDK packages are available on the following NuGet feeds: ## Documentation -The online documentation is available at TBD. +[OpenTelemetry .NET API](./src/OpenTelemetry.Api/README.md) + +[OpenTelemetry .NET SDK](./docs/sdk-usage.md) + +[OpenTelemetry .NET Instrumentation](./docs/instrumentation.md) ## Compatible Exporters diff --git a/docs/instrumentation.md b/docs/instrumentation.md new file mode 100644 index 000000000..e27b28c61 --- /dev/null +++ b/docs/instrumentation.md @@ -0,0 +1,26 @@ +# OpenTelemetry .NET Instrumentation Library + +[Instrumented +library](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md#instrumented-library) +denotes the library for which telemetry signals are gathered. [Instrumentation +library](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md#instrumentation-library) +refers to the library that provides instrumentation for a given instrumented +library. Instrumented Library and Instrumentation Library may be the same +library if it has built-in OpenTelemetry instrumentation. + +Instrumentation libraries were previously referred to as OpenTelemetry +Adapters. Other terms like `Auto-Collectors` were also in use previously. + +OpenTelemetry .NET currently provides the following Instrumentation Libraries. + +1. HttpClient (.NET Core) +2. [HttpClient (.NET Framework)](https://docs.microsoft.com/en-us/dotnet/api/system.net.httpwebrequest) +3. [ASP.NET](https://docs.microsoft.com/en-us/aspnet/overview) +4. [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) +5. SQL Client + 1. [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient) + 2. [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient) +6. [gRPC for .NET](https://github.com/grpc/grpc-dotnet) +7. [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis/) + +## Using HttpClient (.NET Core) Instrumentation diff --git a/docs/sdk-usage.md b/docs/sdk-usage.md new file mode 100644 index 000000000..4d3ec4c95 --- /dev/null +++ b/docs/sdk-usage.md @@ -0,0 +1,90 @@ +# Using OpenTelemetry SDK to send telemetry + +- [Using OpenTelemetry SDK to send + telemetry](#using-opentelemetry-sdk-to-send-telemetry) + - [OpenTelemetry SDK](#opentelemetry-sdk) + - [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) + +## OpenTelemetry SDK + +OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It +implements the Tracer API, the Metric API, and the Context API. OpenTelemetry +SDK deals with concerns such as sampling, processing pipeline, exporting +telemetry to a particular backend etc. The default implementation consists of +the following. + +1. Set of [Built-in + samplers](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#built-in-samplers) +2. Set of [Built-in + processors](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#built-in-span-processors). + 1. SimpleProcessor which sends Activities to the exporter without any + batching. + 2. BatchingProcessor which batches and sends Activities to the exporter. +3. Set of [Built-in + exporters](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter) + 1. Console - Displays activities in console. Used for testing purposes. + 2. Jaeger - Exports traces to [Jaeger](https://www.jaegertracing.io/) + 3. Zipkin- Exports traces to [Zipkin](https://zipkin.io/) + 4. zPages- Exports traces to [zPages](https://opencensus.io/zpages/) + 5. OpenTelemetry Protocol - Exports traces using OpenTelemetry protocol to + the OpenTelemetry Collector. + 6. Prometheus.- Exports metrics to [Prometheus](https://prometheus.io/) +4. Extensibility options for users to customize SDK. + +## Basic usage + +The following examples show how to start collecting OpenTelemetry traces from a +console application, and have the traces displayed in the console. + +1. Create a console application and install the `OpenTelemetry.Exporter.Console` + package to your it. + + ```xml + + + + ``` + +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". + + ```csharp + using var openTelemetry = OpenTelemetrySdk.EnableOpenTelemetry( + (builder) => builder.AddActivitySource("companyname.product.library") + .UseConsoleExporter(opt => opt.DisplayAsJson = options.DisplayAsJson)); + ``` + +3. Generate some activities in the application as shown below. + + ```csharp + var source = new ActivitySource("companyname.product.library"); + using (var parent = source.StartActivity("ActivityName", ActivityKind.Server)) + { + parent?.AddTag("http.method", "GET"); + } + ``` + +Run the application. Traces will be displayed in the console. + +## Advanced usage scenarios + +### Customize Exporter + +### Customize Sampler + +### Customize Resource + +### Filtering and enriching activities using Processor + +### OpenTelemetry Instrumentation + +This should link to the Instrumentation documentation. diff --git a/samples/Exporters/Console/TestConsoleExporter.cs b/samples/Exporters/Console/TestConsoleExporter.cs index 78e04e089..a57d89495 100644 --- a/samples/Exporters/Console/TestConsoleExporter.cs +++ b/samples/Exporters/Console/TestConsoleExporter.cs @@ -18,7 +18,6 @@ using System; using System.Diagnostics; using System.Threading; using System.Threading.Tasks; -using OpenTelemetry.Exporter.Console; using OpenTelemetry.Resources; using OpenTelemetry.Trace.Configuration; using OpenTelemetry.Trace.Export; diff --git a/src/OpenTelemetry.Api/README.md b/src/OpenTelemetry.Api/README.md new file mode 100644 index 000000000..3e9bb4b4b --- /dev/null +++ b/src/OpenTelemetry.Api/README.md @@ -0,0 +1,257 @@ +# Getting Started + +- [Getting Started](#getting-started) + - [OpenTelemetry API](#opentelemetry-api) + - [Tracer API](#tracer-api) + - [Metric API](#metric-api) + - [Introduction to OpenTelemetry .NET Tracer API](#introduction-to-opentelemetry-net-tracer-api) + - [Instrumenting a library/application with .NET Activity API](#instrumenting-a-libraryapplication-with-net-activity-api) + - [Basic usage](#basic-usage) + - [Activity creation options](#activity-creation-options) + - [Adding Events](#adding-events) + - [Setting Status](#setting-status) + - [Instrumenting a library/application with OpenTelemetry.API Shim](#instrumenting-a-libraryapplication-with-opentelemetryapi-shim) + +## OpenTelemetry API + +Application developers and library authors use OpenTelemetry API to instrument +their application/library. The API only surfaces necessary abstractions to +instrument an application/library. It does not address concerns like how +telemetry is exported to a specific telemetry backend, how to sample the +telemetry, etc. The API consists of [Tracer +API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md), +[Metric +API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md), +[Context and Propagation +API](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/context), +and a set of [semantic +conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions). + +### Tracer API + +[Tracer +API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md) +allows users to generate +[Spans](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span), +which represent a single operation within a trace. Spans can be nested to form a +trace tree. Each trace contains a root span, which typically describes the +entire operation and, optionally one or more sub-spans for its sub-operations. + +### Metric API + +[Metric +API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md) +allows users to capture measurements about the execution of a computer program +at runtime. The Metric API is designed to process raw measurements, generally +with the intent to produce continuous summaries of those measurements. + +## Introduction to OpenTelemetry .NET Tracer API + +.NET runtime had `Activity` class for a long time, which was meant to be used +for tracing purposes and represents the equivalent of the OpenTelemetry +[Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span). +OpenTelemetry .NET is reusing the existing `Activity` and associated classes to +represent the OpenTelemetry `Span`. This means, users can instrument their +applications/libraries to emit OpenTelemetry compatible traces by using just the +.NET Runtime. + +The `Activity` and associated classes are shipped as part of +`System.Diagnostics.DiagnosticSource` nuget package. Version 5.0.0 of this +package contains improvements to `Activity` class which makes it more closely +aligned with OpenTelemetry [API +specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md). + +Even though `Activity` enables all the scenarios OpenTelemetry supports, users +who are already familiar with OpenTelemetry terminology may find it easy to +operate with that terminology. For instance, `StartSpan` may be preferred over +`StartActivity`. To help with this transition, the OpenTelemetry.API package has +[shim](#instrumenting-a-libraryapplication-with-opentelemetryapi-shim) classes +to wrap around the .NET `Activity` classes. + +The shim exist only in the API. OpenTelemetry SDK for .NET will be operating +entirely with `Activity` only. Irrespective of whether shim classes or +`Activity` is used for instrumentation, the end result would be same. i.e +Processors/Exporters see the same data. + +## Instrumenting a library/application with .NET Activity API + +### Basic usage + +As mentioned in the introduction, the instrumentation API for OpenTelemetry .NET +is the .NET `Activity` API. Guidance for instrumenting using this API is +documented fully in the TBD(dotnet activity user guide link), but is described +here as well. + +1. Install the `System.Diagnostics.DiagnosticSource` package version + 5.0.0-preview.7.20308.13 or above to your application or library. + +```xml + + + +``` + +2. Create an `ActivitySource`, providing the name and version of the + library/application being instrumented. `ActivitySource` instance is + typically created once and is reused throughout the application/library. + +```csharp + static ActivitySource activitySource = new ActivitySource("companyname.product.library", "semver1.0.0"); +``` + The above requires import of the `System.Diagnostics` namespace. + +3. Use the `ActivitySource` instance from above to create `Activity` instances, + which represent a single operation within a trace. The parameter passed is + the `DisplayName` of the activity. + +```csharp + var activity = source.StartActivity("ActivityName"); +``` + + If there are no listeners interested in this activity, the activity above will be null. Ensure that all subsequent calls using this activity is protected with a null check. + +4. Populate activity with tags following the [OpenTelemetry semantic + conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions). + It is highly recommended to check `activity.IsAllDataRequested`, before + populating any tags which are not readily available. + +```csharp + parent?.AddTag("http.method", "GET"); + if (parent?.IsAllDataRequested ?? false) + { + parent.AddTag("http.url", "http://www.mywebsite.com"); + } +``` + +5. Perform application/library logic. + +6. Stop the activity when done. + +```csharp + activity?.Stop(); +``` + +Alternately, as `Activity` implements `IDisposable`, it can be used with a +`using` block, which ensures activity gets stopped upon disposal. This is shown +below. +```csharp + using (var activity = source.StartActivity("ActivityName") + { + parent?.AddTag("http.method", "GET"); + } // Activity gets stopped automatically at end of this block during dispose. +``` + +The above showed the basic usage of instrumenting using `Activity`. The +following sections describes more features. + +### Activity creation options + +Basic usage example above showed how `StartActivity` method can be used to start +an `Activity`. The started activity will automatically becomes the `Current` +activity. It is important to note that the `StartActivity` returns `null`, if no +listeners are interested in the activity to be created. This happens when the +final application does not enable OpenTelemetry, or when OpenTelemetry samplers +chose not to sample this activity. + +`StartActivity` has many overloads to control the activity creation. +1. `ActivityKind` + +`Activity` has a property called `ActivityKind` which represents OpenTelemetry +[SpanKind](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spankind). +The default value will be `Internal`. `StartActivity` allows passing the +`ActivityKind` while starting an `Activity`. + +```csharp + var activity = source.StartActivity("ActivityName", ActivityKind.Server); +``` + +2. Parent using `ActivityContext` + +`ActivityContext` represents the OpenTelemetry +[SpanContext](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spancontext). +While starting a new `Activity`, the currently active `Activity` is +automatically taken as the parent of the new activity being created. +`StartActivity` allows passing explicit `ActivityContext` to override this +behavior. + +```csharp + var parentContext = new ActivityContext(ActivityTraceId.CreateFromString("0af7651916cd43dd8448eb211c80319c"), ActivitySpanId.CreateFromString("b7ad6b7169203331"), ActivityTraceFlags.None); + var activity = source.StartActivity("ActivityName", ActivityKind.Server, parentContext); +``` + +As `ActivityContext` follows the [W3C +Trace-Context](https://w3c.github.io/trace-context), it is also possible to +provide the parent context as a single string matching the `traceparent` header +of the W3C Trace-Context. This is shown below. + +```csharp + var activity = source.StartActivity("ActivityName", ActivityKind.Server, "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"); +``` + +3. Initial Tags + + `Tags` in `Activity` represents the OpenTelemetry [Span + Attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-attributes). + Earlier sample showed the usage of `AddTag` method of `Activity` to add tags. + It is also possible to provide an initial set of tags during activity + creation, as shown below. + +```csharp + var initialTags = new List>(); + initialTags.Add(new KeyValuePair("tag1", "tagValue1")); + initialTags.Add(new KeyValuePair("tag2", "tagValue2")); + var activity = source.StartActivity("ActivityName", ActivityKind.Server, "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01", initialTags); +``` + +4. Activity Links + + Apart from the parent-child relation, activities can be linked using + `ActivityLinks` which represent the OpenTelemetry + [Links](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#links-between-spans). + The linked activities must be provided during the creation time, as shown + below. + +```csharp + var activityLinks = new List(); + var linkedContext1 = new ActivityContext(ActivityTraceId.CreateFromString("0af7651916cd43dd8448eb211c80319c"), ActivitySpanId.CreateFromString("b7ad6b7169203331"), ActivityTraceFlags.None); + var linkedContext2 = new ActivityContext(ActivityTraceId.CreateFromString("4bf92f3577b34da6a3ce929d0e0e4736"), ActivitySpanId.CreateFromString("00f067aa0ba902b7"), ActivityTraceFlags.Recorded); + activityLinks.Add(new ActivityLink(linkedContext1)); + activityLinks.Add(new ActivityLink(linkedContext2)); + var activity = source.StartActivity("ActivityName", ActivityKind.Server, "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01", initialTags, activityLinks); +``` + +### Adding Events + +It is possible to [add +event](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#add-events) +with `Activity` using the `AddEvent` method as shown below. + +```csharp + activity?.AddEvent(new ActivityEvent("sample activity event.")); +``` + +Apart from providing name, timestamp and attributes can be provided by using +corresponding overloads of `ActivityEvent`. + +### Setting Status + +OpenTelemetry defines a concept called +[Status](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-status) +to be associated with `Activity`. There is no `Status` class in .NET, and hence +`Status` is set to an `Activity` using the following special tags + +`ot.status_code` is the `Tag` name used to store the [Status Canonical +Code](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode). +`ot.status_description` is the `Tag` name used to store the optional +[Description](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#getdescription) + +Example: + +```csharp + activity?.AddTag("ot.status_code", "status canonical code"); + activity?.AddTag("ot.status_description", "status description"); +``` + +## Instrumenting a library/application with OpenTelemetry.API Shim + +This section to be filled after shim is shipped.