.NET-toepassingen en -services bewaken met Application Insights (klassieke API)

In dit artikel wordt uitgelegd hoe u Application Insights inschakelt en configureert voor toepassingen met ASP.NET, ASP.NET Core en Worker Service (niet-HTTP). Application Insights kan de volgende telemetrie van uw apps verzamelen:

Ondersteunde scenario’s

Application Insights toevoegen

Vereiste voorwaarden

Een eenvoudige webtoepassing maken

Als u nog geen werkende webtoepassing hebt, kunt u de volgende richtlijnen gebruiken om er een te maken.

Application Insights automatisch toevoegen (Visual Studio)

In deze sectie wordt u begeleid bij het automatisch toevoegen van Application Insights aan een web-app op basis van een sjabloon.

Application Insights handmatig toevoegen (geen Visual Studio)

In deze sectie wordt u begeleid bij het handmatig toevoegen van Application Insights aan een web-app op basis van een sjabloon.

Controleren of Application Insights telemetrie ontvangt

Telemetrie configureren

In deze sectie

• Live metrische gegevens
• Traceringen (logboeken)
• Gedistribueerde tracering
• Afhankelijkheden
• Uitzonderingen
• Aangepaste metrische gegevens
• Aangepaste bewerkingen

Live statistieken

Live statistieken kunnen worden gebruikt om snel te verifiëren of applicatiebewaking met Application Insights correct is geconfigureerd. Het kan enkele minuten duren voordat telemetrie wordt weergegeven in Azure Portal, maar in het deelvenster met livegegevens wordt het CPU-gebruik van het actieve proces bijna in realtime weergegeven. Er kunnen ook andere telemetriegegevens worden weergegeven, zoals aanvragen, afhankelijkheden en traceringen.

Live metrics inschakelen met behulp van code voor elke .NET-toepassing

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

Traceringen (logboeken)

In deze sectie wordt uitgelegd hoe u logboeken voor diagnostische tracering verzendt vanuit ASP.NET of ASP.NET Core-toepassingen naar Application Insights en deze logboeken vervolgens verkent/doorzoekt in de portal.

U kunt traceringslogboeken gebruiken om traceringen te identificeren die zijn gekoppeld aan elke gebruikersaanvraag en deze te correleren met andere gebeurtenissen en uitzonderingsrapporten.

Application Insights legt logboeken van ASP.NET Core en andere .NET-apps vast via ILogger en van klassieke ASP.NET (.NET Framework) via de klassieke SDK en adapters.

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

Handmatige installatie

