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/)