Runtime instrumentation

.github/workflows/package-Instrumentation.Runtime.yml

@@ -0,0 +1,49 @@
+name: Pack OpenTelemetry.Contrib.Instrumentation.Runtime
+
+on:
+  workflow_dispatch:
+    inputs:
+      logLevel:
+        description: 'Log level'
+        required: true
+        default: 'warning'
+  push:
+    tags:
+      - 'Instrumentation.Runtime-*' # trigger when we create a tag with prefix "Instrumentation.Runtime-"
+
+jobs:
+  build-test-pack:
+    runs-on: ${{ matrix.os }}
+    env:
+      PROJECT: OpenTelemetry.Contrib.Instrumentation.Runtime
+
+    strategy:
+      matrix:
+        os: [windows-latest]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0 # fetching all
+
+    - name: Install dependencies
+      run: dotnet restore
+
+    - name: dotnet build ${{env.PROJECT}}
+      run: dotnet build src/${{env.PROJECT}} --configuration Release --no-restore -p:Deterministic=true
+
+    - name: dotnet test ${{env.PROJECT}}
+      run: dotnet test test/${{env.PROJECT}}.Tests
+
+    - name: dotnet pack ${{env.PROJECT}}
+      run: dotnet pack src/${{env.PROJECT}} --configuration Release --no-build
+
+    - name: Publish Artifacts
+      uses: actions/upload-artifact@v2
+      with:
+        name: ${{env.PROJECT}}-packages
+        path: '**/${{env.PROJECT}}/bin/**/*.*nupkg'
+
+    - name: Publish Nuget
+      run: |
+        nuget push **/${{env.PROJECT}}/bin/**/*.nupkg -Source https://api.nuget.org/v3/index.json -ApiKey ${{ secrets.NUGET_TOKEN }} -SymbolApiKey ${{ secrets.NUGET_TOKEN }}

.github/workflows/pr_build.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false  # ensures the entire test matrix is run, even if one permutation fails
       matrix:
         os: [windows-latest,ubuntu-latest]
-        version: [net461,netcoreapp3.1,net5.0]
+        version: [net461,netcoreapp3.1,net5.0,net6.0]
         exclude:
           - os: ubuntu-latest
             version: net461

opentelemetry-dotnet-contrib.sln