Gebruik deze methode als uw projecttype niet wordt ondersteund door het Application Insights-installatieprogramma (bijvoorbeeld sommige bureaublad-/consolescenario's) of als u liever expliciet besturingselement op pakketniveau gebruikt.

1. Klik in Solution Explorer met de rechtermuisknop op uw project en selecteer NuGet-pakketten beheren.

2. Zoek naar Application Insights.

3. Selecteer een van de volgende pakketten:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListener
   • log4net: Microsoft.ApplicationInsights.Log4NetAppenderNuGet Log4Net banner
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Microsoft.ApplicationInsights.EventSourceListener Banner
   • Microsoft.ApplicationInsights.DiagnosticSourceListener banner
   • Microsoft.ApplicationInsights.EtwCollector

Het NuGet-pakket installeert de benodigde assembly's en wijzigt web.config of app.config, indien van toepassing.

Installatie-instructies:

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>

De tracerings-API rechtstreeks gebruiken

U kunt de Application Insights-tracerings-API rechtstreeks aanroepen. De logboekregistratieadapters gebruiken deze API. Voorbeeld:

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

Een voordeel hiervan TrackTrace is dat u relatief lange gegevens in het bericht kunt plaatsen. U kunt bijvoorbeeld POST-gegevens daar coderen.

U kunt ook een ernstniveau toevoegen aan uw bericht. En net als andere telemetrie kunt u eigenschapswaarden toevoegen om verschillende sets traceringen te filteren of te zoeken. Voorbeeld:

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

U kunt nu eenvoudig filteren in Transaction Search alle berichten van een bepaald ernstniveau die betrekking hebben op een bepaalde database.

Console-applicatie

Als u Application Insights-logboekregistratie wilt toevoegen aan consoletoepassingen, moet u eerst de volgende NuGet-pakketten installeren:

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

In het volgende voorbeeld wordt het Microsoft.Extensions.Logging.ApplicationInsights pakket gebruikt en wordt het standaardgedrag voor een consoletoepassing gedemonstreert. Het Microsoft.Extensions.Logging.ApplicationInsights pakket moet worden gebruikt in een consoletoepassing of wanneer u een minimale implementatie van Application Insights wilt zonder de volledige functieset, zoals metrische gegevens, gedistribueerde tracering, sampling en telemetrie-initialisatie.

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

Zie Voor meer informatie welk Type Application Insights-telemetrie wordt geproduceerd uit ILogger-logboeken? Waar zie ik ILogger-logboeken in Application Insights?

Bereiken voor logboekregistratie

ApplicationInsightsLoggingProvider ondersteunt logboekbereiken, die standaard zijn ingeschakeld.

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

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

Als een ander type wordt gebruikt als een bereik, wordt het opgeslagen onder de eigenschap Scope in Application Insights-telemetrie. In het volgende voorbeeld TraceTelemetry heeft u een eigenschap Scope die het bereik bevat.

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

Uw logboeken zoeken

Voer uw app uit in de foutopsporingsmodus of implementeer deze live.

Verken in Transactiezoeker

Selecteer in het overzichtsvenster van uw app in de Application Insights-portal de optie Transaction Search , waar u het volgende kunt doen:

• Filter op logboektraceringen of op items met specifieke eigenschappen.
• Inspecteer een specifiek item in detail.
• Zoek andere systeemlogboekgegevens die betrekking hebben op dezelfde gebruikersaanvraag (heeft dezelfde bewerkings-id).
• Sla de configuratie van een pagina op als favoriet.

Verkennen in Azure Monitor-logboeken

ILogger-logboeken worden weergegeven als traceringstelemetrie (tabel traces in Application Insights en AppTraces in Log Analytics).

Voorbeeld

Ga in Azure Portal naar Application Insights en voer het volgende uit:

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

Gedistribueerde tracering

Moderne architecturen voor cloud- en microservices hebben eenvoudige, onafhankelijk implementeerbare services ingeschakeld die de kosten verlagen en tegelijkertijd de beschikbaarheid en doorvoer verhogen. Het heeft echter al het hele systeem moeilijker gemaakt om te redeneren over en fouten op te sporen. Gedistribueerde tracering lost dit probleem op door een prestatieprofiel te bieden dat werkt als aanroepstacks voor cloud- en microservicesarchitecturen.

Azure Monitor biedt twee ervaringen voor het gebruik van gedistribueerde traceringsgegevens: de weergave voor transactiediagnose voor één transactie/aanvraag en de toepassingsoverzichtsweergave om te laten zien hoe systemen communiceren.

Application Insights kan elk onderdeel afzonderlijk bewaken en detecteren welk onderdeel verantwoordelijk is voor fouten of prestatievermindering met behulp van gedistribueerde telemetriecorrelatie. In dit artikel wordt het gegevensmodel, technieken voor contextdoorgifte, protocollen en implementatie van correlatietactieken uitgelegd op verschillende talen en platforms die worden gebruikt door Application Insights.

Gedistribueerde tracering inschakelen via Application Insights door middel van autoinstrumentatie of SDK's

De Application Insights-agents en SDK's voor .NET, .NET Core, Java, Node.jsen JavaScript ondersteunen allemaal systeemeigen gedistribueerde tracering.

Wanneer de juiste Application Insights SDK is geïnstalleerd en geconfigureerd, worden traceringsgegevens automatisch verzameld voor populaire frameworks, bibliotheken en technologieën door autocollectors voor SDK-afhankelijkheden. De volledige lijst met ondersteunde technologieën is beschikbaar in de documentatie voor automatisch verzamelen van afhankelijkheden.

Elke technologie kan ook handmatig worden bijgehouden met een aanroep naar TrackDependency op de TelemetryClient.

Gegevensmodel voor telemetriecorrelatie

Application Insights definieert een gegevensmodel voor gedistribueerde telemetriecorrelatie. Als u telemetrie wilt koppelen aan een logische bewerking, heeft elk telemetrie-item een contextveld met de naam operation_Id. Elk telemetrie-item in de gedistribueerde tracering deelt deze id. Zelfs als u telemetrie van één laag kwijtraakt, kunt u nog steeds telemetrie koppelen die door andere onderdelen is gerapporteerd.

Een gedistribueerde logische bewerking bestaat doorgaans uit een set kleinere bewerkingen die worden verwerkt door een van de onderdelen. Telemetrie van aanvragen definieert deze bewerkingen. Elk telemetrie-aanvraagitem heeft een eigen id dat het uniek en wereldwijd identificeert. En alle telemetrie-items (zoals traceringen en uitzonderingen) die aan de aanvraag zijn gekoppeld, moeten de operation_parentId instellen op de waarde van de aanvraag id.

Afhankelijkheidstelemetrie vertegenwoordigt elke uitgaande bewerking, zoals een HTTP-aanroep naar een ander onderdeel. Het definieert ook een eigen id dat wereldwijd uniek is. Telemetrieverzoek, geïnitieerd door deze afhankelijkheidsaanroep, gebruikt dit id als zijn operation_parentId.

U kunt een weergave van de gedistribueerde logische bewerking maken met behulp operation_Idvan , operation_parentIden request.id met dependency.id. Deze velden definiëren ook de causaliteitsvolgorde van telemetriegesprekken.

In een microservicesomgeving kunnen traceringen van onderdelen naar verschillende opslagitems gaan. Elk onderdeel kan een eigen verbindingsreeks hebben in Application Insights. Application Insights vraagt gegevens op uit elk opslagitem om telemetrie voor de logische bewerking op te halen.

Wanneer het aantal opslagitems groot is, hebt u een hint nodig over waar u hierna moet zoeken. Het Application Insights-gegevensmodel definieert twee velden om dit probleem op te lossen: request.source en dependency.target. Het eerste veld identificeert het onderdeel dat de afhankelijkheidsaanvraag heeft gestart. Het tweede veld identificeert welk onderdeel het antwoord van de afhankelijkheidsaanroep heeft geretourneerd.

Zie Querygegevens in Log Analytics-werkruimten, toepassingen en resources in Azure Monitor voor meer informatie over het uitvoeren van query's vanuit meerdere verschillende instanties.

Example

Laten we eens kijken naar een voorbeeld. In een toepassing met de naam Aandelenprijzen wordt de huidige marktkoers van een aandelen weergegeven met behulp van een externe API met de naam Aandelen. De toepassing Aandelenprijzen heeft een pagina met de naam Stock-pagina die de webbrowser van de client opent met behulp van GET /Home/Stock. De toepassing voert een query uit op de Stock-API met behulp van de HTTP-aanroep GET /api/stock/value.

U kunt de resulterende telemetrie analyseren door een query uit te voeren:

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

In de resultaten delen alle telemetrie-items de root operation_Id. Wanneer een Ajax-aanroep vanaf de pagina wordt gedaan, wordt er een nieuwe unieke id (qJSXU) toegewezen aan de telemetrie van de afhankelijkheid en wordt de id van de pageView gebruikt als operation_ParentId. De serveraanvraag gebruikt vervolgens de Ajax-id als operation_ParentId.

Wanneer de aanroep GET /api/stock/value naar een externe service wordt uitgevoerd, moet u de identiteit van die server weten, zodat u het veld op de dependency.target juiste manier kunt instellen. Wanneer de externe service geen ondersteuning biedt voor bewaking, target wordt deze ingesteld op de hostnaam van de service. Een voorbeeld is stock-prices-api.com. Maar als de service zichzelf identificeert door een vooraf gedefinieerde HTTP-header te retourneren, target bevat deze de service-identiteit waarmee Application Insights een gedistribueerde tracering kan maken door een query uit te voeren op telemetrie van die service.

Correlatieheaders met W3C TraceContext

Application Insights gaat over naar W3C Trace-Context, waarmee het volgende wordt gedefinieerd:

• traceparent: draagt de globaal unieke bewerkings-id en unieke id van de aanroep.
• tracestate: Draagt systeemspecifieke traceringscontext.

De nieuwste versie van de Application Insights SDK ondersteunt het Trace-Context-protocol, maar mogelijk moet u zich hiervoor aanmelden. (Achterwaartse compatibiliteit met het vorige correlatieprotocol van de Application Insights SDK wordt gehandhaafd.)

Het HTTP-correlatieprotocol, ook wel Request-Id genoemd, wordt afgeschaft. Dit protocol definieert twee headers:

• Request-Id: Draagt de Wereldwijd Unieke ID van de oproep.
• Correlation-Context: bevat de verzameling naam-waardeparen van de gedistribueerde traceringseigenschappen.

Application Insights definieert ook de extensie voor het HTTP-correlatieprotocol. Het maakt gebruik Request-Context van naam-waardeparen om de verzameling eigenschappen door te geven die door de directe beller of aanroeper worden gebruikt. De Application Insights SDK gebruikt deze header om de dependency.target velden en request.source velden in te stellen.

De W3C Trace-Context en Application Insights-gegevensmodellen worden op de volgende manier gemapt:

Zie het Application Insights-telemetriegegevensmodel voor meer informatie.

Ondersteuning voor gedistribueerde W3C-tracering inschakelen

Gedistribueerde tracering op basis van W3C TraceContext is standaard ingeschakeld in alle recente .NET Framework/.NET Core SDK's, samen met achterwaartse compatibiliteit met een verouderd Request-Id protocol.

Telemetriecorrelatie

Correlatie wordt standaard verwerkt bij het onboarden van een app. Er zijn geen speciale acties vereist.

.NET runtime ondersteunt gedistribueerde systemen met behulp van Activity en DiagnosticSource

De .NET SDK van Application Insights gebruikt DiagnosticSource en Activity om telemetrie te verzamelen en correleren.

Afhankelijkheden

Automatisch bijgehouden afhankelijkheden

Application Insights SDK's voor .NET en .NET Core worden geleverd met DependencyTrackingTelemetryModule, een telemetriemodule waarmee automatisch afhankelijkheden worden verzameld. De module DependencyTrackingTelemetryModule wordt geleverd als het NuGet-pakket Microsoft.ApplicationInsights.DependencyCollector en wordt automatisch meegenomen wanneer u het Microsoft.ApplicationInsights.Web NuGet-pakket of het Microsoft.ApplicationInsights.AspNetCore NuGet-pakket gebruikt.

DependencyTrackingTelemetryModule Op dit moment worden de volgende afhankelijkheden automatisch bijgehouden:

Als de afhankelijkheid niet automatisch wordt opgehaald, kunt u deze handmatig bijhouden met een aanroep voor afhankelijkheid bijhouden.

Zie Afhankelijkheidstracking in Application Insights voor meer informatie over de manier waarop afhankelijkheidstracking werkt.

Automatische afhankelijkheidstracering instellen in console-apps

Als u afhankelijkheden van .NET-console-apps automatisch wilt bijhouden, installeert u het NuGet-pakket Microsoft.ApplicationInsights.DependencyCollector en initialiseert u DependencyTrackingTelemetryModule:

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

Afhankelijkheden handmatig bijhouden

Voor de volgende voorbeelden van afhankelijkheden, die niet automatisch worden verzameld, is handmatig bijhouden vereist:

• Azure Cosmos DB wordt alleen automatisch bijgehouden als HTTP/HTTPS wordt gebruikt. TCP-modus wordt niet automatisch vastgelegd door Application Insights voor SDK-versies die ouder zijn dan 2.22.0-Beta1.
• Redis

Voor deze afhankelijkheden die niet automatisch door SDK worden verzameld, kunt u ze handmatig bijhouden met behulp van de TrackDependency-API die wordt gebruikt door de standaardmodules voor automatisch verzamelen.

Voorbeeld

Als u uw code bouwt met een assembly die u niet zelf hebt geschreven, kunt u alle aanroepen naar de code tijd geven. In dit scenario kunt u achterhalen welke bijdrage het levert aan uw reactietijden.

Als u wilt dat deze gegevens worden weergegeven in de afhankelijkheidsdiagrammen in Application Insights, verzendt u deze met behulp van TrackDependency:

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

U kunt ook de uitbreidingsmethoden TelemetryClient gebruiken en StartOperation, die kunnen worden gebruikt om afhankelijkheden handmatig bij te houden, StopOperation zoals wordt weergegeven in het bijhouden van uitgaande afhankelijkheden.

De standaardmodule voor het bijhouden van afhankelijkheden uitschakelen

Zie telemetriemodules voor meer informatie.

Geavanceerde SQL-tracering om een volledige SQL-query op te halen

Voor SQL-aanroepen wordt de naam van de server en database altijd verzameld en opgeslagen als de naam van de verzamelde DependencyTelemetry. Een ander veld, gegevens genoemd, kan de volledige SQL-querytekst bevatten.

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

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

In de voorgaande gevallen is de juiste manier om te valideren dat de instrumentatie-engine correct is geïnstalleerd door te valideren dat de SDK-versie van de verzamelde DependencyTelemetry versie is rddp. Het gebruik van rdddsd of rddf geeft aan dat afhankelijkheden worden verzameld via DiagnosticSource of EventSource callbacks, zodat de volledige SQL-query niet wordt vastgelegd.

Exceptions

Uitzonderingen in webtoepassingen kunnen worden gerapporteerd met Application Insights. U kunt mislukte aanvragen correleren met uitzonderingen en andere gebeurtenissen op zowel de client als de server, zodat u snel de oorzaken kunt diagnosticeren. In deze sectie leert u hoe u uitzonderingsrapportage instelt, expliciet uitzonderingen rapporteert, fouten diagnosticeert en meer.

Uitzonderingsrapportage instellen

U kunt Application Insights instellen om uitzonderingen te rapporteren die optreden op de server of de client. Afhankelijk van het platform waarop uw toepassing afhankelijk is, hebt u de juiste extensie of SDK nodig.

Fouten en uitzonderingen diagnosticeren

Aangepaste tracerings- en logboekgegevens

Als u diagnostische gegevens wilt ophalen die specifiek zijn voor uw app, kunt u code invoegen om uw eigen telemetriegegevens te verzenden. Uw aangepaste telemetrie- of logboekgegevens worden weergegeven in diagnostische zoekopdrachten naast de aanvraag, paginaweergave en andere automatisch verzamelde gegevens.

Met behulp van de Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, hebt u verschillende API's beschikbaar:

• TelemetryClient.TrackEvent wordt doorgaans gebruikt voor het bewaken van gebruikspatronen, maar de gegevens die worden verzonden, worden ook weergegeven onder Aangepaste gebeurtenissen in diagnostische zoekopdrachten. Gebeurtenissen hebben een naam en kunnen tekenreekseigenschappen en numerieke metrische gegevens bevatten waarop u uw diagnostische zoekopdrachten kunt filteren.
• TelemetryClient.TrackTrace hiermee kunt u langere gegevens, zoals POST-informatie, verzenden.
• TelemetryClient.TrackException verzendt uitzonderingsdetails, zoals stacktraceringen naar Application Insights.

Als u deze gebeurtenissen wilt zien, opent u Zoeken in het linkermenu. Selecteer de vervolgkeuzelijst Gebeurtenistypen en kies vervolgens Aangepaste gebeurtenis, Tracering of Uitzondering.

Post-gegevens aanvragen bekijken

Aanvraagdetails bevatten niet de gegevens die naar uw app worden verzonden in een POST-aanroep. Ga als volgt te werk om deze gegevens te laten melden:

• Voeg de Application Insights SDK toe aan uw app-code.
• Voeg code in uw toepassing in om Microsoft.ApplicationInsights.TrackTrace() aan te roepen. Verzend de POST-gegevens in de berichtparameter. Er is een limiet voor de toegestane grootte, dus probeer alleen de essentiële gegevens te verzenden.
• Wanneer u een mislukte aanvraag onderzoekt, zoekt u de bijbehorende traceringen.

Uitzonderingen en gerelateerde diagnostische gegevens vastleggen

Standaard worden niet alle uitzonderingen die fouten veroorzaken in uw app weergegeven in de portal. Als u de JavaScript SDK op uw webpagina's gebruikt, ziet u browseronderzonderingen. De meeste uitzonderingen aan de serverzijde worden echter onderschept door IIS, dus u moet code toevoegen om ze vast te leggen en te rapporteren.

U kunt:

• Logboekuitzondering expliciet door code in uitzonderingshandlers in te voegen om de uitzonderingen te rapporteren.
• Maak automatisch uitzonderingen door uw ASP.NET framework te configureren. De benodigde toevoegingen zijn verschillend voor verschillende typen frameworks.

Expliciet uitzonderingen rapporteren

De eenvoudigste manier om te rapporteren is door een aanroep in trackException() te voegen in een uitzonderingshandler.

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

De eigenschappen en maatparameters zijn optioneel, maar ze zijn handig voor het filteren en toevoegen van extra informatie. Als u bijvoorbeeld een app hebt die meerdere games kan uitvoeren, kunt u alle uitzonderingsrapporten vinden die betrekking hebben op een bepaalde game. U kunt zoveel items toevoegen als u aan elke woordenlijst wilt toevoegen.

Browser-uitzonderingen

De meeste browseruitzondering worden gerapporteerd.

Als uw webpagina scriptbestanden bevat van netwerken voor contentlevering of andere domeinen, controleert u of uw scripttag het kenmerk crossorigin="anonymous" heeft en of de server CORS-headers verzendt. Met dit gedrag kunt u een stacktracering en details ophalen voor niet-verwerkte JavaScript-uitzonderingen van deze resources.

Uw telemetrieclient opnieuw gebruiken

Met afhankelijkheidsinjectie (DI) in .NET, de juiste .NET SDK en de juiste configuratie van Application Insights voor DI, kunt u de TelemetryClient parameter als constructor vereisen.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

In het voorgaande voorbeeld wordt de TelemetryClient in de ExampleController klasse geïnjecteerd.

Webformulieren

Voor webformulieren kan de HTTP-module de uitzonderingen verzamelen wanneer er geen omleidingen zijn geconfigureerd met CustomErrors. Wanneer u echter actieve omleidingen hebt, voegt u de volgende regels toe aan de Application_Error functie in Global.asax.cs.

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

In het voorgaande voorbeeld is het _telemetryClient een variabele met klassebereik van het type TelemetryClient.

MVC

Vanaf Application Insights Web SDK versie 2.6 (bèta 3 en hoger) verzamelt Application Insights automatisch niet-verwerkte uitzonderingen die zijn gegenereerd in de MVC 5+-controllersmethoden. Als u eerder een aangepaste handler hebt toegevoegd om dergelijke uitzonderingen bij te houden, kunt u deze verwijderen om dubbele tracering van uitzonderingen te voorkomen.

Er zijn verschillende scenario's waarin een uitzonderingsfilter fouten niet correct kan verwerken wanneer er uitzonderingen worden gegenereerd:

• Van controllerconstructors
• Van berichthandlers
• Tijdens routering
• Tijdens serialisatie van antwoordinhoud
• Tijdens het opstarten van de toepassing
• Achtergrondtaken

Alle uitzonderingen die door de toepassing worden verwerkt, moeten nog steeds handmatig worden bijgehouden. Niet-verwerkte uitzonderingen die afkomstig zijn van controllers resulteren doorgaans in een reactie van 500 'Interne serverfout'. Als een dergelijk antwoord handmatig is samengesteld als gevolg van een verwerkte uitzondering of helemaal geen uitzondering, wordt deze bijgehouden in de bijbehorende aanvraagtelemetrie met ResultCode 500. De Application Insights SDK kan echter geen overeenkomstige uitzondering bijhouden.

Ondersteuning voor eerdere versies

Als u MVC 4 (en eerder) van Application Insights Web SDK 2.5 (en eerder) gebruikt, raadpleegt u de volgende voorbeelden om uitzonderingen bij te houden.

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

Web-API

Vanaf Application Insights Web SDK versie 2.6 (bèta 3 en hoger) verzamelt Application Insights niet-verwerkte uitzonderingen die automatisch worden gegenereerd in de controllermethoden voor Web API 2+. Als u eerder een aangepaste handler hebt toegevoegd om dergelijke uitzonderingen bij te houden, zoals beschreven in de volgende voorbeelden, kunt u deze verwijderen om dubbele tracering van uitzonderingen te voorkomen.

Er zijn verschillende gevallen die de uitzonderingsfilters niet kunnen verwerken. Voorbeeld:

• Uitzonderingen die zijn gegenereerd door controllerconstructors.
• Uitzonderingen die zijn gegenereerd door berichtenhandlers.
• Uitzonderingen die zijn opgetreden tijdens de routering.
• Uitzonderingen die zijn opgetreden tijdens de serialisatie van antwoordinhoud.
• Er is een uitzondering opgetreden tijdens het opstarten van de toepassing.
• Er is een uitzondering opgetreden in achtergrondtaken.

Alle uitzonderingen die door de toepassing worden verwerkt, moeten nog steeds handmatig worden bijgehouden. Niet-verwerkte uitzonderingen die afkomstig zijn van controllers resulteren doorgaans in een reactie van 500 'Interne serverfout'. Als een dergelijk antwoord handmatig wordt samengesteld als gevolg van een verwerkte uitzondering of helemaal geen uitzondering, wordt deze bijgehouden in een bijbehorende aanvraagtelemetrie met ResultCode 500. De Application Insights SDK kan echter geen bijbehorende uitzondering bijhouden.

Ondersteuning voor eerdere versies

Als u Web API 1 (en eerder) van Application Insights Web SDK 2.5 (en eerder) gebruikt, raadpleegt u de volgende voorbeelden om uitzonderingen bij te houden.

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

Voeg een klasse toe die wordt uitgebreid Attribute en geïmplementeerd IErrorHandler en 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)
        {
        }
      }
    }

