Övervaka .NET-program och -tjänster med Application Insights (klassiskt API)

Den här artikeln beskriver hur du aktiverar och konfigurerar Application Insights för ASP.NET-, ASP.NET Core- och Worker Service-program (icke-HTTP). Application Insights kan samla in följande telemetri från dina appar:

Scenarier som stöds

Lägga till Application Insights

Förutsättningar

Skapa ett grundläggande webbprogram

Om du inte har något fungerande webbprogram än kan du använda följande vägledning för att skapa ett.

Lägg till Application Insights automatiskt (Visual Studio)

Det här avsnittet vägleder dig genom att automatiskt lägga till Application Insights i en mallbaserad webbapp.

Lägg till Application Insights manuellt (ingen Visual Studio)

Det här avsnittet vägleder dig genom att lägga till Application Insights manuellt i en mallbaserad webbapp.

Kontrollera att Application Insights tar emot telemetri

Konfigurera telemetri

I det här avsnittet

• Live-mått
• Spårningar (loggar)
• Distribuerad spårning
• Beroenden
• undantag
• Anpassade mått
• Anpassade åtgärder

Livemått

Live-mätvärden kan användas för att snabbt kontrollera om programövervakning via Application Insights är korrekt konfigurerad. Det kan ta några minuter innan telemetri visas i Azure Portal, men fönstret livemått visar CPU-användningen i den körande processen i nästan realtid. Den kan också visa andra telemetrier som begäranden, beroenden och spårningar.

Aktivera livemått med hjälp av kod för alla .NET-program

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

            // Secure the control channel.
            // This is optional, but recommended.
            quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
            quickPulseModule.Initialize(config);
            quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

            // Create a TelemetryClient instance. It is important
            // to use the same TelemetryConfiguration here as the one
            // used to set up live metrics.
            TelemetryClient client = new TelemetryClient(config);

            // This sample runs indefinitely. Replace with actual application logic.
            while (true)
            {
                // Send dependency and request telemetry.
                // These will be shown in live metrics.
                // CPU/Memory Performance counter is also shown
                // automatically without any additional steps.
                client.TrackDependency("My dependency", "target", "http://sample",
                    DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
                client.TrackRequest("My Request", DateTimeOffset.Now,
                    TimeSpan.FromMilliseconds(230), "200", true);
                Task.Delay(1000).Wait();
            }
        }
    }
}

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Spårningar (loggar)

I det här avsnittet beskrivs hur du skickar loggar för diagnostisk spårning från ASP.NET eller ASP.NET Core-program till Application Insights och sedan utforskar/söker efter loggarna i portalen.

Du kan använda spårningsloggar för att identifiera spårningar som är associerade med varje användarbegäran och korrelera dem med andra händelser och undantagsrapporter.

Application Insights samlar in loggar från ASP.NET Core och andra .NET-appar via ILogger och från klassiska ASP.NET (.NET Framework) via det klassiska SDK:t och korten.

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Manuell installation

Använd den här metoden om projekttypen inte stöds av Installationsprogrammet för Application Insights (till exempel vissa skrivbords-/konsolscenarier) eller om du föredrar explicit kontroll på paketnivå.

1. Högerklicka på projektet i Solution Explorer och välj Hantera NuGet-paket.

2. Sök efter Application Insights.

3. Välj något av följande paket:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListener
   • log4net: Microsoft.ApplicationInsights.Log4NetAppender
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Banderoll för Microsoft.ApplicationInsights.EventSourceListener
   • Microsoft.ApplicationInsights.DiagnosticSourceListener
   • Microsoft.ApplicationInsights.EtwCollector

NuGet-paketet installerar nödvändiga sammansättningar och ändrar web.config eller app.config, om tillämpligt.

Installationsinstruktioner:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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" };
    }
}

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

    logger.Warn("Slow response - database01");

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Använd spårnings-API:et direkt

Du kan anropa Application Insights-spårnings-API:et direkt. Loggningsadaptrarna använder det här API:t. Till exempel:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

En fördel TrackTrace med är att du kan placera relativt långa data i meddelandet. Du kan till exempel koda POST-data där.

Du kan också lägga till en allvarlighetsgrad i meddelandet. Och precis som andra telemetrier kan du lägga till egenskapsvärden för att filtrera eller söka efter olika uppsättningar spårningar. Till exempel:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

Nu kan du enkelt filtrera bort alla meddelanden på en viss allvarlighetsnivå som är relaterade till en viss databas i Transaktionssökning .

Konsolprogram

Om du vill lägga till Application Insights-loggning i konsolprogram installerar du först följande NuGet-paket:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

I följande exempel används Microsoft.Extensions.Logging.ApplicationInsights paketet och standardbeteendet för ett konsolprogram visas. Paketet Microsoft.Extensions.Logging.ApplicationInsights ska användas i ett konsolprogram eller när du vill ha en minimal implementering av Application Insights utan den fullständiga funktionsuppsättningen, till exempel mått, distribuerad spårning, sampling och telemetriinitierare.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

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(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    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));
}

Mer information finns i Vilken Application Insights-telemetrityp skapas från ILogger-loggar? Var kan jag se ILogger-loggar i Application Insights?.

Loggningsomfång

ApplicationInsightsLoggingProvider stöder loggomfattningar som är aktiverade som standard.

Om omfånget är av typen IReadOnlyCollection<KeyValuePair<string,object>>läggs varje nyckel/värde-par i samlingen till i Application Insights-telemetrin som anpassade egenskaper. I följande exempel registreras loggar som TraceTelemetry och har ("MyKey", "MyValue") i egenskaper.

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

Om någon annan typ används som omfång lagras den under egenskapen Scope i Application Insights-telemetri. I följande exempel TraceTelemetry har en egenskap som heter Scope som innehåller omfånget.

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

Hitta loggarna

Kör appen i felsökningsläge eller distribuera den live.

Utforska i transaktionssökning

I appens översiktsfönster i Application Insights-portalen väljer du Transaktionssökning där du kan:

• Filtrera på loggspårningar eller på objekt med specifika egenskaper.
• Granska ett specifikt objekt i detalj.
• Hitta andra systemloggdata som relaterar till samma användarbegäran (har samma åtgärds-ID).
• Spara konfigurationen av en sida som en favorit.

Utforska i Azure Monitor-loggar

ILogger-loggar visas som spårningstelemetri (tabell traces i Application Insights och AppTraces Log Analytics).

Exempel

I Azure-portalen går du till Application Insights och kör:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Distribuerad spårning

Moderna moln - och mikrotjänstarkitekturer har aktiverat enkla, oberoende distributionsbara tjänster som minskar kostnaderna samtidigt som tillgängligheten och dataflödet ökar. Det har dock gjort det svårare att resonera kring och felsöka övergripande system. Distribuerad spårning löser det här problemet genom att tillhandahålla en prestandaprofilerare som fungerar som anropsstackar för moln- och mikrotjänstarkitekturer.

Azure Monitor tillhandahåller två funktioner för användning av distribuerade spårningsdata: transaktionsdiagnostikvyn för en enskild transaktion/begäran och programkartvyn för att visa hur system interagerar.

Application Insights kan övervaka varje komponent separat och identifiera vilken komponent som är ansvarig för fel eller prestandaförsämring med hjälp av distribuerad telemetrikorrelation. Den här artikeln förklarar datamodellen, tekniker för kontextspridning, protokoll och implementering av korrelationstaktik på olika språk och plattformar som används av Application Insights.

Aktivera distribuerad spårning via Application Insights med autoinstrumentation eller SDK:er

Application Insights-agenter och SDK:er för .NET, .NET Core, Java, Node.jsoch JavaScript stöder alla distribuerad spårning internt.

Med rätt Application Insights SDK installerat och konfigurerat, samlas spårningsinformation automatiskt in för populära ramverk, bibliotek och tekniker genom SDK-beroende automatiska insamlare. Den fullständiga listan över tekniker som stöds finns i dokumentationen för beroendebaserad autokollektion.

Alla teknologier kan också spåras manuellt med ett anrop till TrackDependency på TelemetryClient.

Datamodell för telemetrikorrelation

Application Insights definierar en datamodell för distribuerad telemetrikorrelation. Om du vill associera telemetri med en logisk åtgärd har varje telemetriobjekt ett kontextfält med namnet operation_Id. Varje telemetriobjekt i den distribuerade spårningen delar den här identifieraren. Så även om du förlorar telemetri från ett enda lager kan du fortfarande associera telemetri som rapporterats av andra komponenter.

En distribuerad logisk åtgärd består vanligtvis av en uppsättning mindre åtgärder som är begäranden som bearbetas av en av komponenterna. Telemetri för begäran definierar dessa åtgärder. Varje telemetriobjekt för begäran har ett eget id objekt som identifierar det unikt och globalt. Och alla telemetriobjekt (till exempel spårningar och undantag) som är associerade med begäran bör ange operation_parentId till värdet av begäran id.

Beroendetelemetri representerar varje utgående åtgärd, till exempel ett HTTP-anrop till en annan komponent. Den definierar också sin egen id, som är globalt unik. Telemetri för begäran, initierad av detta beroendekall, utnyttjar detta id som sin operation_parentId.

Du kan skapa en vy över den distribuerade logiska åtgärden med hjälp av operation_Id, operation_parentId och request.id tillsammans med dependency.id. Dessa fält definierar också kausalitetsordningen för telemetrianrop.

I en mikrotjänstmiljö kan spårningar från komponenter gå till olika lagringsobjekt. Varje komponent kan ha en egen anslutningssträng i Application Insights. För att få telemetri för den logiska åtgärden frågar Application Insights data från varje lagringsobjekt.

När antalet lagringsobjekt är stort behöver du en ledtråd om var du ska titta härnäst. Application Insights-datamodellen definierar två fält för att lösa det här problemet: request.source och dependency.target. Det första fältet identifierar komponenten som initierade beroendebegäran. Det andra fältet identifierar vilken komponent som returnerade svaret från beroendeanropet.

För information om hur du frågar från flera olika instanser hänvisas till 'Fråga efter data mellan Log Analytics-arbetsytor, program och resurser i Azure Monitor'.

Example

Nu ska vi titta på ett exempel. Ett program med namnet Aktiekurser visar det aktuella marknadspriset för en aktie med hjälp av ett externt API som heter Stock. Programmet Aktiekurser har en sida med namnet Aktiesida som klientens webbläsare öppnar med hjälp av GET /Home/Stock. Programmet frågar lager-API:et med hjälp av HTTP-anropet GET /api/stock/value.

Du kan analysera den resulterande telemetrin genom att köra en fråga:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

I resultatet delar alla telemetriobjekt roten operation_Id. När ett Ajax-anrop görs från sidan tilldelas ett nytt unikt ID (qJSXU) till beroendetelemetrin och ID:t för pageView används som operation_ParentId. Serverbegäran använder sedan Ajax-ID:t som operation_ParentId.

