From bf1e2ab54cbe0778cf07be68b986fc27b543ee8b Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 25 Jul 2024 12:24:16 -0700 Subject: [PATCH 1/7] Add top-level docs showing how to initialize the OpenTelemetry SDK. --- OpenTelemetry.sln | 3 + docs/README.md | 134 ++++++++++++++++++++++++++++++++++++ src/OpenTelemetry/README.md | 72 +++++++++++-------- 3 files changed, 179 insertions(+), 30 deletions(-) create mode 100644 docs/README.md diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 61963889e01..bc131c3285e 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -123,6 +123,9 @@ EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Benchmarks", "test\Benchmarks\Benchmarks.csproj", "{DE9130A4-F30A-49D7-8834-41DE3021218B}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}" + ProjectSection(SolutionItems) = preProject + docs\README.md = docs\README.md + EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{2C7DD1DA-C229-4D9E-9AF0-BCD5CD3E4948}" ProjectSection(SolutionItems) = preProject diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..425d40fc3f7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,134 @@ +# Getting started with OpenTelemetry + +## Initialize the SDK + +There are two different common initialization styles supported by OpenTelemetry. + +### Initialize the SDK using a host + +Users building applications based on +[Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) +should utilize the +[OpenTelemetry.Extensions.Hosting](../src/OpenTelemetry.Extensions.Hosting/README.md) +package to initialize OpenTelemetry. This style provides a deep integration +between the host infrastructure (`IServiceCollection`, `IServiceProvider`, +`IConfiguration`, etc.) and OpenTelemetry. + +[AspNetCore](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host) +applications are the most common to use the hosting model but there is also a +[Generic Host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) +which may be used in console, service, and worker applications. + +> [!NOTE] +> When using `OpenTelemetry.Extensions.Hosting` only a single pipeline will be +> created for each configured signal (logging, metrics, and/or tracing). Users +> who need more granular control can create additional pipelines using the +> manual style below. + +First install the +[OpenTelemetry.Extensions.Hosting](../src/OpenTelemetry.Extensions.Hosting/README.md) +package. + +Second call the `AddOpenTelemetry` extension using the host +`IServiceCollection`: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +// Clear the default logging providers added by the host +builder.Logging.ClearProviders(); + +// Initialize OpenTelemetry +builder.Services.AddOpenTelemetry() + .ConfigureResource(resource => /* Resource configuration goes here */) + .WithLogging(logging => /* Logging configuration goes here */) + .WithMetrics(metrics => /* Metrics configuration goes here */) + .WithTracing(tracing => /* Tracing configuration goes here */)); +``` + +> [!NOTE] +> Calling `WithLogging` automatically registers the OpenTelemetry +> `ILoggerProvider` and enables `ILogger` integration. + +### Initialize the SDK manually + +Users running on .NET Framework or running without a host may initialize +OpenTelemetry manually. + +> [!IMPORTANT] +> When initializing OpenTelemetry manually make sure to ALWAYS dispose the SDK +> and/or providers when the application is shutting down. Disposing +> OpenTelemetry gives the SDK a chance to flush any telemetry held in memory. +> Skipping this step may result in data loss. + +First install the [OpenTelemetry SDK](../src/OpenTelemetry/README.md) package or +an exporter package such as +[OpenTelemetry.Exporter.OpenTelemetryProtocol](../src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md). +Exporter packages typically reference the SDK and will make it available via +transitive reference. + +Second use one of the following initialization APIs (depending on the SDK +version being used): + +#### Using 1.10.0 or newer + +The `OpenTelemetrySdk.Create` API can be used to initialize all signals off a +single root builder and supports cross-cutting extensions such as +`ConfigureResource` which configures a `Resource` to be used by all enabled +signals. An `OpenTelemetrySdk` instance is returned which may be used to access +providers for each signal. Calling `Dispose` on the returned instance will +gracefully shutdown the SDK and flush any telemetry held in memory. + +> [!NOTE] +> When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and +> `IServiceProvider` will be created for the SDK and shared by all signals. An +> `IConfiguration` is created automatically from environment variables. + +```csharp +using OpenTelemetry; + +var sdk = OpenTelemetrySdk.Create(builder => builder + .ConfigureResource(resource => /* Resource configuration goes here */) + .WithLogging(logging => /* Logging configuration goes here */) + .WithMetrics(metrics => /* Metrics configuration goes here */) + .WithTracing(tracing => /* Tracing configuration goes here */)); + +// During application shutdown +sdk.Dispose(); +``` + +To obtain an `ILogger` instance for emitting logs when using the +`OpenTelemetrySdk.Create` API call the `GetLoggerFactory` extension method using +the returned `OpenTelemetrySdk` instance: + +```csharp +var logger = sdk.GetLoggerFactory().CreateLogger() +logger.LogInformation("Application started"); +``` + +#### Using 1.9.0 or older + +The following shows how to create providers for each individual signal. Each +provider is independent and must be managed and disposed explicitly. There is no +mechanism using this style to perform cross-cutting actions across signals. + +```csharp +using Microsoft.Extensions.Logging; +using OpenTelemetry; + +var tracerProvider = Sdk.CreateTracerProviderBuilder() + /* Tracing configuration goes here */ + .Build(); + +var meterProvider = Sdk.CreateMeterProviderBuilder() + /* Metrics configuration goes here */ + .Build(); + +var loggerFactory = LoggerFactory.Create(builder => builder + .AddOpenTelemetry(options => /* Logging configuration goes here */)); + +// During application shutdown +tracerProvider.Dispose(); +meterProvider.Dispose(); +loggerFactory.Dispose(); +``` diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index 8e444a6f167..3f1b11eb969 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -5,9 +5,11 @@ * [Installation](#installation) * [Introduction](#introduction) -* [Getting started with Logging](#getting-started-with-logging) -* [Getting started with Metrics](#getting-started-with-metrics) -* [Getting started with Tracing](#getting-started-with-tracing) +* [Getting started](#getting-started) + * [Getting started with Logging](#getting-started-with-logging) + * [ILogger integration](#ilogger-integration) + * [Getting started with Metrics](#getting-started-with-metrics) + * [Getting started with Tracing](#getting-started-with-tracing) * [Troubleshooting](#troubleshooting) * [Configuration Parameters](#configuration-parameters) * [Remarks](#remarks) @@ -22,52 +24,62 @@ dotnet add package OpenTelemetry ## Introduction OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It -implements the Tracing API, the Metrics API, and the Context API. Once a valid -SDK is installed and configured, all the OpenTelemetry API methods, which were -no-ops without an SDK, will start emitting telemetry. -This SDK also supports [ILogger](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger) -integration. +implements the Logging API, Metrics API, Tracing API, Resource API, and the +Context API. Once a valid SDK is installed and configured all the OpenTelemetry +API methods, which were no-ops without an SDK, will start emitting telemetry. +This SDK also ships with an [ILogger integration](#ilogger-integration). -The SDK deals with concerns such as sampling, processing pipeline, exporting -telemetry to a particular backend etc. In most cases, users indirectly install -and enable the SDK, when they install a particular exporter. +The SDK deals with concerns such as sampling, processing pipelines (exporting +telemetry to a particular backend, etc.), metrics aggregation, and other +concerns outlined in the [OpenTelemetry +Specification](https://github.com/open-telemetry/opentelemetry-specification). +In most cases, users indirectly install and enable the SDK when they install an +exporter. -## Getting started with Logging +## Getting started -If you are new to logging, it is recommended to first follow the [getting -started in 5 minutes - Console +For general information about how to initialize the OpenTelemetry SDK see +[getting started](../../docs//README.md). + +### Getting started with Logging + +If you are new to +[logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md), +it is recommended to first follow the [getting started in 5 minutes - ASP.NET +Core Application](../../docs/logs/getting-started-aspnetcore/README.md) guide or +the [getting started in 5 minutes - Console Application](../../docs/logs/getting-started-console/README.md) guide to get up and running. -While [OpenTelemetry -logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md) -specification is an experimental signal, `ILogger` is the de-facto logging API -provided by the .NET runtime and is a stable API recommended for production use. -This repo ships an OpenTelemetry -[provider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers), -which provides the ability to enrich logs emitted with `ILogger` with -`ActivityContext`, and export them to multiple destinations, similar to tracing. -`ILogger` based API will become the OpenTelemetry .NET implementation of -OpenTelemetry logging. +For a more detailed explanation of SDK logging features see [Customizing +OpenTelemetry .NET SDK for Logs](../../docs/logs/customizing-the-sdk/README.md). -## Getting started with Metrics +#### ILogger integration + +This repo ships an +[ILoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers) +implementation which automatically enriches logs emitted using +[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) with trace +correlation information (`ActivityContext`). + +### Getting started with Metrics If you are new to -[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md), +[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md), it is recommended to first follow the [getting started in 5 minutes - ASP.NET Core Application](../../docs/metrics/getting-started-aspnetcore/README.md) guide or the [getting started in 5 minutes - Console -Application](../../docs/metrics/getting-started-console/README.md) guide to get up -and running. +Application](../../docs/metrics/getting-started-console/README.md) guide to get +up and running. For a more detailed explanation of SDK metric features see [Customizing OpenTelemetry .NET SDK for Metrics](../../docs/metrics/customizing-the-sdk/README.md). -## Getting started with Tracing +### Getting started with Tracing If you are new to -[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md), +[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md), it is recommended to first follow the [getting started in 5 minutes - ASP.NET Core Application](../../docs/trace/getting-started-aspnetcore/README.md) guide or the [getting started in 5 minutes - Console From d4ac0bc2df18c4997e97c63cf68a76e0a32724b9 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 7 Aug 2024 13:46:21 -0700 Subject: [PATCH 2/7] Doc cleanup and code review. --- README.md | 168 +++++++++++++++++++++++++----------- docs/README.md | 2 +- src/OpenTelemetry/README.md | 75 ++-------------- 3 files changed, 130 insertions(+), 115 deletions(-) diff --git a/README.md b/README.md index bf5d963e5a6..d98383129bc 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,28 @@ [![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.svg)](https://www.nuget.org/profiles/OpenTelemetry) [![Build](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-dotnet/actions/workflows/ci.yml) -The .NET [OpenTelemetry](https://opentelemetry.io/) client. +The .NET [OpenTelemetry](https://opentelemetry.io/) implementation. -## Supported .NET Versions +
+Table of Contents + +* [Supported .NET versions](#supported-net-versions) +* [Project status](#project-status) +* [Getting started](#getting-started) + * [Getting started with Logging](#getting-started-with-logging) + * [ILogger integration](#ilogger-integration) + * [Getting started with Metrics](#getting-started-with-metrics) + * [Getting started with Tracing](#getting-started-with-tracing) +* [Repository structure](#repository-structure) +* [Troubleshooting](#troubleshooting) +* [Extensibility](#extensibility) +* [Releases](#releases) +* [Contributing](#contributing) + +
+ + +## Supported .NET versions Packages shipped from this repository generally support all the officially supported versions of [.NET](https://dotnet.microsoft.com/download/dotnet) and @@ -17,7 +36,7 @@ older Windows-based .NET implementation), except `.NET Framework 3.5`. Any exceptions to this are noted in the individual `README.md` files. -## Project Status +## Project status **Stable** across all 3 signals i.e. `Logs`, `Metrics`, and `Traces`. @@ -26,27 +45,76 @@ Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/ to understand which portions of the specification has been implemented in this repo. -## Getting Started +## Getting started If you are new here, please read the getting started docs: -* [Logs](./docs/logs/README.md) -* [Metrics](./docs/metrics/README.md) -* [Traces](./docs/trace/README.md) - -This repository includes multiple installable components, available on -[NuGet](https://www.nuget.org/profiles/OpenTelemetry). Each component has its -individual `README.md` file, which covers the instruction on how to install and -how to get started. To find all the available components, please take a look at -the `src` folder. +### Getting started with Logging + +If you are new to +[logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md), +it is recommended to first follow the [getting started in 5 minutes - ASP.NET +Core Application](./docs/logs/getting-started-aspnetcore/README.md) guide or +the [getting started in 5 minutes - Console +Application](./docs/logs/getting-started-console/README.md) guide to get up +and running. + +For a more detailed explanation of SDK logging features see [Customizing +OpenTelemetry .NET SDK for Logs](./docs/logs/customizing-the-sdk/README.md). + +#### ILogger integration + +This repo ships an +[ILoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers) +implementation which automatically enriches logs emitted using +[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) with trace +correlation information (`ActivityContext`). + +### Getting started with Metrics + +If you are new to +[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md), +it is recommended to first follow the [getting started in 5 minutes - ASP.NET +Core Application](./docs/metrics/getting-started-aspnetcore/README.md) guide +or the [getting started in 5 minutes - Console +Application](./docs/metrics/getting-started-console/README.md) guide to get +up and running. + +For a more detailed explanation of SDK metric features see [Customizing +OpenTelemetry .NET SDK for +Metrics](./docs/metrics/customizing-the-sdk/README.md). + +### Getting started with Tracing + +If you are new to +[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md), +it is recommended to first follow the [getting started in 5 minutes - ASP.NET +Core Application](./docs/trace/getting-started-aspnetcore/README.md) guide +or the [getting started in 5 minutes - Console +Application](./docs/trace/getting-started-console/README.md) guide to get up +and running. + +For a more detailed explanation of SDK tracing features see [Customizing +OpenTelemetry .NET SDK for +Tracing](./docs/trace/customizing-the-sdk/README.md). + +## Repository structure + +This repository includes only what is defined in the [OpenTelemetry +Specification](https://github.com/open-telemetry/opentelemetry-specification) +and is shipped as separate packages through +[NuGet](https://www.nuget.org/profiles/OpenTelemetry). Each component has an +individual `README.md` and `CHANGELOG.md` file which covers the instructions on +how to install and get started, and details about the individual changes made +(respectively). To find all the available components, please take a look at the +`src` folder. Here are the most commonly used components: -* [OpenTelemetry .NET API](./src/OpenTelemetry.Api/README.md) -* [OpenTelemetry .NET SDK](./src/OpenTelemetry/README.md) - -[Instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -can be found in [contrib repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib). +* [OpenTelemetry API](./src/OpenTelemetry.Api/README.md) +* [OpenTelemetry SDK](./src/OpenTelemetry/README.md) +* [OpenTelemetry Hosting + Extensions](./src/OpenTelemetry.Extensions.Hosting/README.md) Here are the [exporter libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#exporter-library): @@ -59,16 +127,19 @@ libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/ma * [Prometheus HttpListener](./src/OpenTelemetry.Exporter.Prometheus.HttpListener/README.md) * [Zipkin](./src/OpenTelemetry.Exporter.Zipkin/README.md) -See the [OpenTelemetry -registry](https://opentelemetry.io/ecosystem/registry/?language=dotnet) and -[OpenTelemetry .NET Contrib -repo](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) for more -components. +Additional packages including [instrumentation +libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library), +exporters, resource detectors, and extensions can be found in +[opentelemetry-dotnet-contrib +repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) or +and/or the [OpenTelemetry +registry](https://opentelemetry.io/ecosystem/registry/?language=dotnet). ## Troubleshooting -See [Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting). -Additionally check readme file for the individual components for any additional +For general instructions see [OpenTelemetry .NET SDK > +Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting). Additionally +`README.md` files for individual components may contain more detailed troubleshooting information. ## Extensibility @@ -80,7 +151,7 @@ extension scenarios: library](./docs/trace/extending-the-sdk/README.md#instrumentation-library). * Building a custom exporter for [logs](./docs/logs/extending-the-sdk/README.md#exporter), - [metrics](./docs/metrics/extending-the-sdk/README.md#exporter) and + [metrics](./docs/metrics/extending-the-sdk/README.md#exporter), and [traces](./docs/trace/extending-the-sdk/README.md#exporter). * Building a custom processor for [logs](./docs/logs/extending-the-sdk/README.md#processor) and @@ -88,9 +159,31 @@ extension scenarios: * Building a custom sampler for [traces](./docs/trace/extending-the-sdk/README.md#sampler). +## Releases + +> [!CAUTION] +> Certain components, marked as +[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases), +are still work in progress and can undergo breaking changes before stable +release. Check the individual `README.md` file for each component to understand its +current state. + +See the [project +milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones) +for details on upcoming releases. The dates and features described in issues and +milestones are estimates, and subject to change. + +See [releases](https://github.com/open-telemetry/opentelemetry-dotnet/releases) +for information about past releases. + +Nightly builds from this repo are published to [MyGet](https://www.myget.org), +and can be installed from [this +source](https://www.myget.org/F/opentelemetry/api/v3/index.json). + ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) +For information about contributing to the project see: +[CONTRIBUTING.md](CONTRIBUTING.md). We meet weekly on Tuesdays, and the time of the meeting alternates between 9AM PT and 4PM PT. The meeting is subject to change depending on contributors' @@ -143,24 +236,3 @@ Maintainer/Approver/Triager](https://github.com/open-telemetry/community/blob/ma ### Thanks to all the people who have contributed [![contributors](https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-dotnet)](https://github.com/open-telemetry/opentelemetry-dotnet/graphs/contributors) - -## Release Schedule - -See the [project -milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones) -for details on upcoming releases. The dates and features described in issues and -milestones are estimates, and subject to change. - -See the [release -notes](https://github.com/open-telemetry/opentelemetry-dotnet/releases) for -existing releases. - -> [!CAUTION] -> Certain components, marked as -[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases), -are still work in progress and can undergo breaking changes before stable -release. Check the individual `README.md` file for each component to understand its -current state. - -Daily builds from this repo are published to MyGet, and can be installed from -[this source](https://www.myget.org/F/opentelemetry/api/v3/index.json). diff --git a/docs/README.md b/docs/README.md index 425d40fc3f7..491c120aa3a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# Getting started with OpenTelemetry +# OpenTelemetry .NET SDK ## Initialize the SDK diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index 3f1b11eb969..9a3f8285f09 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -5,14 +5,10 @@ * [Installation](#installation) * [Introduction](#introduction) -* [Getting started](#getting-started) - * [Getting started with Logging](#getting-started-with-logging) - * [ILogger integration](#ilogger-integration) - * [Getting started with Metrics](#getting-started-with-metrics) - * [Getting started with Tracing](#getting-started-with-tracing) * [Troubleshooting](#troubleshooting) - * [Configuration Parameters](#configuration-parameters) - * [Remarks](#remarks) + * [Self-diagnostics](#self-diagnostics) + * [Configuration Parameters](#configuration-parameters) + * [Remarks](#remarks) * [References](#references) ## Installation @@ -36,60 +32,6 @@ Specification](https://github.com/open-telemetry/opentelemetry-specification). In most cases, users indirectly install and enable the SDK when they install an exporter. -## Getting started - -For general information about how to initialize the OpenTelemetry SDK see -[getting started](../../docs//README.md). - -### Getting started with Logging - -If you are new to -[logging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md), -it is recommended to first follow the [getting started in 5 minutes - ASP.NET -Core Application](../../docs/logs/getting-started-aspnetcore/README.md) guide or -the [getting started in 5 minutes - Console -Application](../../docs/logs/getting-started-console/README.md) guide to get up -and running. - -For a more detailed explanation of SDK logging features see [Customizing -OpenTelemetry .NET SDK for Logs](../../docs/logs/customizing-the-sdk/README.md). - -#### ILogger integration - -This repo ships an -[ILoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers) -implementation which automatically enriches logs emitted using -[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) with trace -correlation information (`ActivityContext`). - -### Getting started with Metrics - -If you are new to -[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md), -it is recommended to first follow the [getting started in 5 minutes - ASP.NET -Core Application](../../docs/metrics/getting-started-aspnetcore/README.md) guide -or the [getting started in 5 minutes - Console -Application](../../docs/metrics/getting-started-console/README.md) guide to get -up and running. - -For a more detailed explanation of SDK metric features see [Customizing -OpenTelemetry .NET SDK for -Metrics](../../docs/metrics/customizing-the-sdk/README.md). - -### Getting started with Tracing - -If you are new to -[traces](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md), -it is recommended to first follow the [getting started in 5 minutes - ASP.NET -Core Application](../../docs/trace/getting-started-aspnetcore/README.md) guide -or the [getting started in 5 minutes - Console -Application](../../docs/trace/getting-started-console/README.md) guide to get up -and running. - -For a more detailed explanation of SDK tracing features see [Customizing -OpenTelemetry .NET SDK for -Tracing](../../docs/trace/customizing-the-sdk/README.md). - ## Troubleshooting All the components shipped from this repo uses @@ -102,9 +44,9 @@ While it is possible to view these logs using tools such as [PerfView](https://github.com/microsoft/perfview), [dotnet-trace](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-trace) etc., this SDK also ships a [self-diagnostics](#self-diagnostics) feature, which -helps troubleshooting. +helps with troubleshooting. -## Self-diagnostics +### Self-diagnostics OpenTelemetry SDK ships with built-in self-diagnostics feature. This feature, when enabled, will listen to internal logs generated by all OpenTelemetry @@ -142,7 +84,7 @@ Internally, it looks for the configuration file located in and then [AppContext.BaseDirectory](https://docs.microsoft.com/dotnet/api/system.appcontext.basedirectory). You can also find the exact directory by calling these methods from your code. -### Configuration Parameters +#### Configuration Parameters 1. `LogDirectory` is the directory where the output log file will be stored. It can be an absolute path or a relative path to the current directory. @@ -162,7 +104,7 @@ You can also find the exact directory by calling these methods from your code. higher severity levels. For example, `Warning` includes the `Error` and `Critical` levels. -### Remarks +#### Remarks A `FileSize`-KiB log file named as `ExecutableName.ProcessId.log` (e.g. `foobar.exe.12345.log`) will be generated at the specified directory @@ -185,5 +127,6 @@ start from beginning and overwrite existing text. ## References * [OpenTelemetry Project](https://opentelemetry.io/) -* [OpenTelemetry Tracing SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md) * [OpenTelemetry Logging specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md) +* [OpenTelemetry Metrics specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md) +* [OpenTelemetry Tracing specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md) From 76102c1162f0335422b20f97c8961ebd94e31542 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 7 Aug 2024 13:54:25 -0700 Subject: [PATCH 3/7] Tweaks. --- README.md | 6 ++++++ src/OpenTelemetry.Api/README.md | 6 +++++- src/OpenTelemetry/README.md | 8 ++++---- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d98383129bc..817a028f353 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ The .NET [OpenTelemetry](https://opentelemetry.io/) implementation. * [Extensibility](#extensibility) * [Releases](#releases) * [Contributing](#contributing) +* [References](#references) @@ -236,3 +237,8 @@ Maintainer/Approver/Triager](https://github.com/open-telemetry/community/blob/ma ### Thanks to all the people who have contributed [![contributors](https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-dotnet)](https://github.com/open-telemetry/opentelemetry-dotnet/graphs/contributors) + +## References + +* [OpenTelemetry Project](https://opentelemetry.io/) +* [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification) diff --git a/src/OpenTelemetry.Api/README.md b/src/OpenTelemetry.Api/README.md index 5fd769f4461..db0471e1774 100644 --- a/src/OpenTelemetry.Api/README.md +++ b/src/OpenTelemetry.Api/README.md @@ -539,4 +539,8 @@ seeing these internal logs. ## References -* [OpenTelemetry Project](https://opentelemetry.io/) +* [OpenTelemetry Baggage API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md) +* [OpenTelemetry Logs Bridge API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md) +* [OpenTelemetry Metrics API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md) +* [OpenTelemetry Propagators API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) +* [OpenTelemetry Tracing API specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md) diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index 9a3f8285f09..1dabb91a9ad 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -126,7 +126,7 @@ start from beginning and overwrite existing text. ## References -* [OpenTelemetry Project](https://opentelemetry.io/) -* [OpenTelemetry Logging specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/README.md) -* [OpenTelemetry Metrics specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/README.md) -* [OpenTelemetry Tracing specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/README.md) +* [OpenTelemetry Logging SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md) +* [OpenTelemetry Metrics SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md) +* [OpenTelemetry Tracing SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md) +* [OpenTelemetry Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) From 50ddb0534ed3204c3c23149d2daae30e95ad5e5a Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 7 Aug 2024 14:03:38 -0700 Subject: [PATCH 4/7] Tweaks. --- OpenTelemetry.sln | 3 +++ README.md | 25 ++++++++++--------------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index bc131c3285e..f48fdf47fe2 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -134,6 +134,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{2C EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "trace", "trace", "{5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}" + ProjectSection(SolutionItems) = preProject + docs\trace\README.md = docs\trace\README.md + EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "metrics", "metrics", "{3277B1C0-BDFE-4460-9B0D-D9A661FB48DB}" ProjectSection(SolutionItems) = preProject diff --git a/README.md b/README.md index 817a028f353..66bcf92bd17 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,6 @@ The .NET [OpenTelemetry](https://opentelemetry.io/) implementation. * [Project status](#project-status) * [Getting started](#getting-started) * [Getting started with Logging](#getting-started-with-logging) - * [ILogger integration](#ilogger-integration) * [Getting started with Metrics](#getting-started-with-metrics) * [Getting started with Tracing](#getting-started-with-tracing) * [Repository structure](#repository-structure) @@ -60,16 +59,10 @@ the [getting started in 5 minutes - Console Application](./docs/logs/getting-started-console/README.md) guide to get up and running. -For a more detailed explanation of SDK logging features see [Customizing -OpenTelemetry .NET SDK for Logs](./docs/logs/customizing-the-sdk/README.md). - -#### ILogger integration - -This repo ships an -[ILoggerProvider](https://docs.microsoft.com/dotnet/core/extensions/logging-providers) -implementation which automatically enriches logs emitted using -[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) with trace -correlation information (`ActivityContext`). +For general information and best practices see: [OpenTelemetry .NET +Logs](./docs/logs/README.md). For a more detailed explanation of SDK logging +features see: [Customizing OpenTelemetry .NET SDK for +Logs](./docs/logs/customizing-the-sdk/README.md). ### Getting started with Metrics @@ -81,8 +74,9 @@ or the [getting started in 5 minutes - Console Application](./docs/metrics/getting-started-console/README.md) guide to get up and running. -For a more detailed explanation of SDK metric features see [Customizing -OpenTelemetry .NET SDK for +For general information and best practices see: [OpenTelemetry .NET +Metrics](./docs/metrics/README.md). For a more detailed explanation of SDK +metric features see: [Customizing OpenTelemetry .NET SDK for Metrics](./docs/metrics/customizing-the-sdk/README.md). ### Getting started with Tracing @@ -95,8 +89,9 @@ or the [getting started in 5 minutes - Console Application](./docs/trace/getting-started-console/README.md) guide to get up and running. -For a more detailed explanation of SDK tracing features see [Customizing -OpenTelemetry .NET SDK for +For general information and best practices see: [OpenTelemetry .NET +Traces](./docs/trace/README.md). For a more detailed explanation of SDK tracing +features see: [Customizing OpenTelemetry .NET SDK for Tracing](./docs/trace/customizing-the-sdk/README.md). ## Repository structure From 3bac504c245c1e236a65111d49fbbaa9793037e9 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 7 Aug 2024 14:13:09 -0700 Subject: [PATCH 5/7] Tweaks. --- README.md | 1 - src/OpenTelemetry/README.md | 10 +++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 66bcf92bd17..c62f88cf7fc 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,6 @@ The .NET [OpenTelemetry](https://opentelemetry.io/) implementation. - ## Supported .NET versions Packages shipped from this repository generally support all the officially diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index 1dabb91a9ad..b148424893f 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -3,6 +3,9 @@ [![NuGet](https://img.shields.io/nuget/v/OpenTelemetry.svg)](https://www.nuget.org/packages/OpenTelemetry) [![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.svg)](https://www.nuget.org/packages/OpenTelemetry) +
+Table of Contents + * [Installation](#installation) * [Introduction](#introduction) * [Troubleshooting](#troubleshooting) @@ -11,6 +14,8 @@ * [Remarks](#remarks) * [References](#references) +
+ ## Installation ```shell @@ -23,7 +28,10 @@ OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It implements the Logging API, Metrics API, Tracing API, Resource API, and the Context API. Once a valid SDK is installed and configured all the OpenTelemetry API methods, which were no-ops without an SDK, will start emitting telemetry. -This SDK also ships with an [ILogger integration](#ilogger-integration). +This SDK also ships with +[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging) +integration to automatically capture and enrich logs emitted using +`Microsoft.Extensions.Logging`. The SDK deals with concerns such as sampling, processing pipelines (exporting telemetry to a particular backend, etc.), metrics aggregation, and other From 2130c94af54992417e97237bea7d3b72d302276b Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 7 Aug 2024 14:28:57 -0700 Subject: [PATCH 6/7] Tweaks. --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c62f88cf7fc..d2ea00fcf49 100644 --- a/README.md +++ b/README.md @@ -163,17 +163,21 @@ are still work in progress and can undergo breaking changes before stable release. Check the individual `README.md` file for each component to understand its current state. -See the [project -milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones) -for details on upcoming releases. The dates and features described in issues and -milestones are estimates, and subject to change. +For details about upcoming planned releases see: +[Milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones). +The dates and features described in issues and milestones are estimates and +subject to change. -See [releases](https://github.com/open-telemetry/opentelemetry-dotnet/releases) -for information about past releases. +For highlights and annoucements for stable releases see: [Release +Notes](./RELEASENOTES.md). + +To access packages, source code, and/or view a list of changes for all +components in a release see: +[Releases](https://github.com/open-telemetry/opentelemetry-dotnet/releases). Nightly builds from this repo are published to [MyGet](https://www.myget.org), -and can be installed from [this -source](https://www.myget.org/F/opentelemetry/api/v3/index.json). +and can be installed using the +`https://www.myget.org/F/opentelemetry/api/v3/index.json` source. ## Contributing From e639418cf30005a3988777c6c73e85b7503bab16 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 8 Aug 2024 10:49:20 -0700 Subject: [PATCH 7/7] Code review. --- README.md | 32 ++++++++++++++++---------------- src/OpenTelemetry/README.md | 5 +++++ 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d2ea00fcf49..db28ff6028c 100644 --- a/README.md +++ b/README.md @@ -37,12 +37,19 @@ files. ## Project status -**Stable** across all 3 signals i.e. `Logs`, `Metrics`, and `Traces`. +**Stable** across all 3 signals (`Logs`, `Metrics`, and `Traces`). -See [Spec Compliance -Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) -to understand which portions of the specification has been implemented in this -repo. +> [!CAUTION] +> Certain components, marked as +[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases), +are still work in progress and can undergo breaking changes before stable +release. Check the individual `README.md` file for each component to understand its +current state. + +To understand which portions of the [OpenTelemetry +Specification](https://github.com/open-telemetry/opentelemetry-specification) +have been implemented in OpenTelemetry .NET see: [Spec Compliance +Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md). ## Getting started @@ -124,16 +131,16 @@ libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/ma Additional packages including [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library), -exporters, resource detectors, and extensions can be found in +exporters, resource detectors, and extensions can be found in the [opentelemetry-dotnet-contrib -repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) or +repository](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) and/or the [OpenTelemetry registry](https://opentelemetry.io/ecosystem/registry/?language=dotnet). ## Troubleshooting -For general instructions see [OpenTelemetry .NET SDK > -Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting). Additionally +For general instructions see: +[Troubleshooting](./src/OpenTelemetry/README.md#troubleshooting). Additionally `README.md` files for individual components may contain more detailed troubleshooting information. @@ -156,13 +163,6 @@ extension scenarios: ## Releases -> [!CAUTION] -> Certain components, marked as -[pre-release](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#pre-releases), -are still work in progress and can undergo breaking changes before stable -release. Check the individual `README.md` file for each component to understand its -current state. - For details about upcoming planned releases see: [Milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestones). The dates and features described in issues and milestones are estimates and diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index b148424893f..e05a403f42a 100644 --- a/src/OpenTelemetry/README.md +++ b/src/OpenTelemetry/README.md @@ -40,6 +40,11 @@ Specification](https://github.com/open-telemetry/opentelemetry-specification). In most cases, users indirectly install and enable the SDK when they install an exporter. +To learn how to set up and configure the OpenTelemetry SDK see: [Getting +started](../../README.md#getting-started). For additional details about +initialization patterns see: [Initialize the +SDK](../../docs/README.md#initialize-the-sdk). + ## Troubleshooting All the components shipped from this repo uses