Voeg het kenmerk toe aan de service-implementaties:

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

voorbeeld

Prestatiemeteritems voor uitzonderingen

Als u de Azure Monitor Application Insights-agent op uw server hebt geïnstalleerd, kunt u een grafiek ophalen van de frequentie van uitzonderingen die worden gemeten door .NET. Zowel verwerkte als niet-verwerkte .NET-uitzonderingen zijn opgenomen.

Open het tabblad Metrics Explorer en voeg een nieuwe grafiek toe. Selecteer onder Prestatiemeteritemsde uitzonderingsfrequentie.

Het .NET Framework berekent de snelheid door het aantal uitzonderingen in een interval te tellen en te delen door de lengte van het interval.

Dit aantal verschilt van het aantal uitzonderingen dat wordt berekend door de rapporten voor het tellen van TrackException de Application Insights-portal. De steekproefintervallen verschillen en de SDK verzendt TrackException geen rapporten voor alle verwerkte en niet-verwerkte uitzonderingen.

Aangepaste verzameling metrische gegevens

De Azure Monitor Application Insights .NET- en .NET Core SDK's hebben twee verschillende methoden voor het verzamelen van aangepaste metrische gegevens:

• De TrackMetric() methode, die geen vooraggregatie heeft.
• De GetMetric() methode, die vooraf is samengevoegd.

We raden u aan aggregatie te gebruiken, dus TrackMetric()is niet langer de voorkeursmethode voor het verzamelen van aangepaste metrische gegevens. In dit artikel wordt u begeleid bij het gebruik van de GetMetric() methode en een aantal van de logica achter de werking ervan.

Aan de slag met GetMetric

Voor onze voorbeelden gebruiken we een eenvoudige .NET Core 3.1-werkservicetoepassing. Als u de testomgeving wilt repliceren die met deze voorbeelden wordt gebruikt, volgt u stap 1-6 onder de toepassing .NET Core Worker Service. Met deze stappen voegt u Application Insights toe aan een sjabloon voor een basiswerkserviceproject. De concepten zijn van toepassing op elke algemene toepassing waar de SDK kan worden gebruikt, met inbegrip van web-apps en console-apps.

Metrische gegevens verzenden

Vervang de inhoud van het worker.cs bestand door de volgende code:

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

Wanneer u de voorbeeldcode uitvoert, ziet u dat de while lus herhaaldelijk wordt uitgevoerd zonder dat er telemetrie wordt verzonden in het uitvoervenster van Visual Studio. Er wordt één telemetrie-item verzonden rond de 60 seconden, die in onze test er als volgt uitziet:

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

Dit enkele telemetrie-item vertegenwoordigt een aggregaties van 41 afzonderlijke metrische metingen. Omdat we steeds dezelfde waarde hebben verzonden, hebben we een standaarddeviatie (stDev) van 0 identieke maximumwaarden (max) en minimumwaarden (min). De value eigenschap vertegenwoordigt een som van alle afzonderlijke waarden die zijn samengevoegd.

Als we onze Application Insights-resource in de ervaring Logboeken (Analytics) onderzoeken, ziet het afzonderlijke telemetrie-item eruit als in de volgende schermopname.

U kunt ook toegang krijgen tot uw aangepaste metrische telemetrie in de sectie Metrische gegevens van de portal als een op logboek gebaseerde en aangepaste metrische gegevens. De volgende schermopname is een voorbeeld van een metrische gegevens op basis van een logboek.

Naslaginformatie over metrische cachegegevens voor gebruik met hoge doorvoer

In sommige gevallen kunnen metrische waarden vaak worden waargenomen. Een service met hoge doorvoer die bijvoorbeeld 500 aanvragen per seconde verwerkt, wil mogelijk 20 metrische gegevens voor telemetrie verzenden voor elke aanvraag. Het resultaat betekent dat er 10.000 waarden per seconde worden bijgehouden. In dergelijke scenario's met hoge doorvoer moeten gebruikers mogelijk de SDK helpen door bepaalde zoekacties te voorkomen.

In het voorgaande voorbeeld is bijvoorbeeld een zoekactie uitgevoerd voor een ingang voor de metrische waarde ComputersSold en vervolgens een waargenomen waarde bijgehouden.42 In plaats daarvan kan de greep worden opgeslagen in de cache voor meerdere aanroepen van tracering:

//...

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

Naast het opslaan van de metrische ingang in de cache, is het voorgaande voorbeeld ook gereduceerd Task.Delay tot 50 milliseconden, zodat de lus vaker zou worden uitgevoerd. Het resultaat is 772 TrackValue() aanroepen.

Multidimensionale metrische gegevens

In de voorbeelden in de vorige sectie worden nuldimensionale metrische gegevens weergegeven. Metrische gegevens kunnen ook multidimensionaal zijn. Momenteel ondersteunen we maximaal 10 dimensies.

Hier volgt een voorbeeld van het maken van een eendimensionale metrische waarde:

//...

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

Het uitvoeren van de voorbeeldcode gedurende ten minste 60 seconden resulteert in drie afzonderlijke telemetrie-items die naar Azure worden verzonden. Elk item vertegenwoordigt de aggregatie van een van de drie formulierfactoren. Net als voorheen kunt u verder onderzoeken in de weergave Logboeken (Analyse).

In de Metrics Explorer:

U kunt de metrische waarde niet splitsen door uw nieuwe aangepaste dimensie of uw aangepaste dimensie weergeven met de weergave met metrische gegevens.

Multidimensionale metrische gegevens in de Metric Explorer zijn standaard niet ingeschakeld in Application Insights-resources.

Multidimensionale metrische gegevens inschakelen

Als u multidimensionale metrische gegevens wilt inschakelen voor een Application Insights-resource, selecteert u Gebruik en geschatte kosten> gegevens>>OK. Zie Aangepaste dimensies voor metrische gegevens en vooraggregatie voor meer informatie.

Nadat u deze wijziging hebt aangebracht en nieuwe multidimensionale telemetrie hebt verzonden, kunt u Splitsen toepassen selecteren.

Bekijk uw metrische aggregaties voor elke FormFactor dimensie.

MetricIdentifier gebruiken wanneer er meer dan drie dimensies zijn

Momenteel worden 10 dimensies ondersteund. Voor meer dan drie dimensies is MetricIdentifier nodig:

// 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");

Aangepaste configuratie van metrische gegevens

Als u de configuratie van metrische gegevens wilt wijzigen, moet u wijzigingen aanbrengen op de plaats waar de metrische waarde wordt geïnitialiseerd.

Speciale dimensienamen

Metrische gegevens gebruiken niet de telemetriecontext van de TelemetryClient gebruikte gegevens om ze te openen. Het gebruik van speciale dimensienamen die beschikbaar zijn als constanten in de MetricDimensionNames klasse, is de beste tijdelijke oplossing voor deze beperking.

Metrische statistische gegevens die door de volgende Special Operation Request Size metrische gegevens worden verzonden , zijn Context.Operation.Name niet ingesteld op Special Operation. De TrackMetric() methode of een andere TrackXXX() methode is OperationName correct ingesteld op 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);
                //...
            }
                   
        }

Gebruik in dit geval de speciale dimensienamen die in de MetricDimensionNames klasse worden vermeld om de TelemetryContext waarden op te geven.

Wanneer de statistische waarde die het resultaat is van de volgende instructie bijvoorbeeld naar het Application Insights-cloudeindpunt wordt verzonden, Context.Operation.Name wordt het gegevensveld ingesteld op Special Operation:

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

De waarde van deze speciale dimensie wordt gekopieerd TelemetryContext naar en wordt niet gebruikt als een normale dimensie. Als u ook een bewerkingsdimensie wilt behouden voor normale metrische gegevensverkenning, moet u hiervoor een afzonderlijke dimensie maken:

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

Dimensie- en tijdreekslimieten

Als u wilt voorkomen dat het subsysteem voor telemetrie per ongeluk uw resources gebruikt, kunt u het maximum aantal gegevensreeksen per metrische waarde beheren. De standaardlimieten zijn niet meer dan 1000 totale gegevensreeksen per metrische waarde en niet meer dan 100 verschillende waarden per dimensie.

In de context van dimensie- en tijdreekslimieten gebruiken Metric.TrackValue(..) we om ervoor te zorgen dat de limieten worden waargenomen. Als de limieten Metric.TrackValue(..) al zijn bereikt, False worden de waarden geretourneerd en wordt de waarde niet bijgehouden. Anders wordt het geretourneerd True. Dit gedrag is handig als de gegevens voor een metrische waarde afkomstig zijn van gebruikersinvoer.

De MetricConfiguration constructor gebruikt enkele opties voor het beheren van verschillende reeksen binnen de respectieve metrische gegevens en een object van een klasse die IMetricSeriesConfiguration het aggregatiegedrag opgeeft voor elke afzonderlijke reeks van de metrische gegevens:

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 is het maximum aantal gegevenstijdreeksen dat een metrische waarde kan bevatten. Wanneer deze limiet is bereikt, retourneren aanroepen naar TrackValue() die normaal gesproken een nieuwe reeks.false
• valuesPerDimensionLimit beperkt het aantal afzonderlijke waarden per dimensie op een vergelijkbare manier.
• restrictToUInt32Values bepaalt of niet alleen niet-negatieve gehele getallen moeten worden bijgehouden.

Hier volgt een voorbeeld van hoe u een bericht verzendt om te weten of limieten voor limieten worden overschreden:

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

Aangepaste bewerkingen bijhouden

Application Insights SDK's volgen automatisch binnenkomende HTTP-aanvragen en aanroepen naar afhankelijke services, zoals HTTP-aanvragen en SQL-query's. Bijhouden en correlatie van aanvragen en afhankelijkheden geven u inzicht in de reactiesnelheid en betrouwbaarheid van de hele toepassing voor alle microservices die deze toepassing combineren.

Er is een klasse toepassingspatronen die algemeen niet kunnen worden ondersteund. Voor een goede bewaking van dergelijke patronen is handmatige code-instrumentatie vereist. In deze sectie vindt u een aantal patronen waarvoor handmatige instrumentatie is vereist, zoals het verwerken van aangepaste wachtrijen en het uitvoeren van langlopende achtergrondtaken.

Deze sectie bevat richtlijnen voor het bijhouden van aangepaste bewerkingen met de Application Insights SDK.

Overzicht

Een bewerking is een logisch werk dat door een toepassing wordt uitgevoerd. Het heeft een naam, begintijd, duur, resultaat en een context van uitvoering, zoals gebruikersnaam, eigenschappen en resultaat. Als bewerking A is gestart door bewerking B, wordt bewerking B ingesteld als een bovenliggend item voor A. Een bewerking kan slechts één bovenliggende bewerking hebben, maar kan veel onderliggende bewerkingen hebben. Zie Application Insights-telemetriecorrelatie voor meer informatie over bewerkingen en telemetriecorrelatie.

In de .NET SDK van Application Insights wordt de bewerking beschreven door de abstracte klasse OperationTelemetry en de onderliggende RequestTelemetry en DependencyTelemetry.

Bijhouden van binnenkomende bewerkingen

De Application Insights-web-SDK verzamelt automatisch HTTP-aanvragen voor ASP.NET toepassingen die worden uitgevoerd in een IIS-pijplijn en alle ASP.NET Core-toepassingen. Er zijn door de community ondersteunde oplossingen voor andere platforms en frameworks. Als de toepassing niet wordt ondersteund door een van de standaard- of door de community ondersteunde oplossingen, kunt u deze handmatig instrumenteren.

Een ander voorbeeld waarvoor aangepaste tracering is vereist, is de werkrol die items uit de wachtrij ontvangt. Voor sommige wachtrijen wordt de aanroep om een bericht aan deze wachtrij toe te voegen, bijgehouden als een afhankelijkheid. De bewerking op hoog niveau waarin berichtverwerking wordt beschreven, wordt niet automatisch verzameld.

Laten we eens kijken hoe dergelijke bewerkingen kunnen worden bijgehouden.