När anropet GET /api/stock/value görs till en extern tjänst måste du känna till serverns identitet så att du kan ange fältet dependency.target på rätt sätt. När den externa tjänsten inte stöder övervakning target ställs den in på tjänstens värdnamn. Ett exempel är stock-prices-api.com. Men om tjänsten identifierar sig genom att returnera ett fördefinierat HTTP-huvud innehåller target den tjänstidentitet som gör att Application Insights kan skapa en distribuerad spårning genom att fråga telemetri från den tjänsten.

Korrelationshuvuden med hjälp av W3C TraceContext

Application Insights övergår till W3C Trace-Context, som definierar:

• traceparent: Bär det globalt unika åtgärds-ID:t och den unika identifieraren för anropet.
• tracestate: Bär systemspecifikt spårningssammanhang.

Den senaste versionen av Application Insights SDK stöder Trace-Context-protokollet, men du kan behöva välja det. (Bakåtkompatibilitet med det tidigare korrelationsprotokollet som stöds av Application Insights SDK upprätthålls.)

HTTP-korrelationsprotokollet, även kallat Request-Id, är inaktuellt. Det här protokollet definierar två huvuden:

• Request-Id: Bär det globalt unika ID:t för anropet.
• Correlation-Context: Innehåller samlingen av namn-värdepar för de distribuerade spårningsegenskaperna.

Application Insights definierar också tillägget för HTTP-korrelationsprotokollet. Den använder Request-Context namn/värde-par för att överföra den samling egenskaper som används av den omedelbara anroparen eller anropade. Application Insights SDK använder huvudfältet för att ange fälten dependency.target och request.source.

Datamodellerna W3C Trace-Context och Application Insights mappar på följande sätt:

Mer information finns i Application Insights telemetridatamodell.

Aktivera stöd för distribuerad spårning i W3C

W3C TraceContext-baserad distribuerad spårning är aktiverad som standard i alla senaste .NET Framework/.NET Core SDK:er, tillsammans med bakåtkompatibilitet med äldre Request-Id protokoll.

Telemetrikorrelation

Korrelation hanteras som standard när en app registreras. Inga särskilda åtgärder krävs.

.NET-runtime stöder distribuerade system med hjälp av Activity och DiagnosticSource

Application Insights .NET SDK använder DiagnosticSource och Activity för att samla in och korrelera telemetri.

Beroenden

Automatiskt spårade beroenden

Application Insights SDK:er för .NET och .NET Core levereras med DependencyTrackingTelemetryModule, vilket är en telemetrimodul som automatiskt samlar in beroenden. Modulen DependencyTrackingTelemetryModule levereras som NuGet-paketet Microsoft.ApplicationInsights.DependencyCollector och hämtas automatiskt när du använder NuGet-paketet Microsoft.ApplicationInsights.Web eller Microsoft.ApplicationInsights.AspNetCore NuGet-paketet.

DependencyTrackingTelemetryModule Spårar för närvarande följande beroenden automatiskt:

Om beroendet inte samlas in automatiskt kan du spåra det manuellt med ett spårningsberoendeanrop.

Mer information om hur beroendespårning fungerar finns i Beroendespårning i Application Insights.

Konfigurera automatisk beroendespårning i konsolappar

Om du vill spåra beroenden automatiskt från .NET-konsolappar installerar du NuGet-paketet Microsoft.ApplicationInsights.DependencyCollector och initierar DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Spåra beroenden manuellt

Följande exempel på beroenden, som inte samlas in automatiskt, kräver manuell spårning:

• Azure Cosmos DB spåras endast automatiskt om HTTP/HTTPS används. TCP-läget registreras inte automatiskt av Application Insights för SDK-versioner som är äldre än 2.22.0-Beta1.
• Redis

För de beroenden som inte samlas in automatiskt av SDK kan du spåra dem manuellt med hjälp av TrackDependency-API:et som används av standardmodulerna för automatisk insamling.

Exempel

Om du skapar din kod med en sammansättning som du inte skrev själv kan du göra alla anrop till den. Med det här scenariot kan du ta reda på vilket bidrag det ger till dina svarstider.

Om du vill att dessa data ska visas i beroendediagrammen i Application Insights skickar du dem med hjälp TrackDependencyav :

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

TelemetryClient Du kan också ange tilläggsmetoderna StartOperation och StopOperation, som kan användas för att manuellt spåra beroenden enligt vad som visas i Spårning av utgående beroenden.

Inaktivera standardmodulen för beroendespårning

Mer information finns i telemetrimoduler.

Avancerad SQL-spårning för att hämta fullständig SQL-fråga

För SQL-anrop samlas alltid namnet på servern och databasen in och lagras som namnet på den insamlade DependencyTelemetry. Ett annat fält, som kallas data, kan innehålla den fullständiga SQL-frågetexten.

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module. EnableSqlCommandTextInstrumentation = true; });

I föregående fall är rätt sätt att verifiera att instrumentationsmotorn är korrekt installerad genom att verifiera att SDK-versionen av insamlad DependencyTelemetry är rddp. Användning av rdddsd eller rddf indikerar att beroenden samlas in via DiagnosticSource eller EventSource motringningar, så den fullständiga SQL-frågan samlas inte in.

Exceptions

Undantag i webbprogram kan rapporteras med Application Insights. Du kan korrelera misslyckade begäranden med undantag och andra händelser på både klienten och servern så att du snabbt kan diagnostisera orsakerna. I det här avsnittet får du lära dig hur du konfigurerar undantagsrapportering, rapporterar undantag explicit, diagnostiserar fel med mera.

Konfigurera undantagsrapportering

Du kan konfigurera Application Insights för att rapportera undantag som inträffar på antingen servern eller klienten. Beroende på vilken plattform ditt program är beroende av behöver du rätt tillägg eller SDK.

Diagnostisera fel och undantag

Anpassad spårning och loggdata

För att få diagnostikdata som är specifika för din app kan du infoga kod för att skicka egna telemetridata. Dina anpassade telemetri- eller loggdata visas i diagnostiksökningen tillsammans med begäran, sidvyn och andra automatiskt insamlade data.

Med hjälp av Microsoft.VisualStudio.ApplicationInsights.TelemetryClienthar du flera TILLGÄNGLIGA API:er:

• TelemetryClient.TrackEvent används vanligtvis för att övervaka användningsmönster, men de data som skickas visas också under Anpassade händelser i diagnostiksökningen. Händelser namnges och kan innehålla strängegenskaper och numeriska mått som du kan filtrera dina diagnostiksökningar på.
• TelemetryClient.TrackTrace låter dig skicka längre data, till exempel POST-information.
• TelemetryClient.TrackException skickar undantagsinformation, till exempel stackspårningar till Application Insights.

Om du vill se dessa händelser öppnar du Sök på den vänstra menyn. Välj den nedrullningsbara menyn Händelsetyper och välj sedan Anpassad händelse, Spårning eller Undantag.

Se POST-begärandedata

Information om begäran inkluderar inte de data som skickas till din app i ett POST-anrop. Så här rapporterar du dessa data:

• Lägg till Application Insights SDK i din appkod.
• Infoga kod i programmet för att anropa Microsoft.ApplicationInsights.TrackTrace(). Skicka POST-data i meddelandeparametern. Det finns en gräns för den tillåtna storleken, så du bör bara försöka skicka viktiga data.
• När du undersöker en misslyckad begäran letar du upp de associerade spårningarna.

Samla in undantag och relaterade diagnostikdata

Som standard visas inte alla undantag som orsakar fel i din app i portalen. Om du använder JavaScript SDK på dina webbsidor visas webbläsarfel. De flesta undantag på serversidan fångas dock upp av IIS, så du måste lägga till kod för att samla in och rapportera dem.

Du kan:

• Logga undantag explicit genom att infoga kod i undantagshanterare för att rapportera undantagen.
• Samla in undantag automatiskt genom att konfigurera ditt ASP.NET ramverk. De nödvändiga tilläggen skiljer sig åt för olika typer av ramverk.

Rapportera undantag explicit

Det enklaste sättet att rapportera är att infoga ett anrop till trackException() i en undantagshanterare.

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

Parametrarna för egenskaper och mått är valfria, men de är användbara för att filtrera och lägga till extra information. Om du till exempel har en app som kan köra flera spel kan du hitta alla undantagsrapporter som är relaterade till ett visst spel. Du kan lägga till så många objekt som du vill i varje ordlista.

Webbläsarfel

De flesta webbläsarfel rapporteras.

Om din webbsida innehåller skriptfiler från nätverk för innehållsleverans eller andra domäner kontrollerar du att skripttaggen har attributet crossorigin="anonymous" och att servern skickar CORS-huvuden. Med det här beteendet kan du hämta en stackspårning och information för ohanterade JavaScript-undantag från dessa resurser.

Återanvänd din telemetriklient

Med Dependency Injection (DI) i .NET, lämplig .NET SDK och korrekt konfiguration av Application Insights för DI, kan du kräva TelemetryClient som en konstruktorparameter.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

I föregående exempel TelemetryClient matas ExampleController in i klassen.

Webbformulär

För webbformulär kan HTTP-modulen samla in undantagen när inga omdirigeringar har konfigurerats med CustomErrors. Men när du har aktiva omdirigeringar lägger du till följande rader i Application_Error funktionen i Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

I föregående exempel _telemetryClient är en variabel med klassomfattning av typen TelemetryClient.

MVC

Från och med Application Insights Web SDK version 2.6 (beta 3 och senare) samlar Application Insights in ohanterade undantag som genereras automatiskt i MVC 5+-kontrollantmetoderna. Om du tidigare har lagt till en anpassad hanterare för att spåra sådana undantag kan du ta bort den för att förhindra dubbel spårning av undantag.

Det finns flera scenarier när ett undantagsfilter inte kan hantera fel korrekt när undantag utlöses:

• Från styrenhetskonstruktorer
• Från meddelandehanterare
• Under routning
• Under svarsinnehålls serialisering
• Under programstart
• I bakgrundsaktiviteter

Alla undantag som hanteras av programmet måste fortfarande spåras manuellt. Ohanterade undantag från kontrollanter resulterar vanligtvis i ett svar på 500 "internt serverfel". Om ett sådant svar konstrueras manuellt till följd av ett hanterat undantag, eller inget undantag alls, spåras det i motsvarande telemetri för begäran med ResultCode 500. Application Insights SDK kan dock inte spåra ett motsvarande undantag.

Stöd för tidigare versioner

Om du använder MVC 4 (och tidigare) av Application Insights Web SDK 2.5 (och tidigare) läser du följande exempel för att spåra undantag.

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Webb-API

