Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More doc tweaks #3805

Merged
merged 6 commits into from
Oct 22, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/trace/customizing-the-sdk/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

namespace CustomizingTheSdk;
Expand All @@ -36,7 +37,7 @@ public class Program

public static void Main()
{
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
var tracerProvider = Sdk.CreateTracerProviderBuilder()

// The following adds subscription to activities from Activity Source
// named "MyCompany.MyProduct.MyLibrary" only.
Expand All @@ -45,6 +46,8 @@ public static void Main()
// The following adds subscription to activities from all Activity Sources
// whose name starts with "AbcCompany.XyzProduct.".
.AddSource("AbcCompany.XyzProduct.*")
.ConfigureResource(resourceBuilder => resourceBuilder.AddTelemetrySdk())
.ConfigureResource(r => r.AddService("MyServiceName"))
.AddConsoleExporter()
.Build();

Expand Down Expand Up @@ -76,5 +79,7 @@ public static void Main()
activity?.SetTag("foo", 1);
activity?.SetTag("bar", "Hello, World!");
}

tracerProvider.Dispose();
}
}
59 changes: 41 additions & 18 deletions docs/trace/customizing-the-sdk/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Customizing OpenTelemetry .NET SDK

**This doc is work-in-progress.**

## TracerProvider

As shown in the [getting-started](../getting-started/README.md) doc, a valid
Expand All @@ -23,15 +21,21 @@ Once built, changes to its configuration is not allowed, with the exception of
adding more processors. In most cases, a single `TracerProvider` is created at
the application startup, and is disposed when application shuts down.

The snippet below shows how to build a basic `TracerProvider`. This will create
a provider with default configuration, and is not particularly useful. The
subsequent sections shows how to build a more useful provider.
The snippet below shows how to build a basic `TracerProvider` and dispose it at
the end of the application. This will create a provider with default
configuration, and is not particularly useful. The subsequent sections shows how
to build a more useful provider.

```csharp
using OpenTelemetry;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder().Build();
var tracerProvider = Sdk.CreateTracerProviderBuilder().Build();
// ....

// Dispose at application shutdown
tracerProvider.Dispose()

```

In a typical application, a single `TracerProvider` is created at application
Expand Down Expand Up @@ -67,7 +71,7 @@ leveraging the built-in Dependency Injection container as shown

`ActivitySource` denotes a
[`Tracer`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer),
which is used to start activities. The SDK follows an explicit opt-in model for
which is used to create activities. The SDK follows an explicit opt-in model for
listening to activity sources. i.e, by default, it listens to no sources. Every
activity source which produce telemetry must be explicitly added to the tracer
provider to start collecting traces from them.
Expand All @@ -87,7 +91,7 @@ The snippet below shows how to add activity sources to the provider.
using OpenTelemetry;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
var tracerProvider = Sdk.CreateTracerProviderBuilder()
// The following subscribes to activities from Activity Source
// named "MyCompany.MyProduct.MyLibrary" only.
.AddSource("MyCompany.MyProduct.MyLibrary")
Expand Down Expand Up @@ -142,7 +146,7 @@ it is built.
using OpenTelemetry;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
var tracerProvider = Sdk.CreateTracerProviderBuilder()
utpilla marked this conversation as resolved.
Show resolved Hide resolved
.AddProcessor(new MyProcessor1())
.AddProcessor(new MyProcessor2()))
.Build();
Expand Down Expand Up @@ -206,13 +210,24 @@ is the immutable representation of the entity producing the telemetry. If no
resource is used to indicate the
[Service](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service).
The `ConfigureResource` method on `TracerProviderBuilder` can be used to
configure the resource on the provider. When the provider is built, it
automatically builds the final `Resource` from the configured `ResourceBuilder`.
There can only be a single `Resource` associated with a
provider. It is not possible to change the resource builder *after* the provider
is built, by calling the `Build()` method on the `TracerProviderBuilder`.
configure the resource on the provider. `ConfigureResource` accepts an `Action`
to configure the `ResourceBuilder`. Multiple calls to `ConfigureResource` can be
made. When the provider is built, it builds the final `Resource` combining all
the `ConfigureResource` calls. There can only be a single `Resource` associated
with a provider. It is not possible to change the resource builder *after* the
provider is built, by calling the `Build()` method on the
`TracerProviderBuilder`.

`ResourceBuilder` offers various methods to construct resource comprising of
multiple attributes from various sources.
multiple attributes from various sources. Examples include `AddTelemetrySdk()`
which adds [Telemetry
Sdk](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#telemetry-sdk)
resource, and `AddService()` which adds
[Service](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service)
resource. It also allows adding `ResourceDetector`s.

Follow [this](../extending-the-sdk/README.md#resource-detector) document
to learn about how to write own resource detectors.

The snippet below shows configuring the `Resource` associated with the provider.

Expand All @@ -221,8 +236,9 @@ using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.ConfigureResource(r => r.AddService("MyServiceName"))
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.ConfigureResource(resourceBuilder => resourceBuilder.AddTelemetrySdk())
.ConfigureResource(resourceBuilder => resourceBuilder.AddService("service-name"))
.Build();
```

Expand Down Expand Up @@ -252,12 +268,19 @@ The snippet below shows configuring a custom sampler to the provider.
using OpenTelemetry;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetSampler(new TraceIdRatioBasedSampler(0.25))
.Build();
```

Follow [this](../extending-the-sdk/README.md#sampler) document
to learn about how to write own samplers.

## Context Propagation

// TODO: OpenTelemetry Sdk contents about Context. // TODO: Links to built-in
instrumentations doing Propagation.

## Configuration using Dependency Injection

// TODO: Placeholder
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@CodeBlanch This is all yours!