Merge branch 'main' into add-configurable-path-to-jaeger-exporter

README.md

@@ -24,7 +24,7 @@ Any exceptions to this are noted in the individual `README.md` files.
 If you are new here, please read the getting started docs:
 
 * [logs](./docs/logs/getting-started/README.md)
-* [metrics](./docs/metrics/getting-started/README.md) (experimental)
+* [metrics](./docs/metrics/getting-started/README.md)
 * [trace](./docs/trace/getting-started/README.md)
 
 This repository includes multiple installable components, available on
@@ -71,6 +71,8 @@ most common customization and extension scenarios:
   library](./docs/trace/extending-the-sdk/README.md#instrumentation-library)
 * [Building a custom log
   exporter/processor/sampler](./docs/logs/extending-the-sdk/README.md)
+* [Building a custom metrics
+  exporter/reader/exemplar](./docs/metrics/extending-the-sdk/README.md)
 * [Building a custom trace
   exporter/processor/sampler](./docs/trace/extending-the-sdk/README.md)
 
@@ -89,38 +91,30 @@ doc](https://docs.google.com/document/d/1yjjD6aBcLxlRazYrawukDgrhZMObwHARJbB9glW
 If you have trouble accessing the doc, please get in touch on
 [Slack](https://cloud-native.slack.com/archives/C01N3BC2W7Q).
 
-Approvers
-([@open-telemetry/dotnet-approvers](https://github.com/orgs/open-telemetry/teams/dotnet-approvers)):
-
-* [Bruno Garcia](https://github.com/bruno-garcia), Sentry
-* [Eddy Nakamura](https://github.com/eddynaka), Microsoft
-* [Paulo Janotti](https://github.com/pjanotti), Splunk
-* [Reiley Yang](https://github.com/reyang), Microsoft
-* [Robert Pajak](https://github.com/pellared), Splunk
-* [Utkarsh Umesan Pillai](https://github.com/utpilla), Microsoft
-
-*Find more about the approver role in [community
-repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver).*
-
-Maintainers
+[Maintainers](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer)
 ([@open-telemetry/dotnet-maintainers](https://github.com/orgs/open-telemetry/teams/dotnet-maintainers)):
 
 * [Alan West](https://github.com/alanwest), New Relic
 * [Cijo Thomas](https://github.com/cijothomas), Microsoft
-* [Mike Goldsmith](https://github.com/MikeGoldsmith), Honeycomb
 * [Mikel Blanchard](https://github.com/CodeBlanch), CoStar Group
-* [Sergey Kanzhelev](https://github.com/SergeyKanzhelev), Google
 
-*Find more about the maintainer role in [community
-repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).*
+[Approvers](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
+([@open-telemetry/dotnet-approvers](https://github.com/orgs/open-telemetry/teams/dotnet-approvers)):
 
-Triager
-([@open-telemetry/dotnet-triagers](https://github.com/orgs/open-telemetry/teams/dotnet-triagers)):
+* [Reiley Yang](https://github.com/reyang), Microsoft
+* [Robert Pająk](https://github.com/pellared), Splunk
+* [Utkarsh Umesan Pillai](https://github.com/utpilla), Microsoft
 
-* [Victor Lu](https://github.com/victlu), Microsoft
+[Emeritus
+Maintainer/Approver/Triager](https://github.com/open-telemetry/community/blob/main/community-membership.md#emeritus-maintainerapprovertriager):
 
-*Find more about the triager role in [community
-repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#triager).*
+* [Bruno Garcia](https://github.com/bruno-garcia)
+* [Eddy Nakamura](https://github.com/eddynaka)
+* [Liudmila Molkova](https://github.com/lmolkova)
+* [Mike Goldsmith](https://github.com/MikeGoldsmith)
+* [Paulo Janotti](https://github.com/pjanotti)
+* [Sergey Kanzhelev](https://github.com/SergeyKanzhelev)
+* [Victor Lu](https://github.com/victlu)
 
 ### Thanks to all the people who have contributed
 

docs/metrics/customizing-the-sdk/README.md

@@ -31,6 +31,16 @@ using OpenTelemetry.Metrics;
 using var meterProvider = Sdk.CreateMeterProviderBuilder().Build();
 ```
 
+In a typical application, a single `MeterProvider` is created at application
+startup and disposed at application shutdown. It is important to ensure that the
+provider is not disposed too early. Actual mechanism depends on the application
+type. For example, in a typical ASP.NET application, `MeterProvider` is created
+in `Application_Start`, and disposed in `Application_End` (both methods part of
+Global.asax.cs file) as shown [here](../../../examples/AspNet/Global.asax.cs). In
+a typical ASP.NET Core application, `MeterProvider` lifetime is managed by
+leveraging the built-in Dependency Injection container as shown
+[here](../../../examples/AspNetCore/Startup.cs).
+
 ## MeterProvider configuration
 
 `MeterProvider` holds the metrics configuration, which includes the following:

docs/metrics/extending-the-sdk/MyExporter.cs

@@ -35,14 +35,23 @@ public override ExportResult Export(in Batch<Metric> batch)
         using var scope = SuppressInstrumentationScope.Begin();
 
         var sb = new StringBuilder();
-        foreach (var record in batch)
+        foreach (var metric in batch)
         {
             if (sb.Length > 0)
             {
                 sb.Append(", ");
             }
 
-            sb.Append($"{record}");
+            sb.Append($"{metric.Name}");
+
+            foreach (ref readonly var metricPoint in metric.GetMetricPoints())
+            {
+                sb.Append($"{metricPoint.StartTime}");
+                foreach (var metricPointTag in metricPoint.Tags)
+                {
+                    sb.Append($"{metricPointTag.Key} {metricPointTag.Value}");
+                }
+            }
         }
 
         Console.WriteLine($"{this.name}.Export([{sb}])");

docs/metrics/extending-the-sdk/README.md

@@ -7,14 +7,68 @@
 
 ## Exporter
 
-TBD
+OpenTelemetry .NET SDK has provided the following built-in metric exporters:
+
+* [Console](../../../src/OpenTelemetry.Exporter.Console/README.md)
+* [InMemory](../../../src/OpenTelemetry.Exporter.InMemory/README.md)
+* [OpenTelemetryProtocol](../../../src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md)
+* [Prometheus](../../../src/OpenTelemetry.Exporter.Prometheus/README.md)
+
+Custom exporters can be implemented to send telemetry data to places which are
+not covered by the built-in exporters:
+
+* Exporters should derive from `OpenTelemetry.BaseExporter<Metric>` (which
+  belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package)
+  and implement the `Export` method.
+* Exporters can optionally implement the `OnShutdown` method.
+* Exporters should not throw exceptions from `Export` and
+  `OnShutdown`.
+* Exporters are responsible for any retry logic needed by the scenario. The SDK
+  does not implement any retry logic.
+* Exporters should avoid generating telemetry and causing live-loop, this can be
+  done via `OpenTelemetry.SuppressInstrumentationScope`.
+* Exporters receives a batch of `Metric`, and each `Metric`
+  can contain 1 or more `MetricPoint`s.
+* Exporters should use `Activity.TagObjects` collection instead of
+  `Activity.Tags` to obtain the full set of attributes (tags).
+* Exporters should use `ParentProvider.GetResource()` to get the `Resource`
+  associated with the provider.
+
+```csharp
+class MyExporter : BaseExporter<Metric>
+{
+    public override ExportResult Export(in Batch<Metric> batch)
+    {
+        using var scope = SuppressInstrumentationScope.Begin();
+
+        foreach (var metric in batch)
+        {
+            Console.WriteLine($"Export: {metric.metric}");
+
+            foreach (ref readonly var metricPoint in metric.GetMetricPoints())
+            {
+                Console.WriteLine($"Export: {metricPoint.StartTime}");
+            }
+        }
+
+        return ExportResult.Success;
+    }
+}
+```
+
+A demo exporter which simply writes metric name and metric point start time
+, tags to the console is shown [here](./MyExporter.cs).
+
+Apart from the exporter itself, you should also provide extension methods as
+shown [here](./MyExporterExtensions.cs). This allows users to add the Exporter
+to the `MeterProvider` as shown in the example [here](./Program.cs).
 
 ## Reader
 
-TBD
+Not supported.
 
 ## Exemplar
 
-TBD
+Not supported.
 
 ## References

docs/metrics/getting-started-prometheus-grafana/README.md

@@ -25,7 +25,7 @@ Add a reference to [Prometheus
 Exporter](../../../src/OpenTelemetry.Exporter.Prometheus/README.md):
 
 ```shell
-dotnet add package OpenTelemetry.Exporter.Prometheus --version 1.2.0-rc1
+dotnet add package OpenTelemetry.Exporter.Prometheus --version 1.2.0-rc2
 ```
 
 Now, we are going to make some small tweaks to the example in the

docs/metrics/getting-started/README.md

@@ -28,7 +28,8 @@ dotnet add package --prerelease OpenTelemetry.Exporter.Console
 Update the `Program.cs` file with the code from [Program.cs](./Program.cs):
 
 Run the application again (using `dotnet run`) and you should see the metric
-output from the console, similar to shown below:
+output from the console (metrics will be seen once the program ends),
+similar to shown below:
 
 <!-- markdownlint-disable MD013 -->
 ```text

docs/trace/customizing-the-sdk/README.md

@@ -34,6 +34,16 @@ using OpenTelemetry.Trace;
 using var tracerProvider = Sdk.CreateTracerProviderBuilder().Build();
 ```
 
+In a typical application, a single `TracerProvider` is created at application
+startup and disposed at application shutdown. It is important to ensure that the
+provider is not disposed too early. Actual mechanism depends on the application
+type. For example, in a typical ASP.NET application, `TracerProvider` is created
+in `Application_Start`, and disposed in `Application_End` (both methods part of
+Global.asax.cs file) as shown [here](../../../examples/AspNet/Global.asax.cs). In
+a typical ASP.NET Core application, `TracerProvider` lifetime is managed by
+leveraging the built-in Dependency Injection container as shown
+[here](../../../examples/AspNetCore/Startup.cs).
+
 ## TracerProvider configuration
 
 `TracerProvider` holds the tracing configuration, which includes the following:

src/OpenTelemetry.Api/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+* Improved wildcard support for `AddSource`, `AddMeter` to cover `?` (which
+ matches exactly one character).
+ ([#2875](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2875))
+
+## 1.2.0-rc2
+
+Released 2022-Feb-02
+
 * Added `ParentSpanId` to `TelemetrySpan` ([#2740](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2740))
 
 ## 1.2.0-rc1

src/OpenTelemetry.Api/README.md

@@ -19,6 +19,7 @@
   * [Setting Status](#setting-status)
 * [Instrumenting a library/application with OpenTelemetry.API
   Shim](#instrumenting-using-opentelemetryapi-shim)
+* [Troubleshooting](#troubleshooting)
 * [References](#references)
 
 ## Installation
@@ -502,6 +503,15 @@ describes more kinds of instruments.
 
 // TODO - add all instruments.
 
+## Troubleshooting
+
+This component uses an
+[EventSource](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)
+with the name "OpenTelemetry-Api" for its internal logging.
+Please refer to [SDK
+troubleshooting](../opentelemetry/README.md#troubleshooting) for instructions on
+seeing these internal logs.
+
 ## References
 
 * [OpenTelemetry Project](https://opentelemetry.io/)

src/OpenTelemetry.Exporter.Console/CHANGELOG.md

@@ -2,7 +2,12 @@
 
 ## Unreleased
 
+## 1.2.0-rc2
+
+Released 2022-Feb-02
+
 Fix MetricExporter to respect Console and Debug flags.
+Added `Activity.Links` support to `ConsoleActivityExporter`.
 
 ## 1.2.0-rc1
 

src/OpenTelemetry.Exporter.Console/ConsoleActivityExporter.cs

@@ -73,6 +73,15 @@ public override ExportResult Export(in Batch<Activity> batch)
                     }
                 }
 
+                if (activity.Links.Any())
+                {
+                    this.WriteLine("Activity.Links:");
+                    foreach (var activityLink in activity.Links)
+                    {
+                        this.WriteLine($"    {activityLink.Context.TraceId} {activityLink.Context.SpanId}");
+                    }
+                }
+
                 var resource = this.ParentProvider.GetResource();
                 if (resource != Resource.Empty)
                 {

src/OpenTelemetry.Exporter.InMemory/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.2.0-rc2
+
+Released 2022-Feb-02
+
 ## 1.2.0-rc1
 
 Released 2021-Nov-29

src/OpenTelemetry.Exporter.Jaeger/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.2.0-rc2
+
+Released 2022-Feb-02
+
 * Improved span duration's precision from millisecond to microsecond
   ([#2814](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2814))
 

src/OpenTelemetry.Exporter.Jaeger/README.md

@@ -123,6 +123,14 @@ services.AddHttpClient(
 Note: The single instance returned by `HttpClientFactory` is reused by all
 export requests.
 
+## Troubleshooting
+
+This component uses an
+[EventSource](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)
+with the name "OpenTelemetry-Exporter-Jaeger" for its internal logging. Please
+refer to [SDK troubleshooting](../opentelemetry/README.md#troubleshooting) for
+instructions on seeing these internal logs.
+
 ## References
 
 * [Jaeger](https://www.jaegertracing.io)

src/OpenTelemetry.Exporter.OpenTelemetryProtocol.Logs/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.0.0-rc9
+
+Released 2022-Feb-02
+
 ## 1.0.0-rc8
 
 Released 2021-Oct-08

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/CHANGELOG.md

@@ -1,15 +1,22 @@
 # Changelog
 
-* Changed `OtlpLogExporter` to convert `ILogger` structured log inputs to
-  `Attributes` in OpenTelemetry (only active when `ParseStateValues` is `true`
-  on `OpenTelemetryLoggerOptions`)
-
 ## Unreleased
 
+* LogExporter bug fix to handle null EventName.
+  ([#2870](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2871))
+
+## 1.2.0-rc2
+
+Released 2022-Feb-02
+
 * Added validation that insecure channel is configured correctly when using
   .NET Core 3.x for gRPC-based exporting.
   ([#2691](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2691))
 
+* Changed `OtlpLogExporter` to convert `ILogger` structured log inputs to
+  `Attributes` in OpenTelemetry (only active when `ParseStateValues` is `true`
+  on `OpenTelemetryLoggerOptions`)
+
 ## 1.2.0-rc1
 
 Released 2021-Nov-29

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/ExportClient/OtlpGrpcLogExportClient.cs

@@ -24,9 +24,9 @@ namespace OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClie
     /// <summary>Class for sending OTLP metrics export request over gRPC.</summary>
     internal sealed class OtlpGrpcLogExportClient : BaseOtlpGrpcExportClient<OtlpCollector.ExportLogsServiceRequest>
     {
-        private readonly OtlpCollector.LogsService.ILogsServiceClient logsClient;
+        private readonly OtlpCollector.LogsService.LogsServiceClient logsClient;
 
-        public OtlpGrpcLogExportClient(OtlpExporterOptions options, OtlpCollector.LogsService.ILogsServiceClient logsServiceClient = null)
+        public OtlpGrpcLogExportClient(OtlpExporterOptions options, OtlpCollector.LogsService.LogsServiceClient logsServiceClient = null)
             : base(options)
         {
             if (logsServiceClient != null)

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/ExportClient/OtlpGrpcMetricsExportClient.cs

@@ -24,9 +24,9 @@ namespace OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClie
     /// <summary>Class for sending OTLP metrics export request over gRPC.</summary>
     internal sealed class OtlpGrpcMetricsExportClient : BaseOtlpGrpcExportClient<OtlpCollector.ExportMetricsServiceRequest>
     {
-        private readonly OtlpCollector.MetricsService.IMetricsServiceClient metricsClient;
+        private readonly OtlpCollector.MetricsService.MetricsServiceClient metricsClient;
 
-        public OtlpGrpcMetricsExportClient(OtlpExporterOptions options, OtlpCollector.MetricsService.IMetricsServiceClient metricsServiceClient = null)
+        public OtlpGrpcMetricsExportClient(OtlpExporterOptions options, OtlpCollector.MetricsService.MetricsServiceClient metricsServiceClient = null)
             : base(options)
         {
             if (metricsServiceClient != null)