Op hoog niveau is de taak het maken RequestTelemetry en instellen van bekende eigenschappen. Nadat de bewerking is voltooid, houdt u de telemetrie bij. In het volgende voorbeeld ziet u deze taak.

HTTP-aanvraag in zelf-hostende Owin-app

In dit voorbeeld wordt traceringscontext doorgegeven volgens het HTTP-protocol voor correlatie. U kunt verwachten dat er headers worden weergegeven die daar worden beschreven.

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

Het HTTP-protocol voor correlatie declareert ook de Correlation-Context header. Het wordt hier weggelaten om het eenvoudig te maken.

Wachtrij-instrumentatie

Het W3C-traceringscontext en HTTP-protocol voor correlatiegegevens doorgeven aan HTTP-aanvragen , maar elk wachtrijprotocol moet definiëren hoe dezelfde details worden doorgegeven aan het wachtrijbericht. Sommige wachtrijprotocollen, zoals AMQP, staan het doorgeven van meer metagegevens toe. Voor andere protocollen, zoals Azure Storage Queue, moet de context worden gecodeerd in de nettolading van het bericht.

Service Bus-wachtrij

Zie gedistribueerde tracering en correlatie via Azure Service Bus-berichten voor traceringsinformatie.

Azure Storage-wachtrij

In het volgende voorbeeld ziet u hoe u de bewerkingen in de Azure Storage-wachtrij kunt bijhouden en telemetrie kunt correleren tussen de producent, de consument en Azure Storage.

De Storage-wachtrij heeft een HTTP-API. Alle aanroepen naar de wachtrij worden bijgehouden door de Application Insights Dependency Collector voor HTTP-aanvragen. Deze is standaard geconfigureerd voor ASP.NET- en ASP.NET Core-toepassingen. Zie de documentatie voor Console-toepassingen voor andere soorten toepassingen.

Mogelijk wilt u ook de Application Insights-bewerkings-id correleren met de opslagaanvraag-id. Zie Azure Storage controleren, diagnosticeren en problemen oplossen voor informatie over het instellen en ophalen van een opslagaanvraagclient en een serveraanvraag-id.

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

Op dezelfde manier kunnen andere wachtrijbewerkingen worden geïnstrueerd. Een peek-bewerking moet op een vergelijkbare manier worden geïnstrueerd als een dequeue-bewerking. Het instrumenteren van wachtrijbeheerbewerkingen is niet nodig. Application Insights houdt bewerkingen zoals HTTP bij en in de meeste gevallen is dit voldoende.

Wanneer u berichtverwijdering instrumenteert, moet u de bewerkings-id's (correlatie- id's) instellen. U kunt ook de Activity API gebruiken. Vervolgens hoeft u geen bewerkings-id's in te stellen voor de telemetrie-items, omdat de Application Insights SDK dit voor u doet:

• Maak een nieuw Activity item nadat u een item uit de wachtrij hebt.
• Gebruik Activity.SetParentId(message.ParentId) dit om consumenten- en producentlogboeken te correleren.
• Start de Activity.
• Volg dequeue-, proces- en verwijderbewerkingen met behulp van Start/StopOperation helpers. Doe dit vanuit dezelfde asynchrone controlestroom (uitvoeringscontext). Op deze manier worden ze correct gecorreleerd.
• Stop de Activity.
• Telemetrie handmatig gebruiken Start/StopOperation of aanroepen Track .

Afhankelijkheidstypen

Application Insights maakt gebruik van het afhankelijkheidstype om gebruikersinterface-ervaringen aan te passen. Voor wachtrijen worden de volgende typen DependencyTelemetry herkend die de diagnostische ervaring voor transacties verbeteren:

• Azure queue voor Azure Storage-wachtrijen
• Azure Event Hubs voor Azure Event Hubs
• Azure Service Bus voor Azure Service Bus

Batchverwerking

Met sommige wachtrijen kunt u meerdere berichten uit de wachtrij verwijderen met één aanvraag. Het verwerken van dergelijke berichten is vermoedelijk onafhankelijk en behoort tot de verschillende logische bewerkingen. Het is niet mogelijk om de Dequeue bewerking te correleren met een bepaald bericht dat wordt verwerkt.

Elk bericht moet worden verwerkt in een eigen asynchrone controlestroom. Zie de sectie Voor het bijhouden van uitgaande afhankelijkheden voor meer informatie.

Langlopende achtergrondtaken

Sommige toepassingen starten langdurige bewerkingen die mogelijk worden veroorzaakt door gebruikersaanvragen. Vanuit het perspectief van tracering/instrumentatie is dit niet anders dan aanvraag- of afhankelijkheidsinstrumentatie:

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

In dit voorbeeld telemetryClient.StartOperation wordt de correlatiecontext gemaakt DependencyTelemetry en ingevuld. Stel dat u een bovenliggende bewerking hebt die is gemaakt door binnenkomende aanvragen die de bewerking hebben gepland. Zolang BackgroundTask het begint in dezelfde asynchrone controlestroom als een binnenkomende aanvraag, wordt deze gecorreleerd met die bovenliggende bewerking. BackgroundTask en alle geneste telemetrie-items worden automatisch gecorreleerd met de aanvraag die dit heeft veroorzaakt, zelfs nadat de aanvraag is beëindigd.

Wanneer de taak begint vanaf de achtergrondthread waaraan geen bewerking (Activity) is gekoppeld, BackgroundTask is er geen bovenliggend item. Het kan echter geneste bewerkingen hebben. Alle telemetrie-items die van de taak worden gerapporteerd, worden gecorreleerd aan de DependencyTelemetry gemaakte in BackgroundTask.

Bijhouden van uitgaande afhankelijkheden

U kunt uw eigen soort afhankelijkheid bijhouden of een bewerking die niet wordt ondersteund door Application Insights.

De Enqueue methode in de Service Bus-wachtrij of de opslagwachtrij kan fungeren als voorbeelden voor dergelijke aangepaste tracering.

De algemene benadering voor het bijhouden van aangepaste afhankelijkheid is het volgende:

• Roep de TelemetryClient.StartOperation methode (extensie) aan die de DependencyTelemetry eigenschappen vult die nodig zijn voor correlatie en een aantal andere eigenschappen, zoals begin, tijdstempel en duur.
• Stel andere aangepaste eigenschappen in op de DependencyTelemetrynaam, zoals de naam en eventuele andere context die u nodig hebt.
• Maak een afhankelijkheidsaanroep en wacht erop.
• Stop de bewerking met StopOperation wanneer deze is voltooid.
• Uitzonderingen verwerken.

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.
        }
    }
}

Als u een bewerking opstelt, wordt de bewerking gestopt, dus u kunt dit doen in plaats van aanroepen StopOperation.

Parallelle bewerkingen verwerken en bijhouden

Het aanroepen StopOperation stopt alleen de bewerking die is gestart. Als de huidige actieve bewerking niet overeenkomt met de bewerking die u wilt stoppen, StopOperation doet u niets. Deze situatie kan optreden als u meerdere bewerkingen parallel start in dezelfde uitvoeringscontext.

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;

Zorg ervoor dat u de bewerking altijd aanroept StartOperation en verwerkt in dezelfde asynchrone methode om bewerkingen die parallel worden uitgevoerd, te isoleren. Als de bewerking synchroon (of niet asynchroon) is, verpakt u het proces en houdt u het bij met 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-bewerkingen versus System.Diagnostics.Activity

System.Diagnostics.Activity vertegenwoordigt de context voor gedistribueerde tracering en wordt gebruikt door frameworks en bibliotheken om context binnen en buiten het proces te maken en door te geven en telemetrie-items te correleren. Activity werkt samen met System.Diagnostics.DiagnosticSource het meldingsmechanisme tussen het framework/de bibliotheek om te informeren over interessante gebeurtenissen, zoals binnenkomende of uitgaande aanvragen en uitzonderingen.

Activiteiten zijn functies op het hoogste niveau in Application Insights. Automatische afhankelijkheid en aanvraagverzameling zijn sterk afhankelijk van deze, samen met DiagnosticSource gebeurtenissen. Als u in uw toepassing hebt gemaakt Activity , zou dit er niet toe leiden dat application Insights-telemetrie wordt gemaakt. Application Insights moet DiagnosticSource gebeurtenissen ontvangen en de gebeurtenisnamen en payloads kennen om Activity naar telemetrie om te zetten.

Elke Application Insights-bewerking (aanvraag of afhankelijkheid) omvat Activity. Wanneer StartOperation deze wordt aangeroepen, wordt deze eronder gemaakt Activity . StartOperation is de aanbevolen manier om aanvraag- of afhankelijkheidstelemetrieën handmatig bij te houden en ervoor te zorgen dat alles is gecorreleerd.

Tellers in Application Insights

Application Insights ondersteunt prestatiemeteritems en gebeurtenistellers. Deze handleiding biedt een overzicht van beide, waaronder hun doel, configuratie en gebruik in .NET-toepassingen.

Overzicht

Prestatiestatistieken

Windows biedt verschillende prestatiemeteritems, zoals prestatiemeteritems die worden gebruikt voor het verzamelen van processor-, geheugen- en schijfgebruiksstatistieken. U kunt ook uw eigen prestatiemeteritems definiëren.

Uw toepassing ondersteunt het verzamelen van prestatiemeteritems als deze wordt uitgevoerd onder IIS (Internet Information Server) op een on-premises host of een virtuele machine met beheerderstoegang. Toepassingen die als Azure Web Apps worden uitgevoerd, hebben niet rechtstreeks toegang tot prestatiemeteritems, maar Application Insights verzamelt een subset van beschikbare tellers.

Vereiste voorwaarden

Verwijs het serviceaccount van de app-pool om prestatiemeteritems te bewaken door deze toe te voegen aan de groep Gebruikers van prestatiemeter .

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

Tellers weergeven

In het deelvenster Metrische gegevens ziet u de standaardset prestatiemeteritems.

Tellers toevoegen

Als het gewenste prestatiemeteritem niet is opgenomen in de lijst met metrische gegevens, kunt u deze toevoegen.

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

Prestatiemeteritems verzamelen in code voor ASP.NET webtoepassingen of .NET/.NET Core-consoletoepassingen

Als u systeemprestatiemeteritems wilt verzamelen en naar Application Insights wilt verzenden, kunt u het volgende codefragment aanpassen:

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

U kunt ook hetzelfde doen met aangepaste metrische gegevens die u hebt gemaakt:

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

Prestatiemeteritems voor toepassingen die worden uitgevoerd in Azure Web Apps en Windows-containers in Azure App Service

Zowel ASP.NET als ASP.NET Core-toepassingen die zijn geïmplementeerd in Azure Web Apps, worden uitgevoerd in een speciale sandbox-omgeving. Toepassingen die zijn geïmplementeerd in Azure App Service, kunnen gebruikmaken van een Windows-container of worden gehost in een sandbox-omgeving. Als de toepassing is geïmplementeerd in een Windows-container, zijn alle standaard prestatiemeteritems beschikbaar in de containerinstallatiekopie.

De sandbox-omgeving staat geen directe toegang tot systeemprestatiemeteritems toe. Een beperkte subset van tellers wordt echter weergegeven als omgevingsvariabelen, zoals beschreven in Prestatiemeteritems die als omgevingsvariabelen worden weergegeven. In deze omgeving is slechts een subset met tellers beschikbaar. Zie Prestatiemeteritems die als omgevingsvariabelen worden weergegeven voor de volledige lijst.

De Application Insights SDK voor ASP.NET en ASP.NET Core detecteert of code is geïmplementeerd in een web-app of een niet-Windows-container. De detectie bepaalt of prestatiemeteritems in een sandbox-omgeving worden verzameld of het standaardverzamelingsmechanisme wordt gebruikt wanneer deze wordt gehost op een Windows-container of virtuele machine.

Log Analytics-query's voor prestatiemeteritems

U kunt rapporten van prestatiemeteritems zoeken en weergeven in Log Analytics.

Het performanceCounters-schema toont de category, counter naam en instance naam van elke prestatiemeteritem. In de telemetrie voor elke toepassing ziet u alleen de tellers voor die toepassing. Als u bijvoorbeeld wilt zien welke tellers beschikbaar zijn:

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

Instance Hier verwijst u naar het prestatiemeteritemexemplaren, niet de rol of het servercomputerexemplaren. De naam van het exemplaar van het prestatiemeteritem segmenten, zoals processortijd, op basis van de naam van het proces of de toepassing.

Een grafiek met het beschikbare geheugen in de afgelopen periode ophalen:

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

Net als andere telemetrie heeft performanceCounters ook een kolom cloud_RoleInstance die de identiteit aangeeft van het hostserverexemplaren waarop uw app wordt uitgevoerd. Als u bijvoorbeeld de prestaties van uw app op de verschillende computers wilt vergelijken:

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

