Włączanie debugera migawek dla aplikacji platformy .NET w usłudze Azure Service Fabric, usługach w chmurze i maszynach wirtualnych

Artykuł
06/13/2024

Jeśli aplikacja ASP.NET lub ASP.NET Core działa w usłudze aplikacja systemu Azure i wymaga dostosowanej konfiguracji debugera migawek lub wersji zapoznawczej platformy .NET Core, zacznij od opcji Włącz debuger migawek dla aplikacji platformy .NET w usłudze aplikacja systemu Azure Service.

Jeśli aplikacja działa w usłudze Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines lub na maszynach lokalnych, możesz pominąć włączanie debugera migawek w usłudze App Service i postępować zgodnie ze wskazówkami w tym artykule.

Zanim rozpoczniesz

Włącz usługę Application Insights w aplikacji internetowej.
Uwzględnij pakiet NuGet Microsoft.ApplicationInsights.SnapshotCollector w wersji 1.4.2 lub nowszej w aplikacji.

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET

Po dodaniu pakietu NuGet Microsoft.ApplicationInsights.SnapshotCollector do aplikacji SnapshotCollectorTelemetryProcessor element powinien zostać dodany automatycznie do TelemetryProcessors sekcji ApplicationInsights.config.

Jeśli nie widzisz SnapshotCollectorTelemetryProcessor w pliku ApplicationInsights.config lub chcesz dostosować konfigurację debugera migawek, możesz ją edytować ręcznie. Jednak te zmiany mogą zostać zastąpione w przypadku późniejszego uaktualnienia do nowszej wersji pakietu NuGet Microsoft.ApplicationInsights.SnapshotCollector .

W poniższym przykładzie przedstawiono konfigurację równoważną konfiguracji domyślnej:

<TelemetryProcessors>
  <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
    <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->
    <!-- DeveloperMode is a property on the active TelemetryChannel. -->
    <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>
    <!-- How many times we need to see an exception before we ask for snapshots. -->
    <ThresholdForSnapshotting>1</ThresholdForSnapshotting>
    <!-- The maximum number of examples we create for a single problem. -->
    <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>
    <!-- The maximum number of problems that we can be tracking at any time. -->
    <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>
    <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->
    <ReconnectInterval>00:15:00</ReconnectInterval>
    <!-- How often to reset problem counters. -->
    <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>
    <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->
    <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>
    <!-- The maximum number of snapshots allowed per day. -->
    <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>
    <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->
    <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>
    <!-- Agree to send anonymous data to Microsoft to make this product better. -->
    <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>
    <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->
    <FailedRequestLimit>3</FailedRequestLimit>
  </Add>
</TelemetryProcessors>

Migawki są zbierane tylko w przypadku wyjątków zgłoszonych w usłudze Application Insights. W niektórych przypadkach (na przykład starsze wersje platformy .NET) może być konieczne skonfigurowanie kolekcji wyjątków w celu wyświetlenia wyjątków z migawkami w portalu.

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET Core lub usług procesów roboczych

Wymagania wstępne

Aplikacja powinna już odwoływać się do jednego z następujących pakietów NuGet usługi Application Insights:

Dodawanie pakietu NuGet

Dodaj pakiet NuGet Microsoft.ApplicationInsights.SnapshotCollector do aplikacji.

Aktualizowanie kolekcji usług

W kodzie uruchamiania aplikacji, w którym są skonfigurowane usługi, dodaj wywołanie metody AddSnapshotCollector rozszerzenia. Dobrym pomysłem jest dodanie tego wiersza bezpośrednio po wywołaniu metody .AddApplicationInsightsTelemetry Na przykład:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddSnapshotCollector();

Konfigurowanie modułu zbierającego migawki

W większości sytuacji ustawienia domyślne są wystarczające. Jeśli nie, dostosuj ustawienia, dodając następujący kod przed wywołaniem metody AddSnapshotCollector()

using Microsoft.ApplicationInsights.SnapshotCollector;
...
builder.Services.Configure<SnapshotCollectorConfiguration>(builder.Configuration.GetSection("SnapshotCollector"));