Från och med Application Insights Web SDK version 2.6 (beta 3 och senare) samlar Application Insights in ohanterade undantag som genereras i kontrollantmetoderna automatiskt för Web API 2+. Om du tidigare har lagt till en anpassad hanterare för att spåra sådana undantag, enligt beskrivningen i följande exempel, kan du ta bort den för att förhindra dubbel spårning av undantag.

Det finns flera fall som undantagsfiltren inte kan hantera. Till exempel:

• Undantag som genereras från styrenhetskonstruktorer.
• Undantag som genereras från meddelandehanterare.
• Undantag som utlöses under routning.
• Undantag som utlöses under svarsinnehålls serialisering.
• Undantag som utlöses när programmet startas.
• Undantag som genereras i bakgrundsaktiviteter.

Alla undantag som hanteras av programmet måste fortfarande spåras manuellt. Ohanterade undantag från kontrollanter resulterar vanligtvis i ett svar på 500 "internt serverfel". Om ett sådant svar konstrueras manuellt till följd av ett hanterat undantag, eller inget undantag alls, spåras det i en motsvarande telemetri för begäran med ResultCode 500. Application Insights SDK kan dock inte spåra ett motsvarande undantag.

Stöd för tidigare versioner

Om du använder Web API 1 (och tidigare) av Application Insights Web SDK 2.5 (och tidigare) läser du följande exempel för att spåra undantag.

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

WCF

Lägg till en klass som utökar Attribute och implementerar IErrorHandler och IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Lägg till attributet i tjänstimplementeringarna:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Exempel

Prestandaräknare för undantag

Om du har installerat Azure Monitor Application Insights-agenten på servern kan du få ett diagram över undantagsfrekvensen som mäts av .NET. Både hanterade och ohanterade .NET-undantag ingår.

Öppna fliken metrics explorer och lägg till ett nytt diagram. Under Prestandaräknare väljer du Undantagsfrekvens.

.NET Framework beräknar frekvensen genom att räkna antalet undantag i ett intervall och dividera med intervallets längd.

Det här antalet skiljer sig från antalet undantag som beräknas av Application Insights-portalens inventeringsrapporter TrackException . Samplingsintervallen skiljer sig åt och SDK skickar TrackException inte rapporter för alla hanterade och ohanterade undantag.

Anpassad måttsamling

Azure Monitor Application Insights .NET och .NET Core SDK:er har två olika metoder för att samla in anpassade mått:

• Metoden TrackMetric() , som saknar föraggregering.
• Metoden GetMetric() , som har föraggregering.

Vi rekommenderar att du använder aggregering, så TrackMetric()det är inte längre den bästa metoden för att samla in anpassade mått. Den här artikeln beskriver hur du använder GetMetric() metoden och en del av logiken bakom hur den fungerar.

Kom igång med GetMetric

I våra exempel ska vi använda ett grundläggande .NET Core 3.1-arbetstjänstprogram. Om du vill replikera testmiljön som används med dessa exempel följer du steg 1–6 under .NET Core Worker Service-programmet. De här stegen lägger till Application Insights i en grundläggande arbetstjänstprojektmall. Begreppen gäller för alla allmänna program där SDK:t kan användas, inklusive webbappar och konsolappar.

Skicka mått

Ersätt innehållet i worker.cs filen med följande kod:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

När du kör exempelkoden ser du att loopen while körs upprepade gånger utan att telemetri skickas i Visual Studio-utdatafönstret. Ett enda telemetriobjekt skickas runt 60-sekundersmarkeringen, vilket i vårt test ser ut så här:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Det här enskilda telemetriobjektet representerar en sammanställning av 41 distinkta måttmätningar. Eftersom vi skickade samma värde om och om igen har vi en standardavvikelse (stDev) av 0 med identiska högsta (max) och lägsta (min) värden. Egenskapen value representerar en summa av alla enskilda värden som aggregerades.

Om vi undersöker vår Application Insights-resurs i logs(Analytics) -upplevelsen skulle det enskilda telemetriobjektet se ut som följande skärmbild.

Du kan också komma åt din anpassade måtttelemetri i avsnittet Mått i portalen som både ett loggbaserat och anpassat mått. Följande skärmbild är ett exempel på ett loggbaserat mått.

Referens för cachemått för användning med högt dataflöde

Måttvärden kan observeras ofta i vissa fall. En tjänst med högt dataflöde som bearbetar 500 begäranden per sekund kanske vill generera 20 telemetrimått för varje begäran. Resultatet innebär att du spårar 10 000 värden per sekund. I sådana scenarier med högt dataflöde kan användarna behöva hjälpa SDK:t genom att undvika vissa sökningar.

Till exempel utförde föregående exempel en sökning efter ett handtag för måttet ComputersSold och spårade sedan ett observerat värde på 42. I stället kan handtaget cachelagras för flera spåranrop:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Förutom att cachelagra måtthandtaget minskades Task.Delay även föregående exempel till 50 millisekunder så att loopen skulle köras oftare. Resultatet är 772 TrackValue() anrop.

Flerdimensionella mått

Exemplen i föregående avsnitt visar nolldimensionella mått. Mått kan också vara flerdimensionella. Vi stöder för närvarande upp till 10 dimensioner.

Här är ett exempel på hur du skapar ett endimensionellt mått:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Om du kör exempelkoden i minst 60 sekunder skickas tre distinkta telemetriobjekt till Azure. Varje objekt representerar aggregeringen av en av de tre formfaktorerna. Precis som tidigare kan du undersöka mer i vyn Loggar (analys).

I metrics Explorer:

Observera att du inte kan dela upp måttet med din nya anpassade dimension eller visa din anpassade dimension med måttvyn.

Som standard är flerdimensionella mått i måttutforskaren inte aktiverade i Application Insights-resurser.

Aktivera flerdimensionella mått

Om du vill aktivera flerdimensionella mått för en Application Insights-resurs väljer du Användning och uppskattade kostnader>Anpassade mått> för anpassade måttdimensioner >OK. Mer information finns i Anpassade måttdimensioner och föraggregering.

När du har gjort ändringen och skickat ny flerdimensionell telemetri kan du välja Tillämpa delning.

Visa dina måttaggregeringar för varje FormFactor dimension.

Använd MetricIdentifier när det finns fler än tre dimensioner

För närvarande stöds 10 dimensioner. Om du använder fler än tre dimensioner måste du använda MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Anpassad måttkonfiguration

Om du vill ändra måttkonfigurationen måste du göra ändringar på den plats där måttet initieras.

Specialdimensionsnamn

Mått använder inte telemetrikontexten för de TelemetryClient som används för att komma åt dem. Att använda specialdimensionsnamn som är tillgängliga som konstanter i MetricDimensionNames klassen är den bästa lösningen för den här begränsningen.

Måttaggregeringar som skickas av följande Special Operation Request Size mått har Context.Operation.Name angetts till Special Operation. Metoden TrackMetric() eller någon annan TrackXXX() metod har OperationName angetts korrekt till Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

I det här fallet använder du de specialdimensionsnamn som anges i MetricDimensionNames klassen för att ange TelemetryContext värdena.

När måttaggregatet som kommer från nästa instruktion till exempel skickas till Application Insights-molnslutpunkten är dess Context.Operation.Name datafält inställt på Special Operation:

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

Värdet för den här specialdimensionen kopieras till TelemetryContext och används inte som en normal dimension. Om du även vill behålla en åtgärdsdimension för normal måttutforskning måste du skapa en separat dimension för detta ändamål:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Tak för dimensioner och tidsserier

Om du vill förhindra att telemetriundersystemet oavsiktligt använder dina resurser kan du styra det maximala antalet dataserier per mått. Standardgränserna är högst 1 000 totala dataserier per mått och högst 100 olika värden per dimension.

När det gäller begränsning av dimension och tidsserier använder Metric.TrackValue(..) vi för att se till att gränserna följs. Om gränserna redan har nåtts Metric.TrackValue(..) returneras False och värdet spåras inte. Annars returneras True. Det här beteendet är användbart om data för ett mått kommer från användarindata.

Konstruktorn MetricConfiguration tar några alternativ för hur du hanterar olika serier inom respektive mått och ett objekt i en klass som implementerar IMetricSeriesConfiguration som anger aggregeringsbeteende för varje enskild serie av måttet:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call does not track the metric, and returns false.

• seriesCountLimit är det maximala antalet datatidsserier som ett mått kan innehålla. När den här gränsen har nåtts returnerar anrop till TrackValue() det normalt en ny serie .false
• valuesPerDimensionLimit begränsar antalet distinkta värden per dimension på ett liknande sätt.
• restrictToUInt32Values avgör om endast icke-negativa heltalsvärden ska spåras eller inte.

Här är ett exempel på hur du skickar ett meddelande för att veta om gränsen överskrids:

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Spårning av anpassade åtgärder

Application Insights SDK:er spårar automatiskt inkommande HTTP-begäranden och anrop till beroende tjänster, till exempel HTTP-begäranden och SQL-frågor. Spårning och korrelation av begäranden och beroenden ger dig insyn i hela programmets svarstider och tillförlitlighet för alla mikrotjänster som kombinerar det här programmet.

Det finns en klass med programmönster som inte kan stödjas allmänt. Korrekt övervakning av sådana mönster kräver manuell kodinstrumentation. Det här avsnittet beskriver några mönster som kan kräva manuell instrumentering, till exempel anpassad köbearbetning och tidskrävande bakgrundsuppgifter.

Det här avsnittet innehåller vägledning om hur du spårar anpassade åtgärder med Application Insights SDK.

Översikt

En åtgärd är ett logiskt arbete som körs av ett program. Den har ett namn, starttid, varaktighet, resultat och en kontext för körning som användarnamn, egenskaper och resultat. Om åtgärd A initierades av åtgärd B anges åtgärd B som överordnad för A. En åtgärd kan bara ha en överordnad åtgärd, men den kan ha många underordnade åtgärder. Mer information om åtgärder och telemetrikorrelation finns i Application Insights telemetrikorrelation.

I Application Insights .NET SDK beskrivs åtgärden av den abstrakta klassen OperationTelemetry och dess underordnade RequestTelemetry och DependencyTelemetry.

Spårning av inkommande åtgärder

Application Insights webb-SDK samlar automatiskt in HTTP-begäranden för ASP.NET program som körs i en IIS-pipeline och alla ASP.NET Core-program. Det finns lösningar som stöds av communityn för andra plattformar och ramverk. Om programmet inte stöds av någon av de standardlösningar eller lösningar som stöds av communityn kan du instrumentera det manuellt.

Ett annat exempel som kräver anpassad spårning är arbetaren som tar emot objekt från kön. För vissa köer spåras anropet för att lägga till ett meddelande i den här kön som ett beroende. Den övergripande åtgärd som beskriver meddelandebearbetning samlas inte in automatiskt.

Nu ska vi se hur sådana åtgärder kan spåras.

