From 8159df11781ef795f01d87dc964f46d3a1126667 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Wed, 6 Oct 2021 11:28:20 -0700 Subject: [PATCH] Add basic docs for Metrics api and sdk (#2452) --- docs/metrics/customizing-the-sdk/README.md | 68 +++++++++++++++++---- src/OpenTelemetry.Api/README.md | 69 ++++++++++++++++++++++ 2 files changed, 124 insertions(+), 13 deletions(-) diff --git a/docs/metrics/customizing-the-sdk/README.md b/docs/metrics/customizing-the-sdk/README.md index cb5555f714f..31db829a581 100644 --- a/docs/metrics/customizing-the-sdk/README.md +++ b/docs/metrics/customizing-the-sdk/README.md @@ -5,25 +5,25 @@ As shown in the [getting-started](../getting-started/README.md) doc, a valid [`MeterProvider`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#meterprovider) must be configured and built to collect metrics with OpenTelemetry .NET Sdk. -`MeterProvider` holds all the configuration for tracing like metricreaders, -views, etc. Naturally, almost all the customizations must be done on the +`MeterProvider` holds all the configuration for metrics like MetricReaders, +Views, etc. Naturally, almost all the customizations must be done on the `MeterProvider`. ## Building a MeterProvider Building a `MeterProvider` is done using `MeterProviderBuilder` which must be obtained by calling `Sdk.CreateMeterProviderBuilder()`. `MeterProviderBuilder` -exposes various methods which configures the provider it is going to build. These -includes methods like `AddSource`, `AddView` etc, and are explained in +exposes various methods which configure the provider it is going to build. +These include methods like `AddMeter`, `AddView` etc, and are explained in subsequent sections of this document. Once configuration is done, calling `Build()` on the `MeterProviderBuilder` builds the `MeterProvider` instance. -Once built, changes to its configuration is not allowed. In most cases, -a single `MeterProvider` is created at the application startup, -and is disposed when application shuts down. +Once built, changes to its configuration is not allowed. In most cases, a single +`MeterProvider` is created at the application startup, and is disposed when +application shuts down. -The snippet below shows how to build a basic `MeterProvider`. 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 `MeterProvider`. This will create a +provider with default configuration, and is not particularly useful. The +subsequent sections show how to build a more useful provider. ```csharp using OpenTelemetry; @@ -36,9 +36,10 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder().Build(); `MeterProvider` holds the metrics configuration, which includes the following: -1. The list of `Meter`s from which measurements are collected. +1. The list of `Meter`s from which instruments are created to report + measurements. 2. The list of instrumentations enabled via - [InstrumentationLibrary](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library). + [Instrumentation Library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library). 3. The list of [MetricReaders](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#metricreader), including exporting readers which exports metrics to @@ -52,7 +53,48 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder().Build(); ### Meter -// TODO +[`Meter`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#meter) +is used for creating +[`Instruments`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument), +which are then used to report +[Measurements](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#measurement). +The SDK follows an explicit opt-in model for listening to meters. i.e, by +default, it listens to no meters. Every meter which is used to create +instruments must be explicitly added to the meter provider. + +`AddMeter` method on `MeterProviderBuilder` can be used to add a `Meter` to the +provider. The name of the `Meter` (case-insensitive) must be provided as an +argument to this method. `AddMeter` can be called multiple times to add more +than one meters. It also supports wild-card subscription model. + +It is **not** possible to add meters *once* the provider is built by the +`Build()` method on the `MeterProviderBuilder`. + +The snippet below shows how to add meters to the provider. + +```csharp +using OpenTelemetry; +using OpenTelemetry.Metrics; + +using var meterProvider = Sdk.CreateMeterProviderBuilder() + // The following enables instruments from Meter + // named "MyCompany.MyProduct.MyLibrary" only. + .AddMeter("MyCompany.MyProduct.MyLibrary") + // The following enables instruments from all Meters + // whose name starts with "AbcCompany.XyzProduct.". + .AddMeter("AbcCompany.XyzProduct.*") + .Build(); +``` + +See [Program.cs](./Program.cs) for complete example. + +**Note:** +A common mistake while configuring `MeterProvider` is forgetting to add the +required `Meter`s to the provider. It is recommended to leverage the wildcard +subscription model where it makes sense. For example, if your application is +expecting to enable instruments from a number of libraries from a company "Abc", +the you can use `AddMeter("Abc.*")` to enable all meters whose name starts with +"Abc.". ### View diff --git a/src/OpenTelemetry.Api/README.md b/src/OpenTelemetry.Api/README.md index f324249d0b3..eb2d6f82896 100644 --- a/src/OpenTelemetry.Api/README.md +++ b/src/OpenTelemetry.Api/README.md @@ -434,6 +434,75 @@ and [extract](../../examples/MicroserviceExample/Utils/Messaging/MessageReceiver.cs) context. +## Introduction to OpenTelemetry .NET Metrics API + +Metrics in OpenTelemetry .NET are a somewhat unique implementation of the +OpenTelemetry project, as the Metrics API is incorporated directly into the .NET +runtime itself, as part of the +[`System.Diagnostics.DiagnosticSource`](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/6.0.0-rc.1.21451.13) +package. This means, users can instrument their applications/libraries to emit +metrics by simply using the `System.Diagnostics.DiagnosticSource` package. This +package can be used in applications targeting any of the officially supported +versions of [.NET Core](https://dotnet.microsoft.com/download/dotnet-core), and +[.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework) except +for versions lower than `.NET Framework 4.6.1`. + +## Instrumenting a library/application with .NET Metrics API + +### Basic metric usage + +1. Install the `System.Diagnostics.DiagnosticSource` package version + `6.0.0-rc.1.21451.13` or above to your application or library. + + ```xml + + + + ``` + +2. Create a `Meter`, providing the name and version of the library/application + doing the instrumentation. The `Meter` instance is typically created once and + is reused throughout the application/library. + + ```csharp + static Meter meter = new Meter( + "companyname.product.instrumentationlibrary", + "semver1.0.0"); + ``` + + The above requires import of the `System.Diagnostics.Metrics` namespace. + + **Note:** + It is important to note that `Meter` instances are created by using its + constructor, and *not* by calling a `GetMeter` method on the + `MeterProvider`. This is an important distinction from the [OpenTelemetry + specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter), + where `Meter`s are obtained from `MeterProvider`. + +3. Use the `Meter` instance from above to create instruments, which can be used + to report measurements. Just like meter instances, the instrument instances + are to be created once and reused throughout the application/library. + + ```csharp + static Counter MyFruitCounter = meter.CreateCounter("MyFruitCounter"); + ``` + +4. Use the instruments to report measurements, along with the attributes. + + ```csharp + MyFruitCounter.Add(1, new("name", "apple"), new("color", "red")); + ``` + +The above showed the usage of a `Counter` instrument. The following sections +describes more kinds of instruments. + +### Instrument types + +// TODO - add all instruments. + ## References * [OpenTelemetry Project](https://opentelemetry.io/)