Następnie dodaj sekcję SnapshotCollector do appsettings.json , w której można zastąpić wartości domyślne. W poniższym przykładzie przedstawiono konfigurację równoważną konfiguracji domyślnej:

{
  "SnapshotCollector": {
    "IsEnabledInDeveloperMode": false,
    "ThresholdForSnapshotting": 1,
    "MaximumSnapshotsRequired": 3,
    "MaximumCollectionPlanSize": 50,
    "ReconnectInterval": "00:15:00",
    "ProblemCounterResetInterval":"1.00:00:00",
    "SnapshotsPerTenMinutesLimit": 1,
    "SnapshotsPerDayLimit": 30,
    "SnapshotInLowPriorityThread": true,
    "ProvideAnonymousTelemetry": true,
    "FailedRequestLimit": 3
  }
}

Jeśli musisz ręcznie dostosować zachowanie modułu zbierającego migawki bez używania appsettings.json, użyj przeciążenia AddSnapshotCollector , które pobiera delegata. Na przykład:

builder.Services.AddSnapshotCollector(config => config.IsEnabledInDeveloperMode = true);

Konfigurowanie kolekcji migawek dla innych aplikacji platformy .NET

Migawki są zbierane tylko w przypadku wyjątków zgłaszanych w usłudze Application Insights. W przypadku aplikacji ASP.NET i ASP.NET Core zestaw SDK usługi Application Insights automatycznie zgłasza nieobsługiwane wyjątki, które unikną metody kontrolera lub procedury obsługi tras punktu końcowego. W przypadku innych aplikacji może być konieczne zmodyfikowanie kodu w celu ich raportowania. Kod obsługi wyjątków zależy od struktury aplikacji. Oto przykład:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

internal class ExampleService
{
  private readonly TelemetryClient _telemetryClient;

  public ExampleService(TelemetryClient telemetryClient)
  {
    // Obtain the TelemetryClient via dependency injection.
    _telemetryClient = telemetryClient;
  }

  public void HandleExampleRequest()
  {
    using IOperationHolder<RequestTelemetry> operation = 
        _telemetryClient.StartOperation<RequestTelemetry>("Example");
    try
    {
      // TODO: Handle the request.
      operation.Telemetry.Success = true;
    }
    catch (Exception ex)
    {
      // Report the exception to Application Insights.
      operation.Telemetry.Success = false;
      _telemetryClient.TrackException(ex);
      // TODO: Rethrow the exception if desired.
    }
  }
}

W poniższym przykładzie użyto wartości ILogger zamiast TelemetryClient. W tym przykładzie założono, że używasz dostawcy rejestratora usługi Application Insights. Jak pokazano w przykładzie, podczas obsługi wyjątku pamiętaj o przekazaniu wyjątku jako pierwszego parametru do LogError.

using Microsoft.Extensions.Logging;

internal class LoggerExample
{
  private readonly ILogger _logger;

  public LoggerExample(ILogger<LoggerExample> logger)
  {
    _logger = logger;
  }

  public void HandleExampleRequest()
  {
    using IDisposable scope = _logger.BeginScope("Example");
    try
    {
      // TODO: Handle the request
    }
    catch (Exception ex)
    {
      // Use the LogError overload with an Exception as the first parameter.
      _logger.LogError(ex, "An error occurred.");
    }
  }
}

Uwaga

Domyślnie rejestrator usługi Application Insights (ApplicationInsightsLoggerProvider) przekazuje wyjątki do debugera migawek za pomocą polecenia TelemetryClient.TrackException. To zachowanie jest kontrolowane za pośrednictwem TrackExceptionsAsExceptionTelemetry właściwości w ApplicationInsightsLoggerOptions klasie. Jeśli ustawisz wartość TrackExceptionsAsExceptionTelemetry na false podczas konfigurowania rejestratora usługi Application Insights, poprzedni przykład nie wyzwoli debugera migawek. W takim przypadku zmodyfikuj kod w celu ręcznego wywołania TrackException .