Merge main to release/v4

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         run: pwsh build.ps1 -RestoreOnly
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
         with:
           languages: 'csharp'
 
@@ -50,4 +50,4 @@ jobs:
           path: ${{ github.workspace }}/tests/**/*.trx
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0

.github/workflows/codeql.yml

@@ -59,7 +59,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+      uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
@@ -87,6 +87,6 @@ jobs:
         exit 1
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+      uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
       with:
         category: "/language:${{matrix.language}}"

.gitignore

@@ -352,3 +352,6 @@ __pycache__/
 # Secrets file
 appsettings.Secrets.json
 
+
+# Local, machine-specific build notes (not for public repo)
+BUILD-NOTES.local.md

README.md

@@ -24,6 +24,23 @@ Feature management provides a way to develop and expose application functionalit
 * [Blazor Server App](./examples/BlazorServerApp)
 * [ASP.NET Core Web App with Variants and Telemetry](./examples/VariantAndTelemetryDemo)
 * [ASP.NET Core Web App with Variant Service](./examples/VariantServiceDemo)
+* [ASP.NET Core Web App with Variants and OpenTelemetry](./examples/OpenTelemetryDemo)
+
+## OpenTelemetry integration
+
+`Microsoft.FeatureManagement.Telemetry.OpenTelemetry` provides feature-evaluation
+event publishing and targeting enrichment for spans and logs. Register feature
+management with `services.AddFeatureManagement()`, then call
+`AddFeatureManagementProcessors()` on the builder returned by `services.AddOpenTelemetry()`.
+The integration automatically attaches its targeting processors; applications
+configure their own providers and exporters.
+
+Register the integration before exporters, including exporters configured
+separately through logging APIs. An exporter integration with an explicit
+exporter-last guarantee may be registered in either order. This library does not
+reorder existing OpenTelemetry registrations.
+
+See the [OpenTelemetry sample](./examples/OpenTelemetryDemo) for complete setup.
 
 ## Contributing
 

build/install-dotnet.ps1

@@ -1,8 +1,28 @@
 # Installs .NET 8 and .NET 10 for CI/CD environment
 # see: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script#examples
 
+$ErrorActionPreference = "Stop"
+
 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;
 
