Toepassingslog Insights met .NET

In dit artikel leert u hoe u logboeken vast kunt leggen met Application Insights in .NET-apps met behulp van verschillende NuGet-pakketten:

Tip

Het Microsoft.ApplicationInsights.WorkerService NuGet-pakket valt buiten het bereik van dit artikel. Het kan worden gebruikt om application Insights in te stellen voor achtergrondservices. Zie Application Insights for Worker Service-apps voor meer informatie.

Afhankelijk van het application Insights logboekregistratiepakket dat u gebruikt, zijn er verschillende manieren om te ApplicationInsightsLoggerProvider registreren. ApplicationInsightsLoggerProvider is een implementatie van ILoggerProvider , die verantwoordelijk is voor het leveren ILogger en implementeren van ILogger<TCategoryName> .

ASP.NET Core gebruiken

Als u Application Insights-telemetrie wilt toevoegen ASP.NET Core toepassingen, gebruikt u het Microsoft.ApplicationInsights.AspNetCore NuGet-pakket. U kunt dit configureren Visual Studio als een verbonden serviceof handmatig.

Standaard hebben ASP.NET Core toepassingen een Application Insights logboekregistratieprovider geregistreerd wanneer ze zijn geconfigureerd via de code of codeloze benadering. De geregistreerde provider is geconfigureerd voor het automatisch vastleggen van logboekgebeurtenissen met een ernst van of LogLevel.Warning hoger. U kunt de ernst en categorieën aanpassen. Zie Logboekregistratieniveau voor meer informatie.

  1. Zorg ervoor dat het NuGet-pakket is geïnstalleerd:

     <ItemGroup>
         <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.17.0" />
     </ItemGroup>
    
  2. Zorg ervoor dat de Startup.ConfigureServices methode aanroept: services.AddApplicationInsightsTelemetry

    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.Http;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Hosting;
    using Microsoft.Extensions.Configuration;
    
    namespace WebApplication
    {
        public class Startup
        {
            public Startup(IConfiguration configuration)
            {
                Configuration = configuration;
            }
    
            public IConfiguration Configuration { get; }
    
            public void ConfigureServices(IServiceCollection services)
            {
                services.AddApplicationInsightsTelemetry(
                    Configuration["APPINSIGHTS_CONNECTIONSTRING"]);
    
                // An alternative overload, when not using appsettings.json or user secrets.
                // services.AddApplicationInsightsTelemetry();
            }
    
            public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
            {
                // omitted for brevity
            }
        }
    }
    

Nu het NuGet-pakket is geïnstalleerd en de provider wordt geregistreerd met afhankelijkheidsinjectie, kan de app worden geregistreerd. Met constructorinjectie is een van beide of ILogger het algemene-type alternatief ILogger<TCategoryName> vereist. Wanneer deze implementaties zijn opgelost, geeft ApplicationInsightsLoggerProvider u ze. Vastgelegde berichten of uitzonderingen worden verzonden naar Application Insights.

Kijk eens naar de volgende voorbeeldcontroller:

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Zie Logboekregistratie in ASP.NET Core.

Logboeken vastleggen in ASP.NET Core opstartcode

Voor sommige scenario's moeten logboeken worden vastleggen als onderdeel van de opstartroutine van de app, voordat de aanvraag-antwoordpijplijn gereed is om aanvragen te accepteren. Implementaties ILogger zijn echter niet eenvoudig beschikbaar via afhankelijkheidsinjectie in Program.cs en Startup.cs. Zie Logboekregistratie in .NET: Logboeken maken in Main voor meer informatie.

Er gelden enkele beperkingen wanneer u zich vanuit Program.cs en Startup.cs afmeldt:

De volgende voorbeelden laten dit zien door expliciet Program.cs en Startup.cs te instantiëren en te configureren.

Voorbeeld van Program.cs

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;

namespace WebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = CreateHostBuilder(args).Build();

            var logger = host.Services.GetRequiredService<ILogger<Program>>();
            logger.LogInformation("From Program, running the host now.");

            host.Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                })
                .ConfigureLogging((context, builder) =>
                {
                    // Providing an instrumentation key is required if you're using the
                    // standalone Microsoft.Extensions.Logging.ApplicationInsights package,
                    // or when you need to capture logs during application startup, such as
                    // in Program.cs or Startup.cs itself.
                    builder.AddApplicationInsights(
                        context.Configuration["APPINSIGHTS_CONNECTIONSTRING"]);

                    // Capture all log-level entries from Program
                    builder.AddFilter<ApplicationInsightsLoggerProvider>(
                        typeof(Program).FullName, LogLevel.Trace);

                    // Capture all log-level entries from Startup
                    builder.AddFilter<ApplicationInsightsLoggerProvider>(
                        typeof(Startup).FullName, LogLevel.Trace);
                });
    }
}