På hög nivå är uppgiften att skapa RequestTelemetry och ange kända egenskaper. När åtgärden är klar spårar du telemetrin. I följande exempel visas den här uppgiften.

HTTP-begäran i en lokalt installerad Owin-app

I det här exemplet sprids spårningskontexten enligt HTTP-protokollet för korrelation. Du bör förvänta dig att få rubriker som beskrivs där.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

HTTP-protokollet för korrelation deklarerar Correlation-Context också huvudet. Det utelämnas här för enkelhetens skull.

Köinstrumentation

W3C-spårningskontexten och HTTP-protokollet för korrelationspasskorrelationsinformation med HTTP-begäranden, men varje köprotokoll måste definiera hur samma information skickas längs kömeddelandet. Vissa köprotokoll, till exempel AMQP, tillåter överföring av fler metadata. Andra protokoll, till exempel Azure Storage Queue, kräver att kontexten kodas i meddelandets nyttolast.

Service Bus-kö

Information om spårning finns i Distribuerad spårning och korrelation via Azure Service Bus-meddelanden.

Azure Storage-kö

I följande exempel visas hur du spårar Azure Storage-köåtgärderna och korrelerar telemetri mellan producenten, konsumenten och Azure Storage.

Lagringskön har ett HTTP-API. Alla anrop till kön spåras av Application Insights Dependency Collector för HTTP-begäranden. Den konfigureras som standard för ASP.NET- och ASP.NET Core-program. Med andra typer av program kan du läsa dokumentationen om konsolprogram.

Du kanske också vill korrelera Application Insights-åtgärds-ID:t med ID:t för lagringsbegäran. Information om hur du anger och hämtar en klient för lagringsbegäran och ett serverbegärans-ID finns i Övervaka, diagnostisera och felsöka Azure Storage.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

På samma sätt kan andra köåtgärder instrumenteras. En granskningsåtgärd bör instrumenteras på ett liknande sätt som en dequeue-åtgärd. Instrumentering av köhanteringsåtgärder är inte nödvändigt. Application Insights spårar åtgärder som HTTP, och i de flesta fall räcker det.

När du instrumentera borttagning av meddelanden kontrollerar du att du anger åtgärdsidentifierarna (korrelation). Du kan också använda API:et Activity . Sedan behöver du inte ange åtgärdsidentifierare för telemetriobjekten eftersom Application Insights SDK gör det åt dig:

• Skapa en ny Activity när du har fått ett objekt från kön.
• Använd Activity.SetParentId(message.ParentId) för att korrelera konsument- och producentloggar.
• ActivityStarta .
• Spåra dequeue-, process- och borttagningsåtgärder med hjälp av hjälpfunktioner Start/StopOperation . Gör det från samma asynkrona kontrollflöde (körningskontext). På så sätt korreleras de korrekt.
• ActivityStoppa .
• Använd Start/StopOperation eller anropa Track telemetri manuellt.

Beroendetyper

Application Insights använder beroendetyp för att anpassa användargränssnittsupplevelser. För köer identifieras följande typer av som förbättrar upplevelsen av DependencyTelemetrytransaktionsdiagnostik:

• Azure queue för Azure Storage-köer
• Azure Event Hubs för Azure Event Hubs
• Azure Service Bus för Azure Service Bus

Satsvis bearbetning

Med vissa köer kan du ta bort flera meddelanden med en begäran. Bearbetningen av sådana meddelanden är förmodligen oberoende och tillhör de olika logiska åtgärderna. Det går inte att korrelera åtgärden Dequeue med ett visst meddelande som bearbetas.

Varje meddelande ska bearbetas i sitt eget asynkrona kontrollflöde. Mer information finns i avsnittet Spårning av utgående beroenden .

Långvariga bakgrundsaktiviteter

Vissa program startar tidskrävande åtgärder som kan orsakas av användarbegäranden. Ur spårnings-/instrumentationsperspektivet skiljer det sig inte från instrumentation för begäran eller beroende:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

I det här exemplet telemetryClient.StartOperation skapar DependencyTelemetry och fyller korrelationskontexten. Anta att du har en överordnad åtgärd som skapades av inkommande begäranden som schemalagt åtgärden. Så länge som BackgroundTask startar i samma asynkrona kontrollflöde som en inkommande begäran korreleras den med den överordnade åtgärden. BackgroundTask och alla kapslade telemetriobjekt korreleras automatiskt med den begäran som orsakade den, även när begäran har avslutats.

När aktiviteten startar från bakgrundstråden som inte har någon åtgärd (Activity) associerad med den, BackgroundTask har den ingen överordnad. Den kan dock ha kapslade åtgärder. Alla telemetriobjekt som rapporteras från aktiviteten korreleras till de som skapats DependencyTelemetry i BackgroundTask.

Spårning av utgående beroenden

Du kan spåra din egen beroendetyp eller en åtgärd som inte stöds av Application Insights.

Metoden Enqueue i Service Bus-kön eller lagringskön kan fungera som exempel för sådan anpassad spårning.

Den allmänna metoden för anpassad beroendespårning är att:

• Anropa metoden TelemetryClient.StartOperation (tillägg) som fyller de DependencyTelemetry egenskaper som behövs för korrelation och vissa andra egenskaper, till exempel start, tidsstämpel och varaktighet.
• Ange andra anpassade egenskaper för DependencyTelemetry, till exempel namnet och alla andra kontexter som du behöver.
• Ring ett beroendeanrop och vänta på det.
• Stoppa åtgärden med StopOperation när den är klar.
• Hantera undantag.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

Om du tar bort en åtgärd stoppas åtgärden, så du kan göra det i stället för att anropa StopOperation.

Bearbetning och spårning av parallella åtgärder

Anrop StopOperation stoppar bara den åtgärd som startades. Om den aktuella åtgärden som körs inte matchar den som du vill stoppa, StopOperation gör ingenting. Den här situationen kan inträffa om du startar flera åtgärder parallellt i samma körningskontext.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Se till att du alltid anropar StartOperation och bearbetar åtgärden i samma asynkron metod för att isolera åtgärder som körs parallellt. Om åtgärden är synkron (eller inte asynkron), omsluter du processen och spårar med Task.Run.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

ApplicationInsights-åtgärder jämfört med System.Diagnostics.Activity

System.Diagnostics.Activity representerar den distribuerade spårningskontexten och används av ramverk och bibliotek för att skapa och sprida kontext i och utanför processen och korrelera telemetriobjekt. Activity fungerar tillsammans med System.Diagnostics.DiagnosticSource som meddelandemekanism mellan ramverket/biblioteket för att meddela om intressanta händelser som inkommande eller utgående begäranden och undantag.

Aktiviteter är funktioner på den översta nivån i Application Insights. Automatisk beroende- och begärandeinsamling är starkt beroende av dem tillsammans med DiagnosticSource händelser. Om du har skapat Activity i ditt program skulle det inte leda till att Application Insights-telemetri skapas. Application Insights måste ta emot DiagnosticSource händelser och känna till händelsenamn och händelsedata för att omvandla Activity till telemetri.

Varje Application Insights-åtgärd (begäran eller beroende) omfattar Activity. När StartOperation anropas skapas Activity den under. StartOperation är det rekommenderade sättet att spåra telemetrier för begäran eller beroende manuellt och se till att allt är korrelerat.

Räknare i Application Insights

Application Insights stöder prestandaräknare och händelseräknare. Den här guiden ger en översikt över båda, inklusive deras syfte, konfiguration och användning i .NET-program.

Översikt

Prestandaräknare

Windows tillhandahåller olika prestandaräknare, till exempel de som används för att samla in statistik för processor, minne och diskanvändning. Du kan också definiera dina egna prestandaräknare.

Programmet stöder insamling av prestandaräknare om den körs under Internet Information Server (IIS) på en lokal värd eller en virtuell dator med administrativ åtkomst. Program som körs som Azure Web Apps kan inte komma åt prestandaräknare direkt, men Application Insights samlar in en delmängd av tillgängliga räknare.

Förutsättningar

Ge apppooltjänstkontot behörighet att övervaka prestandaräknare genom att lägga till det i gruppen Användare av prestandaövervakare .

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Visa räknare

Fönstret Mått visar standarduppsättningen med prestandaräknare.

Lägg till räknare

Om prestandaräknaren du vill använda inte ingår i listan med mått kan du lägga till den.

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Samla in prestandaräknare i kod för ASP.NET webbprogram eller .NET/.NET Core-konsolprogram

Om du vill samla in systemprestandaräknare och skicka dem till Application Insights kan du anpassa följande kodfragment:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Eller så kan du göra samma sak med anpassade mått som du skapade:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Prestandaräknare för program som körs i Azure Web Apps och Windows-containrar i Azure App Service

Både ASP.NET och ASP.NET Core-program som distribueras till Azure Web Apps körs i en speciell sandbox-miljö. Program som distribueras till Azure App Service kan använda en Windows-container eller finnas i en sandbox-miljö. Om programmet distribueras i en Windows-container är alla standardprestandaräknare tillgängliga i containeravbildningen.

Sandbox-miljön tillåter inte direkt åtkomst till systemprestandaräknare. En begränsad delmängd av räknare exponeras dock som miljövariabler enligt beskrivningen i Perf-räknare som exponeras som miljövariabler. Endast en delmängd av räknare är tillgänglig i den här miljön. Den fullständiga listan finns i Perf-räknare som exponeras som miljövariabler.

Application Insights SDK för ASP.NET och ASP.NET Core identifierar om kod distribueras till en webbapp eller en container som inte är Windows. Identifieringen avgör om den samlar in prestandaräknare i en sandbox-miljö eller använder standardsamlingsmekanismen när den finns på en Windows-container eller virtuell dator.

Log Analytics-frågor för prestandaräknare

Du kan söka efter och visa prestandaräknarrapporter i Log Analytics.

PerformanceCounters-schemat visar category, counter namn och instance namn på varje prestandaräknare. I telemetrin för varje program ser du bara räknare för det programmet. Om du till exempel vill se vilka räknare som är tillgängliga:

performanceCounters | summarize count(), avg(value) by category, instance, counter

Instance Här refererar till prestandaräknarens instans, inte rollen eller serverdatorinstansen. Prestandaräknarens instansnamn segmentar vanligtvis räknare, till exempel processortid, efter namnet på processen eller programmet.

Så här hämtar du ett diagram över tillgängligt minne under den senaste perioden:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

Precis som andra telemetrier har performanceCounters också en kolumn cloud_RoleInstance som anger identiteten för den värdserverinstans som appen körs på. Om du till exempel vill jämföra appens prestanda på de olika datorerna:

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Vanliga frågor och svar om prestandaräknare

Mer information om vanliga frågor och svar finns i Vanliga frågor och svar om prestandaräknare.

Händelseräknare