Veelgestelde vragen over prestatiemeteritems

Zie Veelgestelde vragen over prestatiemeteritems voor meer informatie over veelgestelde vragen.

Gebeurtenistellers

EventCounter is .NET/.NET Core-mechanisme voor het publiceren en verbruiken van tellers of statistieken. EventCounters worden ondersteund in alle besturingssysteemplatforms: Windows, Linux en macOS. Het kan worden beschouwd als een platformoverschrijdend equivalent voor de PerformanceCounters die alleen wordt ondersteund in Windows-systemen.

Hoewel gebruikers aangepaste gebeurtenistellers kunnen publiceren om aan hun behoeften te voldoen, publiceert .NET standaard een set van deze tellers. In dit document worden de stappen beschreven die nodig zijn voor het verzamelen en weergeven van gebeurtenismeteritems (door het systeem gedefinieerd of door de gebruiker gedefinieerd) in Azure Application Insights.

Application Insights gebruiken om EventCounters te verzamelen

Application Insights ondersteunt het verzamelen EventCounters met EventCounterCollectionModulehet bijbehorende, dat deel uitmaakt van het zojuist uitgebrachte NuGet-pakket Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule wordt automatisch ingeschakeld wanneer u AspNetCore of WorkerService gebruikt. EventCounterCollectionModule verzamelt tellers met een niet-configureerbare verzamelingsfrequentie van 60 seconden. Er zijn geen speciale machtigingen vereist voor het verzamelen van EventCounters. Voor ASP.NET Core-toepassingen wilt u ook het pakket Microsoft.ApplicationInsights.AspNetCore toevoegen.

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

Standaarditems verzameld

Vanaf versie 2.15.0 van aspNetCore SDK of WorkerService SDK worden er standaard geen tellers verzameld. De module zelf is ingeschakeld, zodat gebruikers de gewenste tellers kunnen toevoegen om ze te verzamelen.

Zie het document Beschikbare tellers voor een lijst met bekende tellers die zijn gepubliceerd door .NET Runtime.

Tellers aanpassen die moeten worden verzameld

In het volgende voorbeeld ziet u hoe u tellers toevoegt of verwijdert. Deze aanpassing wordt uitgevoerd als onderdeel van de configuratie van uw toepassingsservice nadat de verzameling telemetriegegevens van Application Insights is ingeschakeld met behulp van AddApplicationInsightsTelemetry() of AddApplicationInsightsWorkerService(). Hieronder volgt een voorbeeldcode van een ASP.NET Core-toepassing. Raadpleeg voor andere toepassingen telemetriemodules configureren.

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

EventCounter-verzamelingsmodule uitschakelen

EventCounterCollectionModule kan worden uitgeschakeld met behulp van ApplicationInsightsServiceOptions.

In het volgende voorbeeld wordt de ASP.NET Core SDK gebruikt.

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

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

Een vergelijkbare benadering kan ook worden gebruikt voor de Worker Service SDK, maar de naamruimte moet worden gewijzigd, zoals wordt weergegeven in het volgende voorbeeld.

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

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

Log Analytics-query's voor gebeurtenistellers

U kunt rapporten van gebeurtenistellers zoeken en weergeven in Log Analytics, in de tabel customMetrics .

Voer bijvoorbeeld de volgende query uit om te zien welke meteritems worden verzameld en beschikbaar zijn voor query's:

customMetrics | summarize avg(value) by name

Voer de volgende query uit om een grafiek van een specifieke teller (bijvoorbeeld: ThreadPool Completed Work Item Count) op te halen in de afgelopen periode.

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

Net als andere telemetrie heeft customMetrics ook een kolom cloud_RoleInstance die de identiteit aangeeft van het hostserverexemplaren waarop uw app wordt uitgevoerd. De vorige query toont de tellerwaarde per exemplaar en kan worden gebruikt om de prestaties van verschillende serverexemplaren te vergelijken.

Veelgestelde vragen over gebeurtenistellers

Als u veelgestelde vragen (FAQ) wilt bekijken, raadpleegt u veelgestelde vragen over gebeurtenistellers.

Telemetrie filteren en verrijken

In deze sectie

• Telemetrie filteren en vooraf verwerken
• Initialisatiefuncties voor telemetrie
• Telemetrieprocessor
• Monsterneming
• Gegevens verrijken via HTTP

Telemetrie filteren en vooraf verwerken

U kunt code schrijven om uw telemetrie te filteren, te wijzigen of te verrijken voordat deze wordt verzonden vanuit de SDK. De verwerking omvat gegevens die worden verzonden vanuit de standaardtelemetriemodules, zoals het verzamelen van HTTP-aanvragen en het verzamelen van afhankelijkheden.

• Filteren kan telemetrie wijzigen of verwijderen voordat deze wordt verzonden vanuit de SDK door deze te implementeren ITelemetryProcessor. U kunt bijvoorbeeld het volume van telemetrie verminderen door aanvragen van robots uit te sluiten. In tegenstelling tot steekproeven hebt u volledige controle over wat er wordt verzonden of verwijderd, maar dit is van invloed op metrische gegevens op basis van geaggregeerde logboeken. Afhankelijk van hoe u items negeert, verliest u mogelijk ook de mogelijkheid om tussen gerelateerde items te navigeren.

• Voeg eigenschappen toe aan of wijzig deze voor alle telemetrie die vanuit uw app wordt verzonden door een ITelemetryInitializer. U kunt bijvoorbeeld berekende waarden of versienummers toevoegen waarmee de gegevens in de portal moeten worden gefilterd.

• Steekproeven verminderen het volume van telemetrie zonder dat dit van invloed is op uw statistieken. Hiermee worden gerelateerde gegevenspunten bijeengehouden, zodat u ertussen kunt navigeren wanneer u een probleem diagnosticeren. In de portal worden de totale aantallen vermenigvuldigd om de steekproef te compenseren.

Filtering

Deze techniek geeft u directe controle over wat er is opgenomen of uitgesloten van de telemetriestroom. Filteren kan worden gebruikt om te voorkomen dat telemetrie-items naar Application Insights verzonden worden. U kunt filteren met steekproeven of afzonderlijk gebruiken.

Als u telemetrie wilt filteren, schrijft u een telemetrieprocessor en registreert u deze bij TelemetryConfiguration. Alle telemetrie gaat via uw processor. U kunt ervoor kiezen om deze uit de stream te verwijderen of deze aan de volgende processor in de keten te geven. Telemetrie van de standaardmodules, zoals de HTTP-aanvraagverzamelaar en de afhankelijkheidsverzamelaar, en telemetrie die u zelf hebt bijgehouden, wordt opgenomen. U kunt bijvoorbeeld telemetrie filteren over aanvragen van robots of geslaagde afhankelijkheidsaanroepen.

ITelemetryProcessor en ITelemetryInitializer

Wat is het verschil tussen telemetrieprocessors en initialisatiefuncties voor telemetrie?

• Er zijn enkele overlappingen in wat u ermee kunt doen. Beide kunnen worden gebruikt om eigenschappen van telemetrie toe te voegen of te wijzigen, hoewel we u aanraden initialisatiefuncties voor dat doel te gebruiken.
• Telemetrie-initialisatiefuncties worden altijd uitgevoerd vóór telemetrieprocessors.
• Telemetrie-initialisatiefuncties kunnen meerdere keren worden aangeroepen. Standaard stellen ze geen eigenschap in die al is ingesteld.
• Met telemetrieprocessors kunt u een telemetrie-item volledig vervangen of verwijderen.
• Alle geregistreerde telemetrie-initialisatiefuncties worden aangeroepen voor elk telemetrie-item. Voor telemetrieprocessors garandeert SDK dat de eerste telemetrieprocessor wordt aangeroepen. Of de rest van de processors worden aangeroepen of niet, wordt beslist door de voorgaande telemetrieprocessors.
• Gebruik telemetrie-initialisatiefuncties om telemetrie te verrijken met meer eigenschappen of om een bestaande te overschrijven. Gebruik een telemetrieprocessor om telemetrie uit te filteren.

Eigenschappen toevoegen/wijzigen

Gebruik telemetrie-initialisatiefuncties om telemetrie te verrijken met aanvullende informatie of om telemetrie-eigenschappen te overschrijven die zijn ingesteld door de standaardtelemetriemodules.

Application Insights voor een webpakket verzamelt bijvoorbeeld telemetrie over HTTP-aanvragen. Standaard wordt elke aanvraag met een antwoordcode >=400 als mislukt gevlagd. Als u in plaats daarvan 400 als een succes wilt behandelen, kunt u een initialisatiefunctie voor telemetrie opgeven waarmee de eigenschap succes wordt ingesteld.

Als u een initialisatiefunctie voor telemetrie opgeeft, wordt deze aangeroepen wanneer een van de methoden Track*() wordt aangeroepen. Deze initialisatiefunctie bevat Track() methoden die worden aangeroepen door de standaardtelemetriemodules. Deze modules stellen standaard geen eigenschappen in die al door een initialisatiefunctie zijn ingesteld. Initialisatiefuncties voor telemetrie worden aangeroepen voordat telemetrieprocessors worden aangeroepen, dus alle verrijkingen die door initialisatiefuncties worden uitgevoerd, zijn zichtbaar voor processors.

Initialisatiefuncties voor telemetrie

Als u telemetrie wilt verrijken met aanvullende informatie of telemetrie-eigenschappen wilt overschrijven die zijn ingesteld door de standaardtelemetriemodules, gebruikt u telemetrie-initialisatiefuncties.

Met initialisatiefuncties voor telemetrie worden contexteigenschappen ingesteld die samen met elk item van telemetrie worden verzonden. U kunt uw eigen initializers schrijven om contexteigenschappen in te stellen.

De standaard initializers zijn allemaal ingesteld door de web- of WindowsServer NuGet-pakketten:

ITelemetryInitializer toevoegen

In dit blog wordt een project beschreven voor het diagnosticeren van afhankelijkheidsproblemen door automatisch regelmatige pings naar afhankelijkheden te verzenden.

1. Uw initialisatiefunctie definiëren

   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. Uw initialisatiefunctie laden

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

Voorbeeld van ITelemetryInitializers

Een aangepaste eigenschap toevoegen

Met de volgende voorbeeld-initialisatiefunctie wordt een aangepaste eigenschap toegevoegd aan elke bijgehouden telemetrie.

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

Een cloudrolnaam en cloudrolinstantie toevoegen

Stap 1: Aangepaste TelemetryInitializer schrijven

De volgende voorbeeld-initialisator stelt de cloudrolnaam in voor elke bijgehouden telemetrie.

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

Stap 2: Een initialisatiefunctie laden in 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>();
}

Het IP-adres van de client beheren dat wordt gebruikt voor geolocatietoewijzingen

Met de volgende voorbeeld-initialisatiefunctie wordt het IP-adres van de client ingesteld, dat wordt gebruikt voor geolocatietoewijzing, in plaats van het IP-adres van de clientsocket, tijdens telemetrieopname.

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

Telemetrieverwerkers

Telemetrieprocessors kunnen elk telemetrie-item filteren en wijzigen voordat het van de SDK naar de portal wordt verzonden.