In de voorgaande code ApplicationInsightsLoggerProvider is geconfigureerd met uw "APPINSIGHTS_CONNECTIONSTRING" connection string. Filters worden toegepast, en stellen het logboekniveau in op LogLevel.Trace .

Belangrijk

U wordt aangeraden verbindingsreeksen via instrumentatiesleutels te gebruiken. Voor nieuwe Azure-regio's is het gebruik van verbindingsreeksen in plaats van instrumentatiesleutels vereist.

Een connection string identificeert de resource die u wilt koppelen aan uw telemetriegegevens. U kunt hiermee ook de eindpunten wijzigen die door uw resource worden gebruikt als bestemming voor uw telemetrie. U moet de gegevens kopiëren connection string toevoegen aan de code van uw toepassing of aan een omgevingsvariabele.

Voorbeeld van Startup.cs

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

namespace WebApplication
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddApplicationInsightsTelemetry(
                Configuration["APPINSIGHTS_CONNECTIONSTRING"]);
        }

        // The ILogger<Startup> is resolved by dependency injection
        // and available in Startup.Configure.
        public void Configure(
            IApplicationBuilder app, IWebHostEnvironment env, ILogger<Startup> logger)
        {
            logger.LogInformation(
                "Configuring for {Environment} environment",
                env.EnvironmentName);

            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseRouting();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapGet("/", async context =>
                {
                    await context.Response.WriteAsync("Hello World!");
                });
            });
        }
    }
}

Consoletoepassing

Dit zijn de geïnstalleerde pakketten:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="5.0.0" />
  <PackageReference Include="Microsoft.Extensions.Logging.ApplicationInsights" Version="2.17.0"/>
</ItemGroup>
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System;
using System.Threading.Tasks;

namespace ConsoleApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            using var channel = new InMemoryChannel();

            try
            {
                IServiceCollection services = new ServiceCollection();
                services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
                services.AddLogging(builder =>
                {
                    // Only Application Insights is registered as a logger provider
                    builder.AddApplicationInsights("<YourInstrumentationKey>");
                });

                IServiceProvider serviceProvider = services.BuildServiceProvider();
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                logger.LogInformation("Logger is working...");
            }
            finally
            {
                // Explicitly call Flush() followed by Delay, as required in console apps.
                // This ensures that even if the application terminates, telemetry is sent to the back end.
                channel.Flush();

                await Task.Delay(TimeSpan.FromMilliseconds(1000));
            }
        }
    }
}

In het voorgaande voorbeeld wordt het pakket Microsoft.Extensions.Logging.ApplicationInsights gebruikt. Deze configuratie maakt standaard gebruik van de bare minimuminstelling voor het verzenden van gegevens naar TelemetryConfiguration Application Insights: het InMemoryChannel kanaal. Er is geen steekproef en geen TelemetryInitializer standaard-instantie. U kunt dit gedrag voor een consoletoepassing overschrijven, zoals het volgende voorbeeld laat zien.

Installeer dit extra pakket:

<PackageReference Include="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel" Version="2.17.0" />

In de volgende sectie ziet u hoe u de standaardinstelling TelemetryConfiguration overschrijven met behulp van de Configure(TOptions) methode . In dit voorbeeld worden ServerTelemetryChannel steekproeven en gemaakt. Hiermee wordt een aangepast TelemetryInitializer exemplaar toegevoegd aan TelemetryConfiguration .

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System;
using System.Threading.Tasks;

namespace ConsoleApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            using var channel = new ServerTelemetryChannel();

            try
            {
                IServiceCollection services = new ServiceCollection();
                services.Configure<TelemetryConfiguration>(
                    config =>
                    {
                        config.TelemetryChannel = channel;

                        // Optional: implement your own TelemetryInitializer instance and configure it here
                        // config.TelemetryInitializers.Add(new MyTelemetryInitializer());

                        config.DefaultTelemetrySink.TelemetryProcessorChainBuilder.UseSampling(5);
                        channel.Initialize(config);
                    });

                services.AddLogging(builder =>
                {
                    // Only Application Insights is registered as a logger provider
                    builder.AddApplicationInsights("<YourInstrumentationKey>");
                });

                IServiceProvider serviceProvider = services.BuildServiceProvider();
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                logger.LogInformation("Logger is working...");
            }
            finally
            {
                // Explicitly call Flush() followed by Delay, as required in console apps.
                // This ensures that even if the application terminates, telemetry is sent to the back end.
                channel.Flush();

                await Task.Delay(TimeSpan.FromMilliseconds(1000));
            }
        }
    }
}