EventCounter är .NET/.NET Core-mekanismen för att publicera och använda räknare eller statistik. EventCounters stöds på alla operativsystemplattformar – Windows, Linux och macOS. Det kan ses som en plattformsoberoende motsvarighet för PerformanceCounters som endast stöds i Windows-system.

Medan användare kan publicera anpassade händelseräknare för att uppfylla sina behov publicerar .NET en uppsättning av dessa räknare som standard. Det här dokumentet går igenom de steg som krävs för att samla in och visa händelseräknare (systemdefinierade eller användardefinierade) i Azure Application Insights.

Använda Application Insights för att samla in EventCounters

Application Insights stöder insamling EventCounters med dess EventCounterCollectionModule, som är en del av det nyligen släppta NuGet-paketet Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule aktiveras automatiskt när du använder Antingen AspNetCore eller WorkerService. EventCounterCollectionModule samlar in räknare med en icke-konfigurerbar samlingsfrekvens på 60 sekunder. Det krävs inga särskilda behörigheter för att samla in EventCounters. För ASP.NET Core-program vill du också lägga till paketet Microsoft.ApplicationInsights.AspNetCore .

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Insamlade standardräknare

Från och med 2.15.0-versionen av antingen AspNetCore SDK eller WorkerService SDK samlas inga räknare in som standard. Själva modulen är aktiverad så att användarna kan lägga till önskade räknare för att samla in dem.

En lista över välkända räknare som publicerats av .NET Runtime finns i dokumentet Tillgängliga räknare .

Anpassa räknare som ska samlas in

I följande exempel visas hur du lägger till/tar bort räknare. Den här anpassningen görs som en del av programtjänstkonfigurationen när Application Insights-telemetrisamlingen har aktiverats med antingen AddApplicationInsightsTelemetry() eller AddApplicationInsightsWorkerService(). Följande är en exempelkod från ett ASP.NET Core-program. För andra typer av applikationer, se konfigurera telemetrimoduler.

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Inaktivera eventcounter-samlingsmodul

EventCounterCollectionModule kan inaktiveras med hjälp ApplicationInsightsServiceOptionsav .

I följande exempel används ASP.NET Core SDK.

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

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

En liknande metod kan också användas för Worker Service SDK, men namnområdet måste ändras enligt följande exempel.

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

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Log Analytics-frågor för händelseräknare

Du kan söka efter och visa händelseräknarerapporter i Log Analytics i tabellen customMetrics .

Kör till exempel följande fråga för att se vilka räknare som samlas in och är tillgängliga för frågor:

customMetrics | summarize avg(value) by name

Om du vill hämta ett diagram över en specifik räknare (till exempel: ThreadPool Completed Work Item Count) under den senaste perioden kör du följande fråga.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

Precis som andra telemetrier har customMetrics också en kolumn cloud_RoleInstance som anger identiteten för den värdserverinstans som appen körs på. Föregående fråga visar räknarvärdet per instans och kan användas för att jämföra prestanda för olika serverinstanser.

Vanliga frågor och svar om händelseräknare

Mer information om vanliga frågor och svar finns i Vanliga frågor och svar om händelseräknare.

Filtrera och berika telemetri

I det här avsnittet

• Filtrera och förbearbeta telemetri
• Telemetriinitierare
• Telemetriprocessor
• Provtagning
• Utöka data via HTTP

Filtrera och förbearbeta telemetri

Du kan skriva kod för att filtrera, ändra eller utöka telemetrin innan den skickas från SDK:t. Bearbetningen innehåller data som skickas från standardtelemetrimodulerna, till exempel INSAMLING av HTTP-begäranden och beroendeinsamling.

• Filtrering kan ändra eller ta bort telemetri innan den skickas från SDK:t genom att implementera ITelemetryProcessor. Du kan till exempel minska mängden telemetri genom att exkludera begäranden från robotar. Till skillnad från sampling har du fullständig kontroll över vad som skickas eller tas bort, men det påverkar alla mått som baseras på aggregerade loggar. Beroende på hur du tar bort objekt kan du också förlora möjligheten att navigera mellan relaterade objekt.

• Lägg till eller ändra egenskaper i telemetri som skickas från din app genom att implementera en ITelemetryInitializer. Du kan till exempel lägga till beräknade värden eller versionsnummer för att filtrera data i portalen.

• Sampling minskar mängden telemetri utan att påverka din statistik. Den håller ihop relaterade datapunkter så att du kan navigera mellan dem när du diagnostiserar ett problem. I portalen multipliceras det totala antalet för att kompensera för samplingen.

Filtering

Den här tekniken ger dig direkt kontroll över vad som ingår eller undantas från telemetriströmmen. Filtrering kan användas för att ta bort telemetriobjekt från att skickas till Application Insights. Du kan använda filtrering med sampling eller separat.

Om du vill filtrera telemetri skriver du en telemetriprocessor och registrerar den med TelemetryConfiguration. All telemetri går igenom din processor. Du kan välja att släppa den från strömmen eller ge den till nästa processor i kedjan. Telemetri från standardmodulerna, till exempel HTTP-begärandeinsamlaren och beroendeinsamlaren, och telemetri som du spårade själv ingår. Du kan till exempel filtrera bort telemetri om begäranden från robotar eller lyckade beroendeanrop.

ITelemetryProcessor och ITelemetryInitializer

Vad är skillnaden mellan telemetriprocessorer och telemetriinitierare?

• Det finns vissa överlappningar i vad du kan göra med dem. Båda kan användas för att lägga till eller ändra egenskaper för telemetri, men vi rekommenderar att du använder initierare för detta ändamål.
• Telemetriinitierare körs alltid före telemetriprocessorer.
• Telemetriinitierare kan anropas mer än en gång. Enligt konventionen anger de inte någon egenskap som redan har angetts.
• Med telemetriprocessorer kan du helt ersätta eller ta bort ett telemetriobjekt.
• Alla registrerade telemetriinitierare anropas för varje telemetriobjekt. För telemetriprocessorer garanterar SDK att den första telemetriprocessorn anropas. Om resten av processorerna anropas eller inte bestäms av de föregående telemetriprocessorerna.
• Använd telemetriinitierare för att utöka telemetri med fler egenskaper eller åsidosätta en befintlig. Använd en telemetriprocessor för att filtrera bort telemetri.

Lägg till/ändra egenskaper

Använd telemetriinitierare för att utöka telemetri med ytterligare information eller för att åsidosätta telemetriegenskaper som anges av standardtelemetrimodulerna.

Application Insights för ett webbpaket samlar till exempel in telemetri om HTTP-begäranden. Som standard flaggas alla begäranden med svarskoden >=400 som misslyckade. Om du i stället vill behandla 400 som en framgång kan du ange en telemetri-initialiserare som ställer in framgångsegenskapen.

Om du anger en telemetriinitierare anropas den när någon av Metoderna Track*() anropas. Den här initiatorn innehåller Track() metoder som anropas av standardtelemetrimodulerna. Enligt konventionen anger dessa moduler inte någon egenskap som redan har angetts av en initiator. Telemetriinitierare anropas innan telemetriprocessorer anropas, så alla berikanden som görs av initiatorer är synliga för processorer.

Telemetriinitierare

Om du vill utöka telemetri med ytterligare information eller åsidosätta telemetriegenskaper som anges av standardtelemetrimodulerna använder du telemetriinitierare.

Telemetriinitierare anger kontextegenskaper som skickas tillsammans med varje telemetriobjekt. Du kan skriva egna initierare för att ange kontextegenskaper.

Standardinitierarna anges antingen av webben eller WindowsServer NuGet-paket:

Lägg till ITelemetryInitializer

Den här bloggen beskriver ett projekt för att diagnostisera beroendeproblem genom att automatiskt skicka regelbundna pingar till beroenden.

1. Definiera initieraren

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Läs in din initierare

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

Exempel på ITelemetryInitializers

Lägga till en anpassad egenskap

Följande exempelinitierare lägger till en anpassad egenskap för varje spårad telemetri.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Lägga till ett molnrollnamn och en molnrollinstans

Steg 1: Skriv anpassad TelemetryInitializer

Följande exempelinitierare anger namnet på molnrollen till varje spårad telemetri.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

Steg 2: Läs in en initiator till TelemetryConfiguration

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Kontrollera klientens IP-adress som används för geoplatsmappningar

Följande exempelinitierare anger klientens IP-adress, som används för geoplatsmappning, i stället för IP-adressen för klient socket, under telemetriinmatning.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Telemetriprocessorer

Telemetriprocessorer kan filtrera och ändra varje telemetriobjekt innan det skickas från SDK:t till portalen.

1. Implementera ITelemetryProcessor.

   Telemetriprocessorer skapar en bearbetningskedja. När du instansierar en telemetriprocessor får du en referens till nästa processor i kedjan. När en telemetridatapunkt skickas till processmetoden utför den sitt arbete och anropar sedan (eller anropar inte) nästa telemetriprocessor i kedjan.

   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.Extensibility;
   using Microsoft.ApplicationInsights.DataContracts;
   
   public class SuccessfulDependencyFilter : ITelemetryProcessor
   {
       private ITelemetryProcessor Next { get; set; }
   
       // next will point to the next TelemetryProcessor in the chain.
       public SuccessfulDependencyFilter(ITelemetryProcessor next)
       {
           this.Next = next;
       }
   
       public void Process(ITelemetry item)
       {
           // To filter out an item, return without calling the next processor.
           if (!OKtoSend(item)) { return; }
   
           this.Next.Process(item);
       }
   
       // Example: replace with your own criteria.
       private bool OKtoSend (ITelemetry item)
       {
           var dependency = item as DependencyTelemetry;
           if (dependency == null) return true;
   
           return dependency.Success != true;
       }
   }
   

