open-telemetry
/
opentelemetry-dotnet
mirror of https://github.com/open-telemetry/opentelemetry-dotnet.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Basic docs (#847) 

Basic API usage doc, SDK usage doc.
This commit is contained in:
Cijo Thomas 2020-07-20 11:49:47 -07:00 committed by GitHub
parent b5a9c3a5d6
commit 00ee600fc7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 378 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -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

26
docs/instrumentation.md Normal file
View File

@ -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

90
docs/sdk-usage.md Normal file
View File

@ -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
<ItemGroup>
<PackageReference
Include="OpenTelemetry.Exporter.Console" Version="0.3.0" />
</ItemGroup>
```
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.

1
samples/Exporters/Console/TestConsoleExporter.cs
View File

@ -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;

257
src/OpenTelemetry.Api/README.md Normal file
View File

@ -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
<ItemGroup>
<PackageReference Include="System.Diagnostics.DiagnosticSource" Version="5.0.0-preview.7.20308.13" />
</ItemGroup>
```
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<KeyValuePair<string, string>>();
initialTags.Add(new KeyValuePair<string, string>("tag1", "tagValue1"));
initialTags.Add(new KeyValuePair<string, string>("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<ActivityLink>();
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.