@@ -156,6 +156,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Contrib.Exten
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenTelemetry.Contrib.Extensions.PersistentStorage.Tests", "test\OpenTelemetry.Contrib.Extensions.PersistentStorage.Tests\OpenTelemetry.Contrib.Extensions.PersistentStorage.Tests.csproj", "{72EBA81D-2933-417C-8F21-D4CFFD72F530}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenTelemetry.Contrib.Instrumentation.Runtime", "src\OpenTelemetry.Contrib.Instrumentation.Runtime\OpenTelemetry.Contrib.Instrumentation.Runtime.csproj", "{F01E8C75-2791-4DBE-BD7A-5510871EBF56}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenTelemetry.Contrib.Instrumentation.Runtime.Tests", "test\OpenTelemetry.Contrib.Instrumentation.Runtime.Tests\OpenTelemetry.Contrib.Instrumentation.Runtime.Tests.csproj", "{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -305,7 +309,15 @@ Global
 		{72EBA81D-2933-417C-8F21-D4CFFD72F530}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{72EBA81D-2933-417C-8F21-D4CFFD72F530}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{72EBA81D-2933-417C-8F21-D4CFFD72F530}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{72EBA81D-2933-417C-8F21-D4CFFD72F530}.Release|Any CPU.Build.0 = Release|Any CPU
+		{72EBA81D-2933-417C-8F21-D4CFFD72F530}.Release|Any CPU.Build.0 = Release|Any CPU				
+		{F01E8C75-2791-4DBE-BD7A-5510871EBF56}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F01E8C75-2791-4DBE-BD7A-5510871EBF56}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F01E8C75-2791-4DBE-BD7A-5510871EBF56}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F01E8C75-2791-4DBE-BD7A-5510871EBF56}.Release|Any CPU.Build.0 = Release|Any CPU
+		{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -352,7 +364,9 @@ Global
 		{6B3AA3F2-89A7-433F-918A-1E5E6AAF8423} = {8D11A34C-D0EF-4DE1-8230-32168E67044D}
 		{D52558C8-B7BF-4F59-A0FA-9AA629E68012} = {2097345F-4DD3-477D-BC54-A922F9B2B402}
 		{433C59A3-D535-421E-BA7F-9BCE0D4A3D25} = {22DF5DC0-1290-4E83-A9D8-6BB7DE3B3E63}
-		{72EBA81D-2933-417C-8F21-D4CFFD72F530} = {2097345F-4DD3-477D-BC54-A922F9B2B402}
+		{72EBA81D-2933-417C-8F21-D4CFFD72F530} = {2097345F-4DD3-477D-BC54-A922F9B2B402}			
+		{F01E8C75-2791-4DBE-BD7A-5510871EBF56} = {22DF5DC0-1290-4E83-A9D8-6BB7DE3B3E63}
+		{FB907DF7-F3F3-4A07-885D-E5FECAE36BDA} = {2097345F-4DD3-477D-BC54-A922F9B2B402}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {B0816796-CDB3-47D7-8C3C-946434DE3B66}

src/OpenTelemetry.Contrib.Instrumentation.Runtime/AssemblyInfo.cs

@@ -0,0 +1,23 @@
+// <copyright file="AssemblyInfo.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System.Runtime.CompilerServices;
+
+#if SIGNED
+[assembly: InternalsVisibleTo("OpenTelemetry.Contrib.Instrumentation.Runtime.Tests, PublicKey=002400000480000094000000060200000024000052534131000400000100010051c1562a090fb0c9f391012a32198b5e5d9a60e9b80fa2d7b434c9e5ccb7259bd606e66f9660676afc6692b8cdc6793d190904551d2103b7b22fa636dcbb8208839785ba402ea08fc00c8f1500ccef28bbf599aa64ffb1e1d5dc1bf3420a3777badfe697856e9d52070a50c3ea5821c80bef17ca3acffa28f89dd413f096f898")]
+#else
+[assembly: InternalsVisibleTo("OpenTelemetry.Contrib.Instrumentation.Runtime.Tests")]
+#endif

src/OpenTelemetry.Contrib.Instrumentation.Runtime/Implementation/ServiceProviderExtensions.cs

@@ -0,0 +1,42 @@
+// <copyright file="ServiceProviderExtensions.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using Microsoft.Extensions.Options;
+
+namespace OpenTelemetry.Contrib.Instrumentation.Runtime.Implementation
+{
+    /// <summary>
+    /// Extension methods for OpenTelemetry dependency injection support.
+    /// </summary>
+    internal static class ServiceProviderExtensions
+    {
+        /// <summary>
+        /// Get options from the supplied <see cref="IServiceProvider"/>.
+        /// </summary>
+        /// <typeparam name="T">Options type.</typeparam>
+        /// <param name="serviceProvider"><see cref="IServiceProvider"/>.</param>
+        /// <returns>Options instance.</returns>
+        public static T GetOptions<T>(this IServiceProvider serviceProvider)
+            where T : class, new()
+        {
+            IOptions<T> options = (IOptions<T>)serviceProvider.GetService(typeof(IOptions<T>));
+
+            // Note: options could be null if user never invoked services.AddOptions().
+            return options?.Value ?? new T();
+        }
+    }
+}

src/OpenTelemetry.Contrib.Instrumentation.Runtime/MeterProviderBuilderExtensions.cs

@@ -0,0 +1,66 @@
+// <copyright file="MeterProviderBuilderExtensions.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using OpenTelemetry.Contrib.Instrumentation.Runtime;
+using OpenTelemetry.Contrib.Instrumentation.Runtime.Implementation;
+
+namespace OpenTelemetry.Metrics
+{
+    /// <summary>
+    /// Extension methods to simplify registering of dependency instrumentation.
+    /// </summary>
+    public static class MeterProviderBuilderExtensions
+    {
+        /// <summary>
+        /// Enables runtime instrumentation.
+        /// </summary>
+        /// <param name="builder"><see cref="MeterProviderBuilder"/> being configured.</param>
+        /// <param name="configure">Runtime metrics options.</param>
+        /// <returns>The instance of <see cref="MeterProviderBuilder"/> to chain the calls.</returns>
+        public static MeterProviderBuilder AddRuntimeMetrics(
+            this MeterProviderBuilder builder,
+            Action<RuntimeMetricsOptions> configure = null)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            if (builder is IDeferredMeterProviderBuilder deferredMeterProviderBuilder)
+            {
+                return deferredMeterProviderBuilder.Configure((sp, builder) =>
+                {
+                    AddRuntimeMetrics(builder, sp.GetOptions<RuntimeMetricsOptions>(), configure);
+                });
+            }
+
+            return AddRuntimeMetrics(builder, new RuntimeMetricsOptions(), configure);
+        }
+
+        private static MeterProviderBuilder AddRuntimeMetrics(
+            MeterProviderBuilder builder,
+            RuntimeMetricsOptions options,
+            Action<RuntimeMetricsOptions> configure)
+        {
+            configure?.Invoke(options);
+
+            var instrumentation = new RuntimeMetrics(options);
+            builder.AddMeter(RuntimeMetrics.InstrumentationName);
+            return builder.AddInstrumentation(() => instrumentation);
+        }
+    }
+}