Niveau van logboekregistratie

ILoggerimplementaties hebben een ingebouwd mechanisme om logboekfiltering toe te passen. Met deze filtering kunt u de logboeken bepalen die naar elke geregistreerde provider worden verzonden, met inbegrip van de Application Insights provider. U kunt het filteren gebruiken in de configuratie (bijvoorbeeld met behulp van een appsettings.json-bestand) of in code.

De volgende voorbeelden laten zien hoe u filterregels kunt toepassen op ApplicationInsightsLoggerProvider .

Filterregels maken in de configuratie met appsettings.json

ApplicationInsightsLoggerProvider is een alias met de naam 'ApplicationInsights'. In de volgende sectie van appsettings.json wordt het standaardlogboekniveau van Application Insights overgenomen in logboekcategorieën die beginnen met LogLevel.Warning 'Microsoft' op niveau en LogLevel.Error hoger.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Microsoft": "Error"
      }
    }
  }
}

Filterregels in code maken

Met het volgende codefragment worden logboeken geconfigureerd die voor deze ApplicationInsightsLoggerProvider items moeten worden verzonden:

Host.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(builder =>
    {
        builder.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.Warning);
        builder.AddFilter<ApplicationInsightsLoggerProvider>("Microsoft", LogLevel.Error);
    });

Logboekbereiken

ApplicationInsightsLoggingProviderondersteunt logboekbereiken. Scopes zijn standaard ingeschakeld.

Als het bereik van het type is, wordt elk sleutel-waardepaar in de verzameling toegevoegd aan de IReadOnlyCollection<KeyValuePair<string,object>> application Insights telemetrie als aangepaste eigenschappen. In het volgende voorbeeld worden logboeken vastgelegd als TraceTelemetry en hebben ("MyKey", "MyValue") ze eigenschappen.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Als een ander type wordt gebruikt als bereik, wordt dit opgeslagen onder de eigenschap Scope in Application Insights telemetry. In het volgende voorbeeld TraceTelemetry heeft een eigenschap met de naam die het bereik Scope bevat.

    using (_logger.BeginScope("hello scope"))
    {
        _logger.LogError("An example of an Error level message");
    }

Veelgestelde vragen

Wat zijn de oude en nieuwe versies van ApplicationInsightsLoggerProvider?

De Microsoft.ApplicationInsights.AspNet SDK bevatte een ingebouwd ( ) exemplaar, dat werd ingeschakeld ApplicationInsightsLoggerProvider via Microsoft.ApplicationInsights.AspNetCore.Logging.ApplicationInsightsLoggerProvider ILoggerFactory extensiemethoden. Deze provider is gemarkeerd als verouderd in versie 2.7.1. Deze wordt volledig verwijderd bij de volgende belangrijke versiewijziging.

Het pakket Microsoft.ApplicationInsights.AspNetCore 2.6.1 zelf is niet verouderd. Dit is vereist om de bewaking van items, zoals aanvragen en afhankelijkheden, in te kunnen stellen.

Het voorgestelde alternatief is het nieuwe zelfstandige pakket Microsoft.Extensions.Logging.ApplicationInsights,dat een verbeterde instantie ( ) en extensiemethoden bevat voor het ApplicationInsightsLoggerProvider Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider ILoggerBuilder inschakelen ervan.

Microsoft.ApplicationInsights.AspNet SDK versie 2.7.1 is afhankelijk van het nieuwe pakket en schakelt automatisch vastleggen ILogger in.

Waarom worden sommige ILogger-logboeken twee keer weergegeven in Application Insights?

Duplicatie kan optreden als u de oudere (nu verouderde) versie van hebt ingeschakeld door aan te roepen ApplicationInsightsLoggerProvider AddApplicationInsights op ILoggerFactory . Controleer of uw Configure methode de volgende code heeft en verwijder deze:

 public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
 {
     loggerFactory.AddApplicationInsights(app.ApplicationServices, LogLevel.Warning);
     // ..other code.
 }