2. Lägg till processorn.

   • ASP.NET
   • ASP.NET Core
   • Arbetstjänst

   Infoga det här kodfragmentet i ApplicationInsights.config:

   <TelemetryProcessors>
     <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
       <!-- Set public property -->
       <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
     </Add>
   </TelemetryProcessors>
   

   Du kan skicka strängvärden från .config-filen genom att ange offentliga namngivna egenskaper i din klass.

   Varning

   Var noga med att matcha typnamnet och eventuella egenskapsnamn i .config-filen med klass- och egenskapsnamnen i koden. Om .config-filen refererar till en icke-existerande typ eller egenskap kan SDK:t tyst misslyckas med att skicka telemetri.

   Du kan också initiera filtret i koden. I en lämplig initieringsklass, till exempel AppStart i Global.asax.cs, infogar du processorn i kedjan:

   Anmärkning

   Följande kodexempel är föråldrat, men görs tillgängligt här för eftervärlden. Överväg att komma igång med OpenTelemetry eller migrera till OpenTelemetry.

   var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
   builder.Use((next) => new SuccessfulDependencyFilter(next));
   
   // If you have more processors:
   builder.Use((next) => new AnotherProcessor(next));
   
   builder.Build();
   

   Telemetriklienter som skapats efter den här punkten använder dina processorer.

   Telemetriprocessor för anpassningsbar sampling (från 2.0.0-beta3)

   Den här funktionen är aktiverad som standard. Om din app skickar betydande telemetri tar den här processorn bort en del av den.

   
       <TelemetryProcessors>
         <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
           <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
         </Add>
       </TelemetryProcessors>
   
   

   Parametern ger det mål som algoritmen försöker uppnå. Varje instans av SDK:t fungerar oberoende av varandra. Så om servern är ett kluster med flera datorer multipliceras den faktiska telemetrivolymen i enlighet med detta.

   Läs mer om sampling.

   Telemetriprocessor för fast sampling (från 2.0.0-beta1)

   Det finns också en standardtelemetriprocessor för sampling (från 2.0.1):

       <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
   
        <!-- Set a percentage close to 100/N where N is an integer. -->
        <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
        <SamplingPercentage>10</SamplingPercentage>
        </Add>
      </TelemetryProcessors>
   

Exempelfilter

Syntetiska begäranden

Filtrera bort robotar och webbtester. Även om Metrics Explorer ger dig möjlighet att filtrera bort syntetiska källor, minskar det här alternativet trafik- och inmatningsstorleken genom att filtrera dem i själva SDK:t.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Autentiseringen misslyckades

Filtrera bort begäranden med svaret "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Filtrera bort snabba fjärrberoendeanrop

Om du bara vill diagnostisera anrop som är långsamma filtrerar du bort de snabba.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Provtagning

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Utöka data via HTTP

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Hantera SDK-komponenter

I det här avsnittet

• Telemetrikanaler
• Telemetrimoduler
• Inaktivera telemetri
• ApplicationId-provider
• Samling med ögonblicksbilder

Du kan anpassa Application Insights SDK för ASP.NET, ASP.NET Core och Worker Service för att ändra standardkonfigurationen.

Telemetrikanaler

Telemetrikanaler är en integrerad del av Application Insights SDK:er. De hanterar buffring och överföring av telemetri till Application Insights-tjänsten. .NET- och .NET Core-versionerna av SDK:erna har två inbyggda telemetrikanaler: InMemoryChannel och ServerTelemetryChannel. Det här avsnittet beskriver varje kanal och visar hur du anpassar kanalbeteendet.

Vad är telemetrikanaler?

Telemetrikanaler ansvarar för buffring av telemetriobjekt och skickar dem till Application Insights-tjänsten, där de lagras för frågor och analys. En telemetrikanal är alla klasser som implementerar Microsoft.ApplicationInsights.ITelemetryChannel gränssnittet.

Metoden Send(ITelemetry item) för en telemetrikanal anropas när alla telemetriinitierare och telemetriprocessorer anropas. Därför når inte alla objekt som tappas av en telemetriprocessor kanalen. Metoden Send() skickar vanligtvis inte objekten till serverdelen direkt. Vanligtvis buffrar den dem i minnet och skickar dem i batchar för effektiv överföring.

Undvik att anropa Flush() om det inte är viktigt att skicka buffrad telemetri omedelbart. Använd den bara i scenarier som programavstängning, undantagshantering eller när du använder kortvariga processer som bakgrundsjobb eller kommandoradsverktyg. I webbprogram eller långvariga tjänster hanterar SDK telemetri som skickas automatiskt. Att ringa Flush() i onödan kan orsaka prestandaproblem.

Live Metrics Stream har också en anpassad kanal som driver direktuppspelning av telemetri. Den här kanalen är oberoende av den vanliga telemetrikanalen och det här dokumentet gäller inte för den.

Inbyggda telemetrikanaler

Application Insights .NET och .NET Core SDK:er levereras med två inbyggda kanaler:

• InMemoryChannel: En lätt kanal som buffrar objekt i minnet tills de skickas. Objekt buffrad i minnet och töms en gång var 30:e sekund, eller när 500 objekt buffrats. Den här kanalen ger minimala tillförlitlighetsgarantier eftersom den inte försöker skicka telemetri igen efter ett fel. Den här kanalen behåller inte heller objekt på disken. Så alla osedda objekt går förlorade permanent vid programavstängning, oavsett om det är graciöst eller inte. Den här kanalen implementerar en Flush() metod som kan användas för att tvinga bort alla minnesinterna telemetriobjekt synkront. Den här kanalen passar bra för kortvariga program där en synkron tömning är idealisk.

  Den här kanalen är en del av det större Microsoft.ApplicationInsights NuGet-paketet och är standardkanalen som SDK använder när inget annat har konfigurerats.

• ServerTelemetryChannel: En mer avancerad kanal som har återförsöksprinciper och möjligheten att lagra data på en lokal disk. Den här kanalen försöker skicka telemetri igen om tillfälliga fel inträffar. Den här kanalen använder också lokal disklagring för att hålla objekt på disk under nätverksstopp eller stora telemetrivolymer. På grund av dessa mekanismer för återförsök och lokal disklagring anses den här kanalen vara mer tillförlitlig. Vi rekommenderar det för alla produktionsscenarier. Den här kanalen är standard för ASP.NET och ASP.NET Core-program som konfigureras enligt den officiella dokumentationen. Den här kanalen är optimerad för serverscenarier med tidskrävande processer. Metoden Flush() som implementeras av den här kanalen är inte synkron.

  Den här kanalen levereras som NuGet-paketet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel och hämtas automatiskt när du använder antingen Microsoft.ApplicationInsights.Web eller Microsoft.ApplicationInsights.AspNetCore NuGet-paketet.

Konfigurera en telemetrikanal

Du konfigurerar en telemetrikanal genom att ställa in den på den aktiva telemetrikonfigurationen. För ASP.NET program innebär konfigurationen att du ställer in telemetrikanalinstansen till eller genom att TelemetryConfiguration.ActiveApplicationInsights.configändra . För ASP.NET Core-program innebär konfigurationen att du lägger till kanalen i containern för beroendeinmatning.

I följande avsnitt visas exempel på hur du konfigurerar StorageFolder inställningen för kanalen i olika programtyper. StorageFolder är bara en av de konfigurerbara inställningarna. En fullständig lista över konfigurationsinställningar finns i avsnittet Konfigurerbara inställningar i kanaler senare i den här artikeln.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

Konfiguration i kod för konsolprogram

För konsolappar är koden densamma för både .NET och .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Driftinformation om ServerTelemetryChannel

ServerTelemetryChannel lagrar ankommande objekt i en minnesintern buffert. Objekten serialiseras, komprimeras och lagras i en instans en Transmission gång var 30:e sekund eller när 500 objekt buffras. En enskild Transmission instans innehåller upp till 500 objekt och representerar en batch telemetri som skickas via ett enda HTTPS-anrop till Application Insights-tjänsten.

Som standard kan högst 10 Transmission instanser skickas parallellt. Om telemetrin anländer snabbare, eller om nätverket eller Application Insights-serverdelen är långsam, Transmission lagras instanser i minnet. Standardkapaciteten för den här minnesinterna Transmission bufferten är 5 MB. När minnesintern kapacitet överskrids Transmission lagras instanser på en lokal disk upp till en gräns på 50 MB.

Transmission instanser lagras på den lokala disken även när det finns nätverksproblem. Endast de objekt som lagras på en lokal disk överlever en programkrasch. De skickas när programmet startar igen. Om nätverksproblem kvarstår ServerTelemetryChannel använder du en exponentiell backoff-logik som sträcker sig från 10 sekunder till 1 timme innan du försöker skicka telemetri igen.

Konfigurerbara inställningar i kanaler

Den fullständiga listan över konfigurerbara inställningar för varje kanal finns i:

• InMemoryChannel
• ServerTelemetryChannel

Här är de vanligaste inställningarna för ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: Den maximala mängden minne, i byte, som används av kanalen för att buffrar överföringar i minnet. När den här kapaciteten nås lagras nya objekt direkt på den lokala disken. Standardvärdet är 5 MB. Att ange ett högre värde leder till mindre diskanvändning, men kom ihåg att objekt i minnet går förlorade om programmet kraschar.

• MaxTransmissionSenderCapacity: Det maximala antalet Transmission instanser som skickas till Application Insights samtidigt. Standardvärdet är 10. Den här inställningen kan konfigureras till ett högre tal, vilket vi rekommenderar när en stor mängd telemetri genereras. Hög volym inträffar vanligtvis under belastningstestning eller när samplingen är avstängd.

• StorageFolder: Den mapp som används av kanalen för att lagra objekt på disk efter behov. I Windows används antingen %LOCALAPPDATA% eller %TEMP% om ingen annan sökväg uttryckligen anges. I andra miljöer än Windows används som standard följande platser (i ordning): %TMPDIR%, /var/tmp/ eller /tmp/.

Vilken kanal ska jag använda?

Vi rekommenderar för ServerTelemetryChannel de flesta produktionsscenarier som omfattar långvariga program. Mer information om att rensa telemetri finns i om att använda Flush().

När ska du använda Flush()

Metoden Flush() skickar en buffrad telemetri omedelbart. Den bör dock endast användas i specifika scenarier.

Använd Flush() när:

• Programmet håller på att stängas av och du vill se till att telemetri skickas innan du avslutar.
• Du är i en undantagshanterare och måste garantera att telemetri levereras.
• Du skriver en kortvarig process som ett bakgrundsjobb eller CLI-verktyg som avslutas snabbt.

Undvik att använda Flush() i långvariga program, till exempel webbtjänster. SDK hanterar automatiskt buffring och överföring. Att anropa Flush() i onödan kan orsaka prestandaproblem och garanterar inte att alla data skickas, särskilt när du använder ServerTelemetryChannel, som inte spolas synkront.

Telemetrimoduler

Application Insights samlar automatiskt in telemetri om specifika arbetsbelastningar utan att användaren behöver manuell spårning.

Som standard är följande moduler för automatisk insamling aktiverade. Du kan inaktivera eller konfigurera dem för att ändra deras standardbeteende.

Konfigurera telemetrimoduler

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "keyhere";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Inaktivera telemetri

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Anslutningssträng

Den här inställningen avgör i vilken Application Insights-resurs dina data visas. Vanligtvis skapar du en separat resurs, med en separat anslutningssträng, för vart och ett av dina program.

Se Anslutningssträngar i Application Insights för kodexempel.

Om du till exempel vill ange anslutningssträngen dynamiskt för att skicka resultat från ditt program till olika resurser kan du utelämna anslutningssträngen från konfigurationsfilen och ange den i kod i stället.

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

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

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";

app.Run();

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
tc.TrackEvent("myEvent");
// ...

ApplicationId-provider