-&([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://dot.net/v1/dotnet-install.ps1'))) -Channel 8.0
+$installScript = [scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://dot.net/v1/dotnet-install.ps1'))
+
+$channels = @("8.0", "10.0")
+
+foreach ($channel in $channels)
+{
+    & $installScript -Channel $channel
+}
+
+# Fail fast with a clear error instead of letting a silent install failure surface later as a
+# confusing "You must install or update .NET to run this application" error during test/build.
+$dotnet = & "$PSScriptRoot/resolve-dotnet.ps1"
+$installedSdks = & $dotnet --list-sdks
 
-&([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://dot.net/v1/dotnet-install.ps1'))) -Channel 10.0
+foreach ($channel in $channels)
+{
+    if (-not ($installedSdks | Select-String -Pattern "^$([regex]::Escape($channel))\."))
+    {
+        throw "Verification failed: .NET SDK for channel $channel was not found after installation. Installed SDKs:`n$installedSdks"
+    }
+}

examples/OpenTelemetryDemo/LoggerExtensions.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Microsoft.Extensions.Logging;
+
+namespace OpenTelemetryDemo
+{
+    /// <summary>
+    /// High-performance, source-generator-style logging (<see cref="LoggerMessage.Define"/>) for
+    /// this app's custom events. Each event's message template includes the
+    /// "microsoft.custom_event.name" placeholder, which becomes a `LogRecord` attribute that the
+    /// Azure Monitor OpenTelemetry Exporter (if configured) uses to classify the log as a custom
+    /// event in Application Insights, rather than a plain trace.
+    /// </summary>
+    public static class LoggerExtensions
+    {
+        private const string AzureMonitorCustomEventNameKey = "microsoft.custom_event.name";
+
+        private static readonly Action<ILogger, string, int, Exception> _vote = LoggerMessage.Define<string, int>(
+            LogLevel.Information,
+            new EventId(1, AzureMonitorCustomEventNameKey),
+            "{" + AzureMonitorCustomEventNameKey + "} {ImageRating}");
+
+        private static readonly Action<ILogger, string, string, long, Exception> _checkout = LoggerMessage.Define<string, string, long>(
+            LogLevel.Information,
+            new EventId(2, AzureMonitorCustomEventNameKey),
+            "{" + AzureMonitorCustomEventNameKey + "} {success} {checkoutAmount}");
+
+        public static void LogVote(this ILogger logger, int rating)
+        {
+            _vote(logger, "Vote", rating, null);
+        }
+
+        public static void LogCheckout(this ILogger logger, long amount)
+        {
+            _checkout(logger, "checkout", "yes", amount, null);
+        }
+    }
+}

examples/OpenTelemetryDemo/OpenTelemetryDemo.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" Version="1.6.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.FeatureManagement.AspNetCore\Microsoft.FeatureManagement.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\src\Microsoft.FeatureManagement.Telemetry.OpenTelemetry\Microsoft.FeatureManagement.Telemetry.OpenTelemetry.csproj" />
+  </ItemGroup>
+
+</Project>

examples/OpenTelemetryDemo/Pages/Checkout.cshtml

@@ -0,0 +1,20 @@
+@page
+@model CheckoutModel
+@{
+    ViewData["Title"] = "Checkout";
+}
+<h1>@ViewData["Title"]</h1>
+
+<p>Click Below To Check Out!</p>
+
+<form method="post">
+    @Html.AntiForgeryToken()
+    <button id="checkout" name="checkout" type="submit" class="btn btn-primary btn-sm">
+        Check Out
+    </button>
+</form>
+
+@if (Model.CheckedOut)
+{
+    <p class="mt-3">Checked Out! Amount: @Model.CheckoutAmount</p>
+}

examples/OpenTelemetryDemo/Pages/Checkout.cshtml.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using System.Diagnostics.Metrics;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+using Microsoft.Extensions.Logging;
+
+namespace OpenTelemetryDemo.Pages
+{
+    public class CheckoutModel : PageModel
+    {
+        private readonly Meter _meter;
+        private readonly Histogram<long> _checkoutAmountHistogram;
+        private readonly ILogger<CheckoutModel> _logger;
+
+        public CheckoutModel(IMeterFactory meterFactory, ILogger<CheckoutModel> logger)
+        {
+            _meter = meterFactory?.Create("OpenTelemetryDemo") ?? throw new ArgumentNullException(nameof(meterFactory));
+            _checkoutAmountHistogram = _meter.CreateHistogram<long>("checkoutAmount");
+            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        }
+
+        public bool CheckedOut { get; set; }
+
+        public int CheckoutAmount { get; set; }
+
+        public void OnPost()
+        {
+            CheckoutAmount = Random.Shared.Next(1, 100);
+
+            //
+            // Track the checkout amount metric using the OpenTelemetry metrics API
+            // (System.Diagnostics.Metrics), exported via WithMetrics/AddMeter.
+            _checkoutAmountHistogram.Record(CheckoutAmount);
+
+            //
+            // Emits a log-based custom event, the OpenTelemetry equivalent of
+            // TelemetryClient.TrackEvent.
+            _logger.LogCheckout(CheckoutAmount);
+
+            CheckedOut = true;
+        }
+    }
+}

examples/OpenTelemetryDemo/Pages/Error.cshtml

@@ -0,0 +1,26 @@
+@page
+@model ErrorModel
+@{
+    ViewData["Title"] = "Error";
+}
+
+<h1 class="text-danger">Error.</h1>
+<h2 class="text-danger">An error occurred while processing your request.</h2>
+
+@if (Model.ShowRequestId)
+{
+    <p>
+        <strong>Request ID:</strong> <code>@Model.RequestId</code>
+    </p>
+}
+
+<h3>Development Mode</h3>
+<p>
+    Swapping to the <strong>Development</strong> environment displays detailed information about the error that occurred.
+</p>
+<p>
+    <strong>The Development environment shouldn't be enabled for deployed applications.</strong>
+    It can result in displaying sensitive information from exceptions to end users.
+    For local debugging, enable the <strong>Development</strong> environment by setting the <strong>ASPNETCORE_ENVIRONMENT</strong> environment variable to <strong>Development</strong>
+    and restarting the app.
+</p>

examples/OpenTelemetryDemo/Pages/Error.cshtml.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+using System.Diagnostics;
+
+namespace OpenTelemetryDemo.Pages
+{
+    [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
+    [IgnoreAntiforgeryToken]
+    public class ErrorModel : PageModel
+    {
+        public string RequestId { get; set; }
+
+        public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
+
+        private readonly ILogger<ErrorModel> _logger;
+
+        public ErrorModel(ILogger<ErrorModel> logger)
+        {
+            _logger = logger;
+        }
+
+        public void OnGet()
+        {
+            RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
+        }
+    }
+}

examples/OpenTelemetryDemo/Pages/Index.cshtml

@@ -0,0 +1,72 @@
+@page
+@model IndexModel
+@{
+    ViewData["Title"] = "Home page";
+}
+
+<div class="text-center mb-40">
+    <h1 class="display-4">Welcome, @Model.Username !</h1>
+</div>
+
+<div class="text-center">
+    <div style="display:inline-block;width:500px;">
+        <img class="mb-40" src="@ViewData["ImageUri"]" alt="Dinosaur selected by the ImageRating feature" />
+        <div class="panel panel-primary">
+            <div class="panel-heading">
+                <h3 class="panel-title">
+                    <span class="glyphicon glyphicon-arrow-right"></span>Rate the image on a scale of 1 - 5 !<span class="glyphicon glyphicon-new-window"></span>
+                </h3>
+            </div>
+            <form action="/" method="post">
+                <div class="panel-body mb-5">
+                    <ul class="list-group">
+                        <li class="list-group-item">
+                            <div class="radio">
+                                <label>
+                                    <input type="radio" name="imageScore" value="5">
+                                    5
+                                </label>
+                            </div>
+                        </li>
+                        <li class="list-group-item">
+                            <div class="radio">
+                                <label>
+                                    <input type="radio" name="imageScore" value="4">
+                                    4
+                                </label>
+                            </div>
+                        </li>
+                        <li class="list-group-item">
+                            <div class="radio">
+                                <label>
+                                    <input type="radio" name="imageScore" value="3">
+                                    3
+                                </label>
+                            </div>
+                        </li>
+                        <li class="list-group-item">
+                            <div class="radio">
+                                <label>
+                                    <input type="radio" name="imageScore" value="2">
+                                    2
+                                </label>
+                            </div>
+                        </li>
+                        <li class="list-group-item">
+                            <div class="radio">
+                                <label>
+                                    <input type="radio" name="imageScore" value="1">
+                                    1
+                                </label>
+                            </div>
+                        </li>
+                    </ul>
+                </div>
+                @Html.AntiForgeryToken()
+                <div class="panel-footer">
+                    <input type="submit" class="btn btn-primary btn-sm" value="Vote" />
+                </div>
+            </form>
+        </div>
+    </div>
+</div>