Als u dubbele logboekregistratie ervaart wanneer u fouten opsport in Visual Studio, stelt u als volgt in op in de code waarmee EnableDebugLogger false Application Insights wordt. Deze duplicatie en oplossing zijn alleen relevant wanneer u fouten in de toepassing opsport.

public void ConfigureServices(IServiceCollection services)
{
    var options = new ApplicationInsightsServiceOptions
    {
        EnableDebugLogger = false
    }
    services.AddApplicationInsightsTelemetry(options);
    // ...
}

Ik ben bijgewerkt naar Microsoft.ApplicationInsights.AspNet SDK versie 2.7.1 en logboeken van ILogger worden automatisch vastgelegd. Hoe kan ik functie volledig uitschakelen?

Zie de sectie Logboekregistratieniveau voor meer informatie over het filteren van logboeken in het algemeen. Als u wilt ApplicationInsightsLoggerProvider uitschakelen, gebruikt LogLevel.None u in uw aanroep voor het configureren van logboekregistratie. In de volgende opdracht builder is ILoggingBuilder .

builder.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);

Dit is de wijziging in het bestand appsettings.json:

{
    "Logging": {
        "ApplicationInsights": {
            "LogLevel": {
                "Default": "None"
            }
        }
    }
}

Waarom hebben sommige ILogger-logboeken niet dezelfde eigenschappen als andere?

Application Insights registreert en verzendt logboeken met behulp van dezelfde informatie die wordt gebruikt ILogger TelemetryConfiguration voor elke andere telemetrie. Maar er is een uitzondering. Is standaard niet TelemetryConfiguration volledig ingesteld wanneer u zich aanmeldt vanuit Program.cs of Startup.cs. Logboeken van deze locaties hebben niet de standaardconfiguratie, dus worden niet alle exemplaren TelemetryInitializer en TelemetryProcessor exemplaren uitgevoerd.

Ik gebruik het zelfstandige pakket Microsoft.Extensions.Logging.ApplicationInsights en ik wil handmatig enkele aanvullende aangepaste telemetrie vastleggen. Hoe doe ik dat?

Wanneer u het zelfstandige pakket gebruikt, wordt niet geïnjecteerd in de TelemetryClient afhankelijkheidsinjectiecontainer. U moet een nieuw exemplaar van maken en dezelfde configuratie gebruiken die de TelemetryClient loggerprovider gebruikt, zoals de volgende code laat zien. Dit zorgt ervoor dat dezelfde configuratie wordt gebruikt voor alle aangepaste telemetrie en telemetrie van ILogger .

public class MyController : ApiController
{
   // This TelemetryClient instance can be used to track additional telemetry through the TrackXXX() API.
   private readonly TelemetryClient _telemetryClient;
   private readonly ILogger _logger;

   public MyController(IOptions<TelemetryConfiguration> options, ILogger<MyController> logger)
   {
        _telemetryClient = new TelemetryClient(options.Value);
        _logger = logger;
   }  
}

Notitie

Als u het pakket gebruikt om Application Insights, wijzigt u deze code om Microsoft.ApplicationInsights.AspNetCore rechtstreeks in de TelemetryClient constructor te komen. Zie deze veelgestelde vragen voor een voorbeeld.

Welk toepassingstype Insights telemetrie wordt geproduceerd uit ILogger-logboeken? Waar kan ik ILogger-logboeken in Application Insights?

ApplicationInsightsLoggerProvider legt ILogger logboeken vast en maakt TraceTelemetry er van. Als een Exception object wordt doorgegeven aan de methode op , wordt gemaakt in plaats van Log ILogger ExceptionTelemetry TraceTelemetry .

Deze telemetrie-items zijn te vinden op dezelfde plaatsen als alle andere of items voor Application Insights, met inbegrip van de Azure Portal, analyse of Visual Studio lokale TraceTelemetry ExceptionTelemetry debugger.

Als u liever altijd TraceTelemetry verzendt, gebruikt u dit fragment:

builder.AddApplicationInsights(
    options => options.TrackExceptionsAsExceptionTelemetry = false);

Ik heb de SDK niet geïnstalleerd en ik gebruik de Azure Web Apps-extensie om Application Insights in te ASP.NET Core mijn toepassingen. Hoe kan ik de nieuwe provider gebruiken?

De Application Insights-extensie in Azure Web Apps de nieuwe provider. U kunt de filterregels in het bestand appsettings.json voor uw toepassing wijzigen.

Volgende stappen