src/OpenTelemetry.Contrib.Instrumentation.Runtime/OpenTelemetry.Contrib.Instrumentation.Runtime.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFrameworks>netcoreapp3.1;net6.0</TargetFrameworks>
+        <Description>dotnet runtime instrumentation for OpenTelemetry .NET</Description>
+        <PackageTags>$(PackageTags);OpenTelemetry;runtime</PackageTags>
+        <MinVerTagPrefix>Instrumentation.Runtime-</MinVerTagPrefix>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Microsoft.Extensions.Options" Version="2.1.1" />
+        <PackageReference Include="OpenTelemetry.Api" Version="1.2.0-rc2" />
+    </ItemGroup>
+
+</Project>

src/OpenTelemetry.Contrib.Instrumentation.Runtime/README.md

@@ -0,0 +1,87 @@
+# DotNet Runtime Instrumentation for OpenTelemetry .NET
+
+[![NuGet](https://img.shields.io/nuget/v/OpenTelemetry.Contrib.Instrumentation.Runtime.svg)](https://www.nuget.org/packages/OpenTelemetry.Contrib.Instrumentation.Runtime)
+[![NuGet](https://img.shields.io/nuget/dt/OpenTelemetry.Contrib.Instrumentation.Runtime.svg)](https://www.nuget.org/packages/OpenTelemetry.Contrib.Instrumentation.Runtime)
+
+This is an [Instrumentation
+Library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library),
+which instruments [.NET Runtime](https://docs.microsoft.com/dotnet) and
+collect telemetry about runtime behavior.
+
+## Steps to enable OpenTelemetry.Contrib.Instrumentation.Runtime
+
+### Step 1: Install Package
+
+Add a reference to the
+[`OpenTelemetry.Contrib.Instrumentation.Runtime`](https://www.nuget.org/packages/OpenTelemetry.Contrib.Instrumentation.Runtime)
+package. Also, add any other instrumentations & exporters you will need.
+
+```shell
+dotnet add package OpenTelemetry.Contrib.Instrumentation.Runtime
+```
+
+### Step 2: Enable Runtime Instrumentation at application startup
+
+Runtime instrumentation must be enabled at application startup. This is
+typically done in the `ConfigureServices` of your `Startup` class. The example
+below enables this instrumentation by using an extension method on
+`IServiceCollection`. This extension method requires adding the package
+[`OpenTelemetry.Extensions.Hosting`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Extensions.Hosting/README.md)
+to the application. This ensures the instrumentation is disposed when the host
+is shutdown.
+
+Additionally, this examples sets up the OpenTelemetry Prometheus exporter, which
+requires adding the package
+[`OpenTelemetry.Exporter.Prometheus`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Prometheus/README.md) to
+the application.
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using OpenTelemetry.Metrics;
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddOpenTelemetryMetrics((builder) => builder
+        .AddRuntimeMetrics()
+        .AddPrometheusExporter()
+    );
+}
+```
+
+Or configure directly:
+
+```csharp
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .AddRuntimeMetrics()
+    .Build();
+```
+
+## Advanced configuration
+
+By default all available runtime metrics will be added. It's also possible to
+specify only the required metrics:
+
+```csharp
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .AddRuntimeMetrics(options => options
+        .WithGc()
+        .WithThreading()
+        .WithPerformance()
+    )
+    .Build();
+```
+
+## Troubleshooting
+
+This component uses an
+[EventSource](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)
+with the name "OpenTelemetry-Instrumentation-Runtime" for its internal
+logging. Please refer to [SDK
+troubleshooting](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry#troubleshooting) for instructions on
+seeing these internal logs.
+
+## References
+
+* [Introduction to ASP.NET
+  Core](https://docs.microsoft.com/aspnet/core/introduction-to-aspnet-core)
+* [OpenTelemetry Project](https://opentelemetry.io/)