1. Voer ITelemetryProcessor uit.

   Telemetrieprocessors bouwen een keten van verwerking. Wanneer u een telemetrieprocessor instantiëren, krijgt u een verwijzing naar de volgende processor in de keten. Wanneer een telemetriegegevenspunt wordt doorgegeven aan de procesmethode, wordt het werk uitgevoerd en wordt vervolgens de volgende telemetrieprocessor in de keten aangeroepen (of wordt deze niet aangeroepen).

   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. Voeg uw processor toe.

   • ASP.NET
   • ASP.NET Core
   • Werker Service

   Voeg dit fragment in ApplicationInsights.configin:

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

   U kunt tekenreekswaarden uit het .config-bestand doorgeven door openbare benoemde eigenschappen in uw klasse op te geven.

   Waarschuwing

   Zorg ervoor dat de typenaam en eventuele eigenschapsnamen in het .config bestand overeenkomen met de klasse- en eigenschapsnamen in de code. Als het bestand .config verwijst naar een niet-bestaand type of een niet-bestaande eigenschap, kan de SDK op de achtergrond geen telemetrie verzenden.

   U kunt het filter ook initialiseren in code. Voeg in een geschikte initialisatieklasse, bijvoorbeeld AppStart in Global.asax.cs, uw processor in de keten in:

   Opmerking

   Het volgende codevoorbeeld is verouderd, maar wordt hier beschikbaar gesteld voor posteriteit. Overweeg om aan de slag te gaan met OpenTelemetry of te migreren naar 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();
   

   Telemetrieclients die na dit punt zijn gemaakt, gebruiken uw processors.

   Adaptieve steekproeftelemetrieprocessor (van 2.0.0-beta3)

   Deze functionaliteit is standaard ingeschakeld. Als uw app aanzienlijke telemetrie verzendt, verwijdert deze processor een deel ervan.

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

   De parameter biedt het doel dat het algoritme probeert te bereiken. Elk exemplaar van de SDK werkt onafhankelijk. Dus als uw server een cluster van verschillende computers is, wordt het werkelijke volume van telemetrie dienovereenkomstig vermenigvuldigd.

   Meer informatie over steekproeven.

   Telemetrieprocessor met vaste snelheid (van 2.0.0-beta1)

   Er is ook een standaard steekproeftelemetrieprocessor (van 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>
   

Voorbeeldfilters

Synthetische aanvragen

Filter bots en webtests uit. Hoewel Metrics Explorer u de mogelijkheid biedt om synthetische bronnen te filteren, vermindert deze optie het verkeer en de opnamegrootte door ze te filteren op de SDK zelf.

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

Mislukte verificatie

Filter aanvragen met een "401"-antwoord eruit.

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

Snelle externe afhankelijkheidsaanroepen filteren

Als u alleen gesprekken wilt diagnosticeren die traag zijn, filtert u de snelle oproepen.

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

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

Steekproeven

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

Gegevens verrijken 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

SDK-onderdelen beheren

In deze sectie

• Telemetriekanalen
• Telemetriemodules
• Telemetrie uitschakelen
• ApplicationId-provider
• Verzameling momentopnamen

U kunt de Application Insights SDK aanpassen voor ASP.NET, ASP.NET Core en Worker Service om de standaardconfiguratie te wijzigen.

Telemetriekanalen

Telemetriekanalen vormen een integraal onderdeel van de Application Insights SDK's. Ze beheren buffering en overdracht van telemetrie naar de Application Insights-service. De .NET- en .NET Core-versies van de SDK's hebben twee ingebouwde telemetriekanalen: InMemoryChannel en ServerTelemetryChannel. In deze sectie wordt elk kanaal beschreven en wordt uitgelegd hoe u kanaalgedrag aanpast.

Wat zijn telemetriekanalen?

Telemetriekanalen zijn verantwoordelijk voor het bufferen van telemetrie-items en het verzenden ervan naar de Application Insights-service, waar ze worden opgeslagen voor het uitvoeren van query's en analyses. Een telemetriekanaal is een klasse die de Microsoft.ApplicationInsights.ITelemetryChannel interface implementeert.

De Send(ITelemetry item) methode van een telemetriekanaal wordt aangeroepen nadat alle telemetrie-initialisatiefuncties en telemetrieprocessors worden aangeroepen. Alle items die door een telemetrieprocessor worden verwijderd, bereiken dus het kanaal niet. De Send() methode verzendt de items gewoonlijk niet onmiddellijk naar de back-end. Normaal gesproken buffert het ze in het geheugen en verzendt ze in batches voor efficiënte verzending.

Vermijd aanroepen Flush() , tenzij het essentieel is om direct gebufferde telemetrie te verzenden. Gebruik dit alleen in scenario's zoals het afsluiten van toepassingen, het verwerken van uitzonderingen of bij het gebruik van processen met korte levensduur, zoals achtergrondtaken of opdrachtregelprogramma's. In webtoepassingen of langlopende services verwerkt de SDK telemetrie die automatisch wordt verzonden. Bellen Flush() kan onnodig prestatieproblemen veroorzaken.

Live Metrics Stream heeft ook een aangepast kanaal dat de livestreaming van telemetrie mogelijk maakt. Dit kanaal is onafhankelijk van het normale telemetriekanaal en dit document is niet van toepassing op het kanaal.

Ingebouwde telemetriekanalen

De .NET- en .NET Core SDK's van Application Insights worden geleverd met twee ingebouwde kanalen:

• InMemoryChannel: Een lichtgewicht kanaal waarmee items in het geheugen worden gebufferd totdat ze worden verzonden. Items worden in het geheugen gebufferd en elke 30 seconden leeggemaakt, of wanneer 500 items worden gebufferd. Dit kanaal biedt minimale betrouwbaarheidsgaranties omdat het geen telemetrie opnieuw probeert te verzenden na een fout. Dit kanaal bewaart ook geen items op schijf. Alle niet-verzonden items gaan dus definitief verloren bij het afsluiten van de toepassing, ongeacht of deze correct zijn of niet. Dit kanaal implementeert een Flush() methode die kan worden gebruikt om eventuele in-memory telemetrie-items synchroon te wissen. Dit kanaal is zeer geschikt voor kortlopende toepassingen waarbij een synchrone flush ideaal is.

  Dit kanaal maakt deel uit van het grotere NuGet-pakket Microsoft.ApplicationInsights en is het standaardkanaal dat de SDK gebruikt wanneer er niets anders is geconfigureerd.

• ServerTelemetryChannel: Een geavanceerder kanaal met beleid voor opnieuw proberen en de mogelijkheid om gegevens op een lokale schijf op te slaan. Dit kanaal probeert opnieuw telemetrie te verzenden als er tijdelijke fouten optreden. Dit kanaal maakt ook gebruik van lokale schijfopslag om items op schijf te houden tijdens netwerkstoringen of hoge telemetrievolumes. Vanwege deze mechanismen voor opnieuw proberen en lokale schijfopslag wordt dit kanaal beschouwd als betrouwbaarder. We raden dit aan voor alle productiescenario's. Dit kanaal is de standaardinstelling voor ASP.NET- en ASP.NET Core-toepassingen die zijn geconfigureerd volgens de officiële documentatie. Dit kanaal is geoptimaliseerd voor serverscenario's met langlopende processen. De Flush() methode die door dit kanaal wordt geïmplementeerd, is niet synchroon.

  Dit kanaal wordt geleverd als het NuGet-pakket Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel en wordt automatisch verkregen wanneer u het NuGet-pakket Microsoft.ApplicationInsights.Web of Microsoft.ApplicationInsights.AspNetCore gebruikt.

Een telemetriekanaal configureren

U configureert een telemetriekanaal door dit in te stellen op de actieve telemetrieconfiguratie. Voor ASP.NET toepassingen moet de configuratie het exemplaar van het telemetriekanaal TelemetryConfiguration.Active instellen op of door deze te ApplicationInsights.configwijzigen. Voor ASP.NET Core-toepassingen moet de configuratie het kanaal toevoegen aan de container voor afhankelijkheidsinjectie.

In de volgende secties ziet u voorbeelden van het configureren van de StorageFolder instelling voor het kanaal in verschillende toepassingstypen. StorageFolder is slechts een van de configureerbare instellingen. Zie de sectie Configureerbare instellingen in kanalen verderop in dit artikel voor de volledige lijst met configuratie-instellingen.

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

Configuratie in code voor consoletoepassingen

Voor console-apps is de code hetzelfde voor zowel .NET als .NET Core:

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

Operationele details van ServerTelemetryChannel

ServerTelemetryChannel slaat binnenkomende items op in een buffer in het geheugen. De items worden elke 30 seconden geserialiseerd, gecomprimeerd en opgeslagen in een Transmission exemplaar of wanneer 500 items worden gebufferd. Eén Transmission exemplaar bevat maximaal 500 items en vertegenwoordigt een batch telemetriegegevens die via één HTTPS-aanroep naar de Application Insights-service worden verzonden.

Standaard kunnen maximaal 10 Transmission exemplaren parallel worden verzonden. Als telemetrie sneller aankomt of als het netwerk of de Application Insights-back-end traag is, Transmission worden exemplaren opgeslagen in het geheugen. De standaardcapaciteit van deze in-memory Transmission buffer is 5 MB. Wanneer de capaciteit in het geheugen wordt overschreden, Transmission worden exemplaren op de lokale schijf opgeslagen tot een limiet van 50 MB.

Transmission exemplaren worden op de lokale schijf opgeslagen, ook wanneer er netwerkproblemen zijn. Alleen items die zijn opgeslagen op een lokale schijf, overleven een toepassingscrash. Ze worden verzonden wanneer de toepassing opnieuw wordt gestart. Als netwerkproblemen zich voordoen, ServerTelemetryChannel gebruikt u een exponentieel uitstellogica van 10 seconden tot 1 uur voordat u opnieuw probeert telemetrie te verzenden.

Configureerbare instellingen in kanalen

Zie voor de volledige lijst met configureerbare instellingen voor elk kanaal:

• InMemoryChannel
• ServerTelemetryChannel

Hier volgen de meestgebruikte instellingen voor ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: De maximale hoeveelheid geheugen, in bytes, die door het kanaal wordt gebruikt om transmissies in het geheugen te bufferen. Wanneer deze capaciteit is bereikt, worden nieuwe items rechtstreeks op de lokale schijf opgeslagen. De standaardwaarde is 5 MB. Het instellen van een hogere waarde leidt tot minder schijfgebruik, maar onthoud dat items in het geheugen verloren gaan als de toepassing vastloopt.

• MaxTransmissionSenderCapacity: Het maximum aantal Transmission exemplaren dat tegelijkertijd naar Application Insights wordt verzonden. De standaardwaarde is 10. Deze instelling kan worden geconfigureerd voor een hoger getal, wat we aanbevelen wanneer een groot aantal telemetriegegevens wordt gegenereerd. Een hoog volume treedt meestal op tijdens het testen van de belasting of wanneer steekproeven zijn uitgeschakeld.

• StorageFolder: De map die door het kanaal wordt gebruikt om items naar schijf op te slaan, indien nodig. In Windows wordt %LOCALAPPDATA% of %TEMP% gebruikt als er geen ander pad expliciet is opgegeven. In andere omgevingen dan Windows worden standaard de volgende locaties gebruikt (in volgorde): %TMPDIR%, /var/tmp/ of /tmp/.

Welk kanaal moet ik gebruiken?

We raden u aan ServerTelemetryChannel voor de meeste productiescenario's waarbij langlopende toepassingen worden gebruikt. Lees over het gebruik van telemetrie voor meer informatie over het leegmaken van Flush()telemetrie.

Wanneer gebruikt u Flush()

De Flush() methode verzendt onmiddellijk gebufferde telemetrie. Het mag echter alleen worden gebruikt in specifieke scenario's.

Gebruik Flush() wanneer:

• De toepassing staat op het punt om af te sluiten en u wilt ervoor zorgen dat telemetrie wordt verzonden voordat u afsluit.
• U bevindt zich in een uitzonderingshandler en moet garanderen dat telemetrie wordt geleverd.
• U schrijft een kortstondige procedure, zoals een achtergrondtaak of CLI-hulpprogramma dat snel wordt afgesloten.

Vermijd het gebruik Flush() in langlopende toepassingen, zoals webservices. De SDK beheert automatisch buffering en verzending. Het aanroepen Flush() kan onnodig prestatieproblemen veroorzaken en garandeert niet dat alle gegevens worden verzonden, met name wanneer ze worden gebruikt ServerTelemetryChannel, waardoor deze niet synchroon worden leeggemaakt.

Telemetriemodules

Application Insights verzamelt automatisch telemetrie over specifieke werkbelastingen zonder dat handmatig bijhouden door de gebruiker is vereist.

Standaard zijn de volgende modules voor automatische verzameling ingeschakeld. U kunt ze uitschakelen of configureren om hun standaardgedrag te wijzigen.

Telemetriemodules configureren

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

Telemetrie uitschakelen

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

Verbindingsreeks

Deze instelling bepaalt de Application Insights-resource waarin uw gegevens worden weergegeven. Normaal gesproken maakt u een afzonderlijke resource, met een afzonderlijke verbindingsreeks, voor elk van uw toepassingen.

Zie Verbindingsreeksen in Application Insights voor codevoorbeelden .

Als u de verbindingsreeks dynamisch wilt instellen, bijvoorbeeld om resultaten van uw toepassing naar verschillende resources te verzenden, kunt u de verbindingsreeks weglaten uit het configuratiebestand en deze in plaats daarvan instellen in code.

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

Het doel van deze provider is om een toepassings-id op te zoeken op basis van een verbindingsreeks. De toepassings-id is opgenomen in RequestTelemetry en DependencyTelemetry wordt gebruikt om de correlatie in de portal te bepalen.

Deze functionaliteit is beschikbaar door de instelling in te stellen TelemetryConfiguration.ApplicationIdProvider.

Interface: IApplicationIdProvider (Interface voor toepassings-ID-aanbieder)

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

We bieden twee implementaties in de Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider en DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Deze wrapper is voor onze profiel-API. Hiermee worden aanvragen en cacheresultaten beperkt. Deze provider wordt automatisch opgenomen wanneer u Microsoft.ApplicationInsights.DependencyCollector of Microsoft.ApplicationInsights.Web installeert.

De klasse toont een optionele eigenschap met de naam ProfileQueryEndpoint. Deze is standaard ingesteld op https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Als u een proxy wilt configureren, raden we u aan het basisadres te proxyn en ervoor te zorgen dat het pad wordt opgenomen /api/profiles/{0}/appId. Tijdens runtime {0} wordt deze vervangen door de instrumentatiesleutel voor elke aanvraag.

<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

Deze statische provider is afhankelijk van uw geconfigureerde instrumentatiesleutel-/toepassings-id-paren.

Deze klasse heeft de Defined eigenschap, een Dictionary<string,string> van instrumentatiesleutel-/toepassings-id-paren.

Deze klasse heeft de optionele eigenschap Next, die kan worden gebruikt om een andere provider te configureren die moet worden gebruikt wanneer een verbindingsreeks wordt aangevraagd die niet bestaat in uw configuratie.

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

Verzameling momentopnamen configureren

Zie Snapshot Debugger inschakelen voor .NET-apps in Azure Service Fabric, Cloud Services en virtuele machines voor informatie over het configureren van momentopnameverzamelingen voor ASP.NET en ASP.NET Core-toepassingen.

Bewaking aan clientzijde toevoegen

De vorige secties bevatten richtlijnen voor methoden voor het automatisch en handmatig configureren van bewaking aan de serverzijde. Als u bewaking aan clientzijde wilt toevoegen, gebruikt u de JavaScript SDK aan de clientzijde. U kunt de transacties aan de clientzijde van elke webpagina bewaken door een JavaScript (Web) SDK Loader Script toe te voegen vóór de afsluitende </head> tag van de HTML van de pagina.

Hoewel het mogelijk is om het JavaScript (Web) SDK Loader Script handmatig toe te voegen aan de koptekst van elke HTML-pagina, raden we u aan in plaats daarvan het JavaScript (Web) SDK Loader Script toe te voegen aan een primaire pagina. Deze actie injecteert het JavaScript (Web) SDK Loader Script in alle pagina's van een site.

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

Kern-API voor aangepaste gebeurtenissen en metrische gegevens

Voeg een paar regels code in uw toepassing in om erachter te komen wat gebruikers ermee doen of om problemen vast te stellen. U kunt telemetrie verzenden vanuit apparaat- en bureaublad-apps, webclients en webservers. Gebruik de Application Insights-kerntelemetrie-API om aangepaste gebeurtenissen en metrische gegevens en uw eigen versies van standaardtelemetrie te verzenden. Deze API is dezelfde API die door de standaard Application Insights-gegevensverzamelaars wordt gebruikt.

API-samenvatting

De kern-API is uniform op alle platforms, afgezien van enkele variaties zoals GetMetric (alleen.NET).

U kunt eigenschappen en metrische gegevens koppelen aan de meeste van deze telemetriegesprekken.

Vereiste voorwaarden

Als u nog geen referentie hebt naar de Application Insights SDK:

1. Voeg de Application Insights SDK toe aan uw project.

2. Neem in de code van uw apparaat of webserver het volgende op:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Een TelemetryClient-exemplaar ophalen

Haal een exemplaar op van TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

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

var telemetry = applicationInsights.defaultClient;

TrackEvent

In Application Insights is een aangepaste gebeurtenis een gegevenspunt dat u in Metrics Explorer kunt weergeven als een geaggregeerd aantal en in Diagnostische zoekopdrachten als afzonderlijke exemplaren. (Het is niet gerelateerd aan MVC of andere framework -gebeurtenissen.)

Voeg TrackEvent aanroepen in uw code in om verschillende gebeurtenissen te tellen. U kunt bijvoorbeeld bijhouden hoe vaak gebruikers een bepaalde functie kiezen. Of misschien wilt u weten hoe vaak ze bepaalde doelen bereiken of specifieke soorten fouten maken.

Verzend bijvoorbeeld in een game-app een gebeurtenis wanneer een gebruiker het spel wint:

telemetry.TrackEvent("WinGame");

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

Aangepaste gebeurtenissen in Log Analytics

De telemetrie is beschikbaar in de customEvents tabel op het tabblad Application Insights-logboeken of de gebruikservaring. Gebeurtenissen kunnen afkomstig zijn van trackEvent(..) of de invoegtoepassing Click Analytics AutoCollection.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackEvent(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aangepaste gebeurtenissen wilt ophalen, gebruikt u code zoals customEvents | summarize sum(itemCount).

GetMetric

Zie GetMetric() voor meer informatie over het effectief gebruik van de aanroep om lokaal geaggregeerde metrische gegevens vast te leggen voor .NET- en .NET Core-toepassingen.

TrackMetric

Application Insights kan metrische gegevens weergeven die niet zijn gekoppeld aan bepaalde gebeurtenissen. U kunt bijvoorbeeld een wachtrijlengte met regelmatige tussenpozen bewaken. Met metrische gegevens zijn de afzonderlijke metingen minder interessant dan de variaties en trends, en dus zijn statistische grafieken nuttig.

Als u metrische gegevens naar Application Insights wilt verzenden, kunt u de TrackMetric(..) API gebruiken. Er zijn twee manieren om een metrische waarde te verzenden:

• Eén waarde. Telkens wanneer u een meting uitvoert in uw toepassing, verzendt u de bijbehorende waarde naar Application Insights.

  Stel dat u een metrische waarde hebt die het aantal items in een container beschrijft. Tijdens een bepaalde periode plaatst u eerst drie items in de container en vervolgens verwijdert u twee items. Daarom zou u TrackMetric twee keer aanroepen. Eerst geeft u de waarde 3 door en geeft u vervolgens de waarde -2door. In Application Insights worden beide waarden voor u opgeslagen.

• Aggregatie. Wanneer u met metingen werkt, is elke afzonderlijke meting zelden interessant. In plaats daarvan is een samenvatting van wat er is gebeurd tijdens een bepaalde periode belangrijk. Een dergelijke samenvatting wordt aggregatie genoemd.

  In het voorgaande voorbeeld is 1 de geaggregeerde metrische som voor die periode en het aantal metrische waarden 2. Wanneer u de aggregatiebenadering gebruikt, roept TrackMetric u slechts één keer per periode aan en verzendt u de geaggregeerde waarden. We raden deze aanpak aan omdat deze de kosten en prestatieoverhead aanzienlijk kan verminderen door minder gegevenspunten naar Application Insights te verzenden, terwijl alle relevante informatie nog steeds wordt verzameld.

Voorbeelden van één waarde

Eén metrische waarde verzenden:

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

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

Aangepaste metrische gegevens in Log Analytics

De telemetrie is beschikbaar in de customMetrics tabel in Application Insights Analytics. Elke rij vertegenwoordigt een aanroep naar trackMetric(..) in uw app.

• valueSum: De som van de metingen. Als u de gemiddelde waarde wilt ophalen, deelt u door valueCount.
• valueCount: Het aantal metingen dat in deze trackMetric(..) aanroep is samengevoegd.

Paginaweergaven

In een apparaat- of webapp wordt paginaweergavetelemetrie standaard verzonden wanneer elk scherm of elke pagina wordt geladen. Maar u kunt de standaardinstelling wijzigen om paginaweergaven op meer of verschillende tijdstippen bij te houden. In een app met tabbladen of deelvensters kunt u bijvoorbeeld een pagina bijhouden wanneer de gebruiker een nieuw deelvenster opent.

Gebruikers- en sessiegegevens worden verzonden als eigenschappen, samen met paginaweergaven, zodat de gebruikers- en sessiegrafieken tot leven komen wanneer er telemetriegegevens over de paginaweergave zijn.

Aangepaste paginaweergaven

telemetry.TrackPageView("GameReviewPage");

Pagina-telemetrie in Log Analytics

In Log Analytics worden in twee tabellen gegevens uit browserbewerkingen weergegeven:

• pageViews: bevat gegevens over de URL en paginatitel.
• browserTimings: bevat gegevens over clientprestaties, zoals de tijd die nodig is om de binnenkomende gegevens te verwerken.

Ga als volgt te werk om te zien hoe lang het duurt voordat de browser verschillende pagina's verwerkt:

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

De populariteit van verschillende browsers ontdekken:

pageViews
| summarize count() by client_Browser

Als u paginaweergaven wilt koppelen aan AJAX-aanroepen, koppel met afhankelijkheden.

pageViews
| join (dependencies) on operation_Id

TrackRequest

De server-SDK gebruikt TrackRequest om HTTP-aanvragen te registreren.

U kunt deze ook zelf aanroepen als u aanvragen wilt simuleren in een context waarin de webservicemodule niet wordt uitgevoerd.

De aanbevolen manier om aanvraagtelemetrie te verzenden, is waar de aanvraag fungeert als een bewerkingscontext.

Bewerkingscontext

U kunt telemetrie-items aan elkaar correleren door ze te koppelen aan de bewerkingscontext. De standaardmodule voor het bijhouden van aanvragen doet dit voor uitzonderingen en andere gebeurtenissen die worden verzonden terwijl een HTTP-aanvraag wordt verwerkt. In Search and Analytics kunt u eenvoudig gebeurtenissen vinden die zijn gekoppeld aan de aanvraag met behulp van de bewerkings-id.

Wanneer u telemetrie handmatig bijhoudt, is de eenvoudigste manier om ervoor te zorgen dat telemetriecorrelatie dit patroon gebruikt:

// 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.

Naast het instellen van een bewerkingscontext, StartOperation maakt u een telemetrie-item van het type dat u opgeeft. Het telemetrie-item wordt verzonden wanneer u de bewerking hebt verwijderd of als u expliciet aanroept StopOperation. Als u als telemetrietype gebruikt RequestTelemetry , wordt de duur ervan ingesteld op het tijdsinterval tussen het begin en einde.

Telemetrie-items die binnen een bewerkingsbereik worden gerapporteerd, worden ondergeschikte componenten van een dergelijke bewerking. Bewerkingscontexten kunnen worden genest.

In Search wordt de bewerkingscontext gebruikt om de lijst Gerelateerde items te maken.

Zie Aangepaste bewerkingen bijhouden met Application Insights .NET SDK voor meer informatie over het bijhouden van aangepaste bewerkingen.

Aanvragen in Log Analytics

In Application Insights Analytics worden aanvragen weergegeven in de requests tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackRequest(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aanvragen en de gemiddelde duur wilt ophalen die is gesegmenteerd op aanvraagnamen, gebruikt u code zoals:

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

TrackException

Uitzonderingen verzenden naar Application Insights:

• Om ze te tellen als indicatie van de frequentie van een probleem.
• Afzonderlijke exemplaren onderzoeken.

De rapporten bevatten de stacktraceringen.

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

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

De SDK's vangen automatisch veel uitzonderingen op, dus u hoeft niet altijd expliciet aan te roepen TrackException .

Uitzonderingen in Log Analytics

In Application Insights Analytics worden uitzonderingen weergegeven in de exceptions tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackException(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal uitzonderingen wilt ophalen dat is gesegmenteerd op type uitzondering, gebruikt u code zoals:

exceptions
| summarize sum(itemCount) by type

De meeste belangrijke stackgegevens worden al geëxtraheerd in afzonderlijke variabelen, maar u kunt de details structuur uit elkaar trekken om meer te krijgen. Omdat deze structuur dynamisch is, moet u het resultaat casten naar het type dat u verwacht. Voorbeeld:

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

Als u uitzonderingen aan hun gerelateerde aanvragen wilt koppelen, gebruikt u een join:

exceptions
| join (requests) on operation_Id

TrackTrace

Gebruik TrackTrace dit om problemen te diagnosticeren door een 'breadcrumb trail' naar Application Insights te verzenden. U kunt segmenten met diagnostische gegevens verzenden en inspecteren in Diagnostisch zoeken.

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

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

Een diagnostische gebeurtenis registreren, zoals het invoeren of verlaten van een methode.

U kunt zoeken op berichtinhoud, maar in tegenstelling tot eigenschapswaarden kunt u er niet op filteren.

De limiet voor de grootte message is veel hoger dan de limiet voor eigenschappen. Een voordeel hiervan TrackTrace is dat u relatief lange gegevens in het bericht kunt plaatsen. U kunt bijvoorbeeld POST-gegevens daar coderen.

U kunt ook een ernstniveau toevoegen aan uw bericht. En net als andere telemetrie kunt u eigenschapswaarden toevoegen om u te helpen bij het filteren of zoeken naar verschillende sets traceringen. Voorbeeld:

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

In Zoeken kunt u vervolgens eenvoudig alle berichten van een bepaald ernstniveau filteren die betrekking hebben op een bepaalde database.

Traceringen in Log Analytics

In Application Insights Analytics worden aanroepen weergegeven TrackTrace in de traces tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackTrace(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal traceringsoproepen wilt ophalen, gebruikt u code zoals traces | summarize sum(itemCount).

TrackDependency

Gebruik de TrackDependency aanroep om de reactietijden en slagingspercentages van aanroepen naar een extern codefragment bij te houden. De resultaten worden weergegeven in de afhankelijkheidsdiagrammen in de portal. Het volgende codefragment moet worden toegevoegd waar een afhankelijkheidsaanroep wordt gedaan.

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

Houd er rekening mee dat de server-SDK's een afhankelijkheidsmodule bevatten waarmee bepaalde afhankelijkheidsaanroepen automatisch worden gedetecteerd en bijgehouden, bijvoorbeeld naar databases en REST API's. U moet een agent op uw server installeren om de module te laten werken.

U gebruikt deze aanroep als u oproepen wilt bijhouden die niet door de automatische tracering worden geregistreerd.

Als u de standaardmodule voor het bijhouden van afhankelijkheden in C# wilt uitschakelen, bewerkt uApplicationInsights.config en verwijdert u de verwijzing naar DependencyCollector.DependencyTrackingTelemetryModule.

Afhankelijkheden in Log Analytics

In Application Insights AnalyticstrackDependency worden aanroepen weergegeven in de dependencies tabel.

Als er steekproeven worden genomen , wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackDependency(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal afhankelijkheden wilt ophalen dat per doelonderdeel is gesegmenteerd, gebruikt u code zoals:

dependencies
| summarize sum(itemCount) by target

Als je afhankelijkheden aan hun gerelateerde aanvragen wilt koppelen, gebruik je een join.

dependencies
| join (requests) on operation_Id

Gegevens leegmaken

Normaal gesproken verzendt de SDK gegevens met vaste intervallen, meestal 30 seconden of wanneer de buffer vol is, wat meestal 500 items is. In sommige gevallen wilt u de buffer mogelijk leegmaken. Een voorbeeld is als u de SDK gebruikt in een toepassing die wordt afgesloten.

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

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

telemetry.flush();

Geverifieerde gebruikers

In een web-app worden gebruikers standaard geïdentificeerd door cookies . Een gebruiker kan meerdere keren worden geteld als hij of zij toegang heeft tot uw app vanaf een andere computer of browser of als ze cookies verwijderen.

Als gebruikers zich aanmelden bij uw app, kunt u een nauwkeuriger aantal krijgen door de geverifieerde gebruikers-id in de browsercode in te stellen. Het is niet nodig om de werkelijke aanmeldingsnaam van de gebruiker te gebruiken. Het hoeft alleen een id te zijn die uniek is voor die gebruiker. Het mag geen spaties of een van de tekens ,;=|bevatten.

De gebruikers-id wordt ook ingesteld in een sessiecooky en verzonden naar de server. Als de server-SDK is geïnstalleerd, wordt de geverifieerde gebruikers-id verzonden als onderdeel van de contexteigenschappen van zowel client- als servertelemetrie. Vervolgens kunt u erop filteren en zoeken.

Als uw app gebruikers in accounts groepeert, kunt u ook een id voor het account doorgeven. Dezelfde tekenbeperkingen gelden.

In Metrics Explorer kunt u een grafiek maken waarmee gebruikers, geverifieerde en gebruikersaccounts worden geteld.

U kunt ook zoeken naar clientgegevenspunten met specifieke gebruikersnamen en accounts.

Uw gegevens filteren, zoeken en segmenteren met behulp van eigenschappen

U kunt eigenschappen en metingen koppelen aan uw gebeurtenissen, metrische gegevens, paginaweergaven, uitzonderingen en andere telemetriegegevens.

Eigenschappen zijn tekenreekswaarden die u kunt gebruiken om uw telemetrie in de gebruiksrapporten te filteren. Als uw app bijvoorbeeld verschillende games biedt, kunt u de naam van het spel koppelen aan elke gebeurtenis, zodat u kunt zien welke games populairder zijn.

Er geldt een limiet van 8.192 voor de tekenreekslengte. Als u grote stukken gegevens wilt verzenden, gebruikt u de berichtparameter van TrackTrace.

Metrische gegevens zijn numerieke waarden die grafisch kunnen worden weergegeven. U kunt bijvoorbeeld zien of er een geleidelijke toename is van de scores die uw gamers behalen. De grafieken kunnen worden gesegmenteerd door de eigenschappen die met de gebeurtenis worden verzonden, zodat u afzonderlijke of gestapelde grafieken voor verschillende games kunt krijgen.

Metrische waarden moeten groter zijn dan of gelijk zijn aan 0 om correct weer te geven.

Er gelden enkele limieten voor het aantal eigenschappen, eigenschapswaarden en metrische gegevens die u kunt gebruiken.

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

Alternatieve manier om eigenschappen en metrische gegevens in te stellen

Als het handiger is, kunt u de parameters van een gebeurtenis in een afzonderlijk object verzamelen:

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

Aangepaste metingen en eigenschappen in Log Analytics

In Log Analytics worden aangepaste metrische gegevens en eigenschappen weergegeven in de customMeasurements en customDimensions kenmerken van elke telemetrierecord.

Als u bijvoorbeeld een eigenschap met de naam 'game' toevoegt aan uw aanvraagtelemetrie, telt deze query het aantal exemplaren van verschillende waarden van 'game' en toont het gemiddelde van de aangepaste metrische waarde 'score':

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

U ziet dat:

• Wanneer u een waarde uit de customDimensions of customMeasurements JSON extraheert, heeft deze een dynamisch type, dus moet u deze tostring casten of todouble.
• Om rekening te houden met de mogelijkheid van steekproeven, gebruik sum(itemCount) niet count().

Tijdgebeurtenissen

Soms wilt u een grafiek maken hoe lang het duurt om een actie uit te voeren. U wilt bijvoorbeeld weten hoelang gebruikers rekening houden met keuzes in een game. Gebruik de meetparameter om deze informatie te verkrijgen.

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

Standaardeigenschappen voor aangepaste telemetrie

Als u standaardeigenschapswaarden wilt instellen voor een aantal van de aangepaste gebeurtenissen die u schrijft, stelt u deze in een TelemetryClient instantie in. Ze worden gekoppeld aan elk telemetrie-item dat vanaf die client wordt verzonden.

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

Afzonderlijke telemetrie-aanroepen kunnen de standaardwaarden in hun eigenschapswoordenlijsten overschrijven.

Als u eigenschappen wilt toevoegen aan alle telemetriegegevens, inclusief de gegevens uit standaardverzamelingsmodules, implementeert u ITelemetryInitializer.

Telemetrie uitschakelen

De verzameling en verzending van telemetrie dynamisch stoppen en starten :

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

Ontwikkelaarsmodus

Tijdens foutopsporing is het handig om uw telemetrie te laten versnellen via de pijplijn, zodat u direct resultaten kunt zien. U krijgt ook andere berichten waarmee u problemen met de telemetrie kunt traceren. Schakel het uit in de productieomgeving omdat uw app kan vertragen.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

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

De instrumentatiesleutel instellen voor geselecteerde aangepaste telemetrie

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

Dynamische verbindingsreeks

Om te voorkomen dat telemetrie wordt vermengd vanuit ontwikkel-, test- en productieomgevingen, kunt u afzonderlijke Application Insights-resources maken en hun sleutels wijzigen, afhankelijk van de omgeving.

In plaats van de instrumentatiesleutel op te halen uit het configuratiebestand, kunt u deze instellen in uw code. Stel de sleutel in een initialisatiemethode in, zoals global.aspx.cs in een ASP.NET-service:

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

TelemetryContext

TelemetryClient heeft een contexteigenschap, die waarden bevat die samen met alle telemetriegegevens worden verzonden. Ze worden normaal gesproken ingesteld door de standaardtelemetriemodules, maar u kunt ze ook zelf instellen. Voorbeeld:

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

Als u een van deze waarden zelf instelt, kunt u overwegen om de relevante regel uit ApplicationInsights.config te verwijderen, zodat uw waarden en de standaardwaarden niet in de war raken.

• Onderdeel: de app en de bijbehorende versie.
• Apparaat: gegevens over het apparaat waarop de app wordt uitgevoerd. In web-apps is het de server of het clientapparaat waaruit de telemetrie wordt verzonden.
• InstrumentationKey: de Application Insights-resource in Azure waar de telemetrie wordt weergegeven. Het wordt meestal opgehaald uit ApplicationInsights.config.
• Locatie: De geografische locatie van het apparaat.
• Bewerking: In webapplicaties de huidige HTTP-aanvraag. In andere app-typen kunt u deze waarde instellen om gebeurtenissen samen te groeperen.
  • Id: Een gegenereerde waarde die verschillende gebeurtenissen correleert, zodat u gerelateerde items kunt vinden wanneer u een gebeurtenis inspecteert in diagnostische zoekopdrachten.
  • Naam: een id, meestal de URL van de HTTP-aanvraag.
  • SyntheticSource: Als deze niet null of leeg is, geeft een string aan dat de bron van het verzoek is geïdentificeerd als een robot of webtest. Standaard wordt deze uitgesloten van berekeningen in Metrics Explorer.
• Sessie: de sessie van de gebruiker. De id wordt ingesteld op een gegenereerde waarde, die wordt gewijzigd wanneer de gebruiker al een tijdje niet actief is geweest.
• Gebruiker: Gebruikersgegevens.

Limits

Er gelden enkele beperkingen voor het aantal meetgegevens en gebeurtenissen per toepassing, per instrumentatiesleutel. De limieten zijn afhankelijk van de prijscategorie die u kiest.

Zie Application Insights-facturering voor meer informatie over prijzen en quota.

Gebruik steekproeven om te voorkomen dat de gegevenssnelheidslimiet wordt bereikt.

Zie Gegevensretentie en privacy om te bepalen hoe lang gegevens worden bewaard.

Voorbeeldtoepassingen

.NET Core-consoletoepassing: gebruik dit voorbeeld als u een consoletoepassing gebruikt die is geschreven in .NET Core (2.0 of hoger) of .NET Framework (4.7.2 of hoger).

ASP.NET Core-achtergrondtaken met HostedServices: Gebruik dit voorbeeld als u in ASP.NET Core achtergrondtaken maakt in overeenstemming met de officiële richtlijnen.

.NET Core Worker-service: gebruik dit voorbeeld als u een .NET Worker-servicetoepassing hebt in overeenstemming met de officiële richtlijnen.

Probleemoplossingsproces

Zie het speciale artikel over probleemoplossing.

Connectiviteit testen tussen uw toepassingshost en de opnameservice

De SDKs en agents van Application Insights verzenden telemetrie zodat deze als REST-aanroepen naar onze opname-eindpunten kan worden verzonden. U kunt de connectiviteit vanaf uw webserver of hostmachine van uw toepassing naar de ingestiedienst-eindpunten testen door gebruik te maken van onbewerkte REST-clients met PowerShell of curl-opdrachten. Zie Problemen met ontbrekende toepassingstelemetrie oplossen in Azure Monitor Application Insights.

Opensource-SDK

Lezen en bijdragen aan de code.

Raadpleeg de releaseopmerkingen voor de meest recente updates en bugfixes.

Opmerkingen bij de release

Voor versie 2.12 en hoger: .NET Software Development Kits (SDK's), waaronder ASP.NET, ASP.NET Core en Logboekregistratieadapters

Onze service-updates geven ook een overzicht van belangrijke Application Insights-verbeteringen.

Volgende stappen

• Als u veelgestelde vragen (FAQ) wilt bekijken, raadpleegt u:
  • Veelgestelde vragen over Application Insights voor ASP.NET
  • Veelgestelde vragen over Application Insights voor ASP.NET Core
  • Veelgestelde vragen over Worker Service-toepassingen
  • Veelgestelde vragen over Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens
• Controleer of u een ondersteunde versie van de Application Insights SDK uitvoert.
• Bekijk het gegevensmodel voor Application Insights-typen en -gegevensmodellen.
• Voeg synthetische transacties toe om te testen of uw website overal ter wereld beschikbaar is met beschikbaarheidsbewaking.
• Raadpleeg de gebruikershandleiding System.Diagnostics.Activity om te zien hoe telemetrie wordt gecorreleerd.
• Configureer een verzameling momentopnamen om de status van broncode en variabelen te bekijken op het moment dat er een uitzondering wordt gegenereerd.

Naslagdocumentatie

• Naslaginformatie over gegevenstypen voor ASP.NET SDK en ASP.NET Core SDK.
• SDK-code voor ASP.NET SDK en ASP.NET Core SDK.