Syftet med den här providern är att söka efter ett program-ID baserat på en anslutningssträng. Program-ID ingår i RequestTelemetry och DependencyTelemetry används för att fastställa korrelation i portalen.

Den här funktionen är tillgänglig genom att ange TelemetryConfiguration.ApplicationIdProvider.

Gränssnitt: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Vi tillhandahåller två implementeringar i Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider och DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Den här omslutningen är för vårt profil-API. Den begränsar begäranden och cacheresultat. Den här providern inkluderas automatiskt när du installerar antingen Microsoft.ApplicationInsights.DependencyCollector eller Microsoft.ApplicationInsights.Web.

Klassen exponerar en valfri egenskap med namnet ProfileQueryEndpoint. Som standard är den inställd på https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Om du behöver konfigurera en proxy rekommenderar vi att du proxysöker basadressen och ser till att sökvägen innehåller /api/profiles/{0}/appId. Vid körning {0} ersätts med instrumentationsnyckeln för varje begäran.

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

Den här statiska providern förlitar sig på dina konfigurerade instrumentationsnyckel/program-ID-par.

Den här klassen har Defined egenskapen, som är en Dictionary<string,string> av instrumentationsnyckel/program-ID-par.

Den här klassen har den valfria egenskapen Next, som kan användas för att konfigurera en annan provider att använda när en anslutningssträng begärs som inte finns i konfigurationen.

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "InstrumentationKey_1", "ApplicationId_1" },
            { "InstrumentationKey_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Konfigurera ögonblicksbildsamling

Information om hur du konfigurerar insamling av ögonblicksbilder för ASP.NET- och ASP.NET Core-program finns i Aktivera ögonblicksbildsfelsökare för .NET-appar i Azure Service Fabric, Cloud Services och virtuella datorer.

Lägga till övervakning på klientsidan

De föregående avsnitten gav vägledning om metoder för att automatiskt och manuellt konfigurera övervakning på serversidan. Om du vill lägga till övervakning på klientsidan använder du JavaScript SDK på klientsidan. Du kan övervaka en webbsidas transaktioner på klientsidan genom att lägga till ett JavaScript-SDK-inläsningsskript (Web) före den avslutande </head> taggen för sidans HTML.

Även om det är möjligt att manuellt lägga till SDK-inläsningsskriptet för JavaScript (Web) i sidhuvudet på varje HTML-sida rekommenderar vi att du i stället lägger till JavaScript-SDK-inläsningsskriptet (Web) på en primär sida. Den åtgärden injicerar JavaScript (webb) SDK-laddningsskriptet i alla sidor på en webbplats.

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

Kärn-API för anpassade händelser och mått

Infoga några rader kod i programmet för att ta reda på vad användarna gör med det eller för att diagnostisera problem. Du kan skicka telemetri från enhets- och skrivbordsappar, webbklienter och webbservrar. Använd Application Insights-kärntelemetri-API:et för att skicka anpassade händelser och mått och dina egna versioner av standardtelemetri. Det här API:et är samma API som standarddatainsamlaren i Application Insights använder.

API-sammanfattning

Kärn-API:et är enhetligt på alla plattformar, förutom några varianter som GetMetric (endast.NET).

Du kan koppla egenskaper och mått till de flesta av dessa telemetrianrop.

Förutsättningar

Om du inte har någon referens för Application Insights SDK ännu:

1. Lägg till Application Insights SDK i projektet.

2. I din enhets- eller webbserverkod inkluderar du:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Hämta en TelemetryClient-instans

Hämta en instans av TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

TrackEvent

I Application Insights är en anpassad händelse en datapunkt som du kan visa i Metrics Explorer som ett aggregerat antal och i Diagnostiksökning som enskilda förekomster. (Det är inte relaterat till MVC eller andra ramverkshändelser.)

Infoga TrackEvent anrop i koden för att räkna olika händelser. Du kanske till exempel vill spåra hur ofta användare väljer en viss funktion. Eller så kanske du vill veta hur ofta de uppnår vissa mål eller gör specifika typer av misstag.

I en spelapp kan du till exempel skicka ett evenemang när en användare vinner spelet:

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

Anpassade händelser i Log Analytics

Telemetrin är tillgänglig i customEvents tabellen på fliken Application Insights-loggar eller användningsupplevelsen. Händelser kan komma från trackEvent(..) eller plugin-programmet Click Analytics Autocollection.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackEvent()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal anpassade händelser använder du kod som customEvents | summarize sum(itemCount).

GetMetric

Information om hur du effektivt använder anropet GetMetric() för att samla in lokalt föraggregerade mått för .NET- och .NET Core-program finns i Anpassad måttsamling i .NET och .NET Core.

TrackMetric

Application Insights kan kartlägga mått som inte är kopplade till vissa händelser. Du kan till exempel övervaka en kölängd med jämna mellanrum. Med mått är de enskilda mätningarna av mindre intresse än variationerna och trenderna, och därför är statistiska diagram användbara.

Om du vill skicka mått till Application Insights kan du använda API:et TrackMetric(..) . Det finns två sätt att skicka ett mått:

• Enskilt värde. Varje gång du utför en mätning i ditt program skickar du motsvarande värde till Application Insights.

  Anta till exempel att du har ett mått som beskriver antalet objekt i en container. Under en viss tidsperiod placerar du först tre objekt i containern och tar sedan bort två objekt. Därför skulle du ringa TrackMetric två gånger. Först skickar du värdet 3 och skickar sedan värdet -2. Application Insights lagrar båda värdena åt dig.

• Aggregat. När du arbetar med mått är varje enskild mätning sällan av intresse. I stället är en sammanfattning av vad som hände under en viss tidsperiod viktig. En sådan sammanfattning kallas aggregering.

  I föregående exempel är 1 den aggregerade måttsumman för den tidsperioden och antalet måttvärden är 2. När du använder aggregeringsmetoden anropar TrackMetric du bara en gång per tidsperiod och skickar aggregeringsvärdena. Vi rekommenderar den här metoden eftersom den avsevärt kan minska kostnaderna och prestandakostnaderna genom att skicka färre datapunkter till Application Insights, samtidigt som all relevant information samlas in.

Exempel med ett enda värde

Så här skickar du ett enda måttvärde:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

Anpassade mått i Log Analytics

Telemetrin är tillgänglig i customMetrics tabellen i Application Insights Analytics. Varje rad representerar ett anrop till trackMetric(..) i din app.

• valueSum: Summan av mätningarna. Om du vill hämta medelvärdet dividerar du med valueCount.
• valueCount: Antalet mått som aggregerades i det här trackMetric(..) anropet.

Sidvisningar

I en enhets- eller webbsidaapp skickas telemetri för sidvisning som standard när varje skärm eller sida läses in. Men du kan ändra standardvärdet för att spåra sidvisningar vid fler eller olika tidpunkter. I en app som till exempel visar flikar eller fönster kanske du vill spåra en sida när användaren öppnar ett nytt fönster.

Användar- och sessionsdata skickas som egenskaper tillsammans med sidvyer, så användar- och sessionsdiagram kommer till liv när det finns telemetri för sidvisning.

Anpassade sidvyer

telemetry.TrackPageView("GameReviewPage");

Sidtelemetri i Log Analytics

I Log Analytics visar två tabeller data från webbläsaråtgärder:

• pageViews: Innehåller data om URL:en och sidrubriken.
• browserTimings: Innehåller data om klientprestanda som den tid det tar att bearbeta inkommande data.

För att ta reda på hur lång tid det tar för webbläsaren att bearbeta olika sidor:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Så här upptäcker du populariteten för olika webbläsare:

pageViews
| summarize count() by client_Browser

Koppla sidvisningar till AJAX-anrop genom att ansluta till beroenden:

pageViews
| join (dependencies) on operation_Id

TrackRequest

Server-SDK:t använder TrackRequest för att logga HTTP-begäranden.

Du kan också anropa det själv om du vill simulera begäranden i en kontext där du inte har webbtjänstmodulen igång.

Det rekommenderade sättet att skicka telemetri för begäran är när begäran fungerar som en åtgärdskontext.

Åtgärdskontext

Du kan korrelera telemetriobjekt genom att associera dem med åtgärdskontexten. Standardmodulen för spårning av begäranden gör det för undantag och andra händelser som skickas medan en HTTP-begäran bearbetas. I Sök och Analys kan du enkelt hitta alla händelser som är associerade med begäran med hjälp av dess åtgärds-ID.

När du spårar telemetri manuellt är det enklaste sättet att säkerställa telemetrikorrelation genom att använda det här mönstret:

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Tillsammans med att ange en åtgärdskontext StartOperation skapar ett telemetriobjekt av den typ som du anger. Den skickar telemetriobjektet när du tar bort åtgärden eller om du uttryckligen anropar StopOperation. Om du använder RequestTelemetry som telemetrityp är dess varaktighet inställd på det tidsintervall mellan start och stopp.

Telemetriobjekt som rapporteras inom ett driftsområde blir underordnade objekt till en sådan operation. Åtgärdskontexter kan kapslas.

I Sök används åtgärdskontexten för att skapa listan Relaterade objekt .

Mer information om spårning av anpassade åtgärder finns i Spåra anpassade åtgärder med Application Insights .NET SDK.

Begäranden i Log Analytics

I Application Insights Analytics visas begäranden i requests tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackRequest()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal begäranden och genomsnittlig varaktighet segmenterade efter begärandenamn använder du kod som:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Skicka undantag till Application Insights:

• Att räkna dem, som en indikation på frekvensen för ett problem.
• För att undersöka enskilda förekomster.

Rapporterna innehåller stackspårningsinformation.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK:erna fångar upp många undantag automatiskt, så du behöver inte alltid anropa TrackException explicit.

Undantag i Log Analytics

I Application Insights Analytics visas undantag i exceptions tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackException()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal undantag segmenterade efter typ av undantag använder du kod som:

exceptions
| summarize sum(itemCount) by type

Det mesta av den viktiga stackinformationen extraheras redan i separata variabler, men du kan dra isär details strukturen för att få mer. Eftersom den här strukturen är dynamisk bör du omvandla resultatet till den typ du förväntar dig. Till exempel:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Om du vill associera undantag med deras relaterade begäranden använder du en koppling:

exceptions
| join (requests) on operation_Id

TrackTrace

Använd TrackTrace för att diagnostisera problem genom att skicka en "breadcrumb trail" till Application Insights. Du kan skicka delar av diagnostikdata och inspektera dem i Diagnostiksökning.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Logga en diagnostikhändelse som att ange eller lämna en metod.

Du kan söka efter meddelandeinnehåll, men till skillnad från egenskapsvärden kan du inte filtrera på det.

Storleksgränsen på message är mycket högre än gränsen för egenskaper. En fördel TrackTrace med är att du kan placera relativt långa data i meddelandet. Du kan till exempel koda POST-data där.

Du kan också lägga till en allvarlighetsgrad i meddelandet. Och precis som andra telemetrier kan du lägga till egenskapsvärden som hjälper dig att filtrera eller söka efter olika uppsättningar spårningar. Till exempel:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

I Sök kan du sedan enkelt filtrera bort alla meddelanden på en viss allvarlighetsnivå som är relaterade till en viss databas.

Spårningar i Log Analytics

I Application Insights Analytics visas anrop till TrackTrace i traces-tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackTrace()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal spårningsanrop använder du kod som traces | summarize sum(itemCount).

TrackDependency

Använd anropet TrackDependency för att spåra svarstiderna och framgångsfrekvensen för anrop till en extern kod. Resultaten visas i beroendediagrammen i portalen. Följande kodfragment måste läggas till varhelst ett beroendeanrop görs.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Kom ihåg att server-SDK:erna innehåller en beroendemodul som identifierar och spårar vissa beroendeanrop automatiskt, till exempel till databaser och REST-API:er. Du måste installera en agent på servern för att modulen ska fungera.

Du använder det här anropet om du vill spåra anrop som den automatiserade spårningen inte fångar upp.

Om du vill inaktivera standardmodulen för beroendespårning i C# redigerar duApplicationInsights.config och tar bort referensen till DependencyCollector.DependencyTrackingTelemetryModule.

Beroenden i Log Analytics

I Application Insights AnalyticstrackDependency visas anrop upp i dependencies tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackDependency()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal beroenden segmenterade efter målkomponent använder du kod som:

dependencies
| summarize sum(itemCount) by target

Om du vill associera beroenden med deras relaterade begäranden använder du en sammanfogning:

dependencies
| join (requests) on operation_Id

Rensa data

Normalt skickar SDK:t data med fasta intervall, vanligtvis 30 sekunder, eller när bufferten är full, vilket vanligtvis är 500 objekt. I vissa fall kanske du vill tömma bufferten. Ett exempel är om du använder SDK:t i ett program som stängs av.

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

await telemetryClient.FlushAsync()
// No need to sleep

telemetry.flush();

Autentiserade användare

I en webbapp identifieras användare som standard med cookies . En användare kan räknas mer än en gång om de kommer åt din app från en annan dator eller webbläsare, eller om de tar bort cookies.

Om användarna loggar in på din app kan du få ett mer exakt antal genom att ange det autentiserade användar-ID:t i webbläsarkoden. Det är inte nödvändigt att använda användarens faktiska inloggningsnamn. Det behöver bara vara ett ID som är unikt för den användaren. Den får inte innehålla mellanslag eller någon av tecknen ,;=|.

Användar-ID:t anges också i en sessionscookie och skickas till servern. Om server-SDK:t är installerat skickas det autentiserade användar-ID:t som en del av kontextegenskaperna för både klient- och servertelemetri. Du kan sedan filtrera och söka på den.

Om appen grupperar användare till konton kan du också skicka en identifierare för kontot. Samma teckenbegränsningar gäller.

I Metrics Explorer kan du skapa ett diagram som räknar användare, autentiserade och användarkonton.

Du kan också söka efter klientdatapunkter med specifika användarnamn och konton.

Filtrera, söka efter och segmentera dina data med hjälp av egenskaper

Du kan koppla egenskaper och mått till dina händelser, mått, sidvisningar, undantag och andra telemetridata.

Egenskaper är strängvärden som du kan använda för att filtrera telemetrin i användningsrapporterna. Om din app till exempel tillhandahåller flera spel kan du koppla namnet på spelet till varje händelse så att du kan se vilka spel som är mer populära.

Det finns en gräns på 8 192 för stränglängden. Om du vill skicka stora datasegment använder du meddelandeparametern TrackTraceför .

Mått är numeriska värden som kan visas grafiskt. Du kanske till exempel vill se om det sker en gradvis ökning av poängen som dina spelare uppnår. Graferna kan segmenteras efter de egenskaper som skickas med händelsen så att du kan få separata eller staplade grafer för olika spel.

Måttvärdena ska vara större än eller lika med 0 för att visas korrekt.

Det finns vissa begränsningar för antalet egenskaper, egenskapsvärden och mått som du kan använda.

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Alternativt sätt att ange egenskaper och mått

Om det är enklare kan du samla in parametrarna för en händelse i ett separat objekt:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Anpassade mått och egenskaper i Log Analytics

I Log Analytics visas anpassade mått och egenskaper i attributen customMeasurements och customDimensions för varje telemetripost.

Om du till exempel lägger till en egenskap med namnet "game" i din begärans telemetri räknar frågan förekomsterna av olika värden av "game" och visar medelvärdet av det anpassade måttet "score".

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Observera att:

• När du extraherar ett värde från customDimensions eller customMeasurements JSON har det en dynamisk typ, så du måste omvandla det tostring eller todouble.
• Om du vill ta hänsyn till möjligheten till sampling ska du inte sum(itemCount)använda count() .

Tidshändelser

Ibland vill du visa hur lång tid det tar att utföra en åtgärd. Du kanske till exempel vill veta hur lång tid det tar för användarna att överväga val i ett spel. Använd måttparametern för att hämta den här informationen.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Standardegenskaper för anpassad telemetri

Om du vill ange standardegenskapsvärden för några av de anpassade händelser som du skriver anger du dem i en TelemetryClient instans. De är kopplade till varje telemetriobjekt som skickas från klienten.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Enskilda telemetrianrop kan åsidosätta standardvärdena i sina egenskapsordlistor.

Om du vill lägga till egenskaper för all telemetri, inklusive data från standardsamlingsmoduler, implementerar du ITelemetryInitializer.

Inaktivera telemetri

För att dynamiskt stoppa och starta insamling och överföring av telemetri:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Utvecklarläge

När du felsöker är det fördelaktigt att telemetrin skickas snabbare genom bearbetningskedjan så att du kan se resultaten omedelbart. Du får även andra meddelanden som hjälper dig att spåra eventuella problem med telemetrin. Stäng av den i produktion eftersom den kan göra din app långsammare.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Ange instrumentationsnyckeln för vald anpassad telemetri

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Dynamisk anslutningssträng

För att undvika att blanda telemetri från utvecklings-, test- och produktionsmiljöer kan du skapa separata Application Insights-resurser och ändra deras nycklar beroende på miljön.

I stället för att hämta instrumentationsnyckeln från konfigurationsfilen kan du ange den i koden. Ange nyckeln i en initieringsmetod, till exempel global.aspx.cs i en ASP.NET tjänst:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetriContext

TelemetryClient har en kontextegenskap som innehåller värden som skickas tillsammans med alla telemetridata. De anges normalt av standardtelemetrimodulerna, men du kan också ange dem själv. Till exempel:

telemetry.Context.Operation.Name = "MyOperationName";

Om du anger något av dessa värden själv kan du överväga att ta bort relevant rad från ApplicationInsights.config så att dina värden och standardvärdena inte blir förvirrade.

• Komponent: Appen och dess version.
• Enhet: Data om enheten där appen körs. I webbappar är det den server eller klientenhet som telemetrin skickas från.
• InstrumentationKey: Application Insights-resursen i Azure där telemetrin visas. Den hämtas vanligtvis från ApplicationInsights.config.
• Plats: Enhetens geografiska plats.
• Åtgärd: I webbappar, den aktuella HTTP-begäran. I andra apptyper kan du ange det här värdet för att gruppera händelser tillsammans.
  • ID: Ett genererat värde som korrelerar olika händelser så att du kan hitta relaterade objekt när du inspekterar en händelse i Diagnostiksökning.
  • Namn: En identifierare, vanligtvis URL:en för HTTP-begäran.
  • SyntheticSource: Om den inte är null eller tom har en sträng som anger att källan till begäran har identifierats som en robot eller ett webbtest. Som standard undantas den från beräkningar i Metrics Explorer.
• Session: Användarens session. ID:t är inställt på ett genererat värde som ändras när användaren inte har varit aktiv på ett tag.
• Användare: Användarinformation.

Gränser

Det finns vissa gränser för antalet mått och händelser per program, dvs. per instrumentationsnyckel. Gränserna beror på vilken prisplan du väljer.

Mer information om priser och kvoter finns i Application Insights-fakturering.

Om du vill undvika att nå datahastighetsgränsen använder du sampling.

Information om hur länge data sparas finns i Datakvarhållning och sekretess.

Exempelapplikationer

.NET Core-konsolprogram: Använd det här exemplet om du använder ett konsolprogram som skrivits i .NET Core (2.0 eller senare) eller .NET Framework (4.7.2 eller senare).

ASP.NET Grundläggande bakgrundsaktiviteter med HostedServices: Använd det här exemplet om du är i ASP.NET Core och skapar bakgrundsuppgifter i enlighet med officiell vägledning.

.NET Core Worker Service: Använd det här exemplet om du har ett .NET Worker Service-program i enlighet med officiell vägledning.

Felsökning

Se den dedikerade felsökningsartikeln.

Testa anslutningen mellan din applikationsvärd och insamlingstjänsten

Application Insights SDK:er och agenter skickar telemetri för att matas in som REST-anrop till våra inmatningsslutpunkter. Du kan testa anslutningen från webbservern eller programvärddatorn till slutpunkterna för inmatningstjänsten med hjälp av råa REST-klienter från PowerShell- eller curl-kommandon. Se Felsöka programtelemetri som saknas i Azure Monitor Application Insights.

SDK med öppen källkod

Läsa och bidra till koden.

För de senaste uppdateringarna och buggfixarna, se releasenoterna.

Versionsanteckningar

För version 2.12 och senare: .NET Programvaruutvecklingskit (SDK:er) inklusive ASP.NET, ASP.NET Core och loggningsadaptrar

Våra tjänstuppdateringar sammanfattar även större Förbättringar av Application Insights.

Nästa steg

• Mer information om vanliga frågor och svar finns i:
  • Vanliga frågor och svar om Applications Insights för ASP.NET
  • Vanliga frågor och svar om Application Insights för ASP.NET Core
  • Vanliga frågor och svar om Worker Service-program
  • Vanliga frågor och svar om Application Insights API för anpassade händelser och mått
• Kontrollera att du kör en version av Application Insights SDK som stöds .
• Se datamodellen för Application Insights-typer och datamodeller.
• Lägg till syntetiska transaktioner för att testa att din webbplats är tillgänglig från hela världen med tillgänglighetsövervakning.
• Kontrollera användarhandboken för System.Diagnostics.Activity för att se hur vi korrelerar telemetri.
• Konfigurera en samling ögonblicksbilder för att se tillståndet för källkod och variabler när ett undantag utlöses.

Referensdokument

• Referens för datatyper för ASP.NET SDK och ASP.NET Core SDK.
• SDK-kod för ASP.NET SDK och ASP.NET Core SDK.