Azure API Management integreren met Azure Application Insights

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

U kunt eenvoudig Azure-toepassing Insights integreren met Azure API Management. Azure Application Insights is een uitbreidbare service voor webontwikkelaars die apps bouwen en beheren op meerdere platforms. In deze handleiding gaat u het volgende doen:

  • Doorloop de integratie van Application Insights in API Management.
  • Leer strategieën voor het verminderen van de invloed op prestaties op uw API Management-service-exemplaar.

Vereisten

  • U hebt een Azure API Management-exemplaar nodig. Maak er eerst een .

  • Als u Application Insights wilt gebruiken, maakt u een exemplaar van de Application Insights-service. Zie Application Insights-resources op basis van werkruimten om een exemplaar te maken met behulp van Azure Portal.

    Notitie

    De Application Insights-resource kan zich in een ander abonnement of zelfs een andere tenant bevinden dan de API Management-resource.

  • Als u van plan bent om een beheerde identiteit te configureren voor API Management voor gebruik met Application Insights, moet u de volgende stappen uitvoeren:

    1. Schakel een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in voor API Management in uw API Management-exemplaar.

      • Als u een door de gebruiker toegewezen beheerde identiteit inschakelt, noteert u de client-id van de identiteit.

    2. Wijs de identiteit toe aan de rol Monitoring Metrics Publisher , binnen het bereik van de Application Insights-resource. Als u de rol wilt toewijzen, gebruikt u Azure Portal of andere Azure-hulpprogramma's.

Overzicht van scenario

Hieronder volgen de stappen op hoog niveau voor dit scenario.

  1. Eerst maakt u een verbinding tussen Application Insights en API Management

    U kunt een verbinding maken tussen Application Insights en UW API Management met behulp van Azure Portal, de REST API of gerelateerde Azure-hulpprogramma's. API Management configureert een loggerresource voor de verbinding.

    Notitie

    Als uw Application Insights-resource zich in een andere tenant bevindt, moet u de logboekregistratie maken met behulp van de REST API.

    Belangrijk

    Momenteel ondersteunt API Management in de portal alleen verbindingen met Application Insights met behulp van een Application Insights-instrumentatiesleutel. Als u een Application Insights-verbindingsreeks of een door API Management beheerde identiteit wilt gebruiken, gebruikt u de REST API, Bicep of ARM-sjabloon om de logboekregistratie te maken. Meer informatie over Application Insights-verbindingsreeks s.

  2. Ten tweede schakelt u Application Insights-logboekregistratie in voor uw API of API's.

    In dit artikel schakelt u Application Insights-logboekregistratie in voor uw API met behulp van Azure Portal. API Management configureert een diagnostische resource voor de API.

Een verbinding maken met behulp van Azure Portal

Volg deze stappen om Azure Portal te gebruiken om een verbinding te maken tussen Application Insights en API Management.

  1. Navigeer naar uw Azure API Management-service-exemplaar in Azure Portal.

  2. Selecteer Application Insights in het menu aan de linkerkant.

  3. Selecteer +Toevoegen.
    Schermopname die laat zien waar een nieuwe verbinding moet worden toegevoegd

  4. Selecteer het Application Insights-exemplaar dat u eerder hebt gemaakt en geef een korte beschrijving op.

  5. Als u beschikbaarheidsbewaking van uw API Management-exemplaar in Application Insights wilt inschakelen, schakelt u het selectievakje Beschikbaarheidsmonitor toevoegen in.

    • Met deze instelling wordt regelmatig gecontroleerd of het EINDPUNT van de API Management-gateway reageert.
    • Resultaten worden weergegeven in het deelvenster Beschikbaarheid van het Application Insights-exemplaar.

  6. Selecteer Maken.

  7. Controleer of de nieuwe Application Insights-logboekregistratie nu wordt weergegeven in de lijst.

    Schermopname van waar u de zojuist gemaakte Application Insights-logboekregistratie kunt bekijken.

Notitie

Achter de schermen wordt een logboekentiteit gemaakt in uw API Management-exemplaar met de instrumentatiesleutel van het Application Insights-exemplaar.

Tip

Als u de instrumentatiesleutel moet bijwerken die is geconfigureerd in de Application Insights-logboekregistratie, selecteert u de rij van de logboekregistratie in de lijst (niet de naam van de logboekregistratie). Voer de instrumentatiesleutel in en selecteer Opslaan.

Een verbinding maken met behulp van de REST API, Bicep of ARM-sjabloon

Volg deze stappen om de REST API, Bicep of ARM-sjabloon te gebruiken om een verbinding te maken tussen Application Insights en API Management. U kunt een logboekregistratie configureren die gebruikmaakt van een verbindingsreeks, door het systeem toegewezen beheerde identiteit of door de gebruiker toegewezen beheerde identiteit.

Logboekregistratie met verbindingsreeks referenties

De Application Insights-verbindingsreeks wordt weergegeven in de sectie Overzicht van uw Application Insights-resource.

Gebruik de REST API van API Management met de volgende aanvraagbody.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Logboekregistratie met door het systeem toegewezen beheerde identiteitreferenties

Zie de vereisten voor het gebruik van een beheerde API Management-identiteit.

Gebruik de REST API van API Management met de volgende aanvraagbody.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Logboekregistratie met door de gebruiker toegewezen beheerde identiteitreferenties

Zie de vereisten voor het gebruik van een beheerde API Management-identiteit.

Gebruik de REST API van API Management met de volgende aanvraagbody.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Application Insights-logboekregistratie inschakelen voor uw API

Gebruik de volgende stappen om Application Insights-logboekregistratie in te schakelen voor een API. U kunt Application Insights-logboekregistratie ook inschakelen voor alle API's.

  1. Navigeer naar uw Azure API Management-service-exemplaar in Azure Portal.

  2. Selecteer API's in het menu aan de linkerkant.

  3. Klik op uw API, in dit geval Demo Conference API. Als deze is geconfigureerd, selecteert u een versie.

    Tip

    Als u logboekregistratie voor alle API's wilt inschakelen, selecteert u Alle API's.

  4. Ga vanaf de bovenste balk naar het tabblad Instellingen.

  5. Schuif omlaag naar de sectie Diagnostische logboeken .
    App Insights-logboekregistratie

  6. Schakel het selectievakje Inschakelen in .

  7. Selecteer de gekoppelde logger in de vervolgkeuzelijst Bestemming .

  8. Voer 100 in als sampling (%) en schakel het selectievakje Altijd logboekfouten in.

  9. Laat de rest van de instellingen staan. Zie de naslaginformatie over de instellingen voor diagnostische logboeken voor meer informatie over de instellingen.

    Waarschuwing

    Als u het standaardaantal nettoladingbytes voor logboekwaarde0 overschrijft, kunnen de prestaties van uw API's aanzienlijk afnemen.

  10. Selecteer Opslaan.

  11. Achter de schermen wordt een diagnostische entiteit met de naam applicationinsights gemaakt op API-niveau.

Notitie

Aanvragen zijn geslaagd zodra API Management het volledige antwoord naar de client verzendt.

Loggers voor één API of alle API's

U kunt logboekregistraties opgeven op verschillende niveaus:

  • Logboekregistratie voor één API
  • Een logboekregistratie voor alle API's

Geef beide op:

  • Standaard overschrijft de afzonderlijke API-logboekregistratie (meer gedetailleerd niveau) de logboekregistratie voor alle API's.
  • Als de logboekregistraties die zijn geconfigureerd op de twee niveaus verschillen en u beide loggers nodig hebt om telemetrie (multiplexing) te ontvangen, neemt u contact op met Microsoft Ondersteuning. Houd er rekening mee dat multiplexing niet wordt ondersteund als u dezelfde logboekregistratie (Application Insights-bestemming) gebruikt op het niveau Alle API's en het niveau van één API. Om multiplexing correct te laten werken, moet u verschillende logboekregistraties configureren op het niveau 'Alle API's' en afzonderlijke API's en hulp vragen van Microsoft-ondersteuning om multiplexing in te schakelen voor uw service.

Welke gegevens worden toegevoegd aan Application Insights

Application Insights ontvangt:

Telemetrie-item Beschrijving
Aanvragen Voor elke binnenkomende aanvraag:
  • front-endaanvraag
  • front-endantwoord
Afhankelijkheid Voor elke aanvraag die wordt doorgestuurd naar een back-endservice:
  • back-endaanvraag
  • back-endantwoord
Uitzondering Voor elke mislukte aanvraag:
  • Mislukt vanwege een gesloten clientverbinding
  • Er is een on-error-sectie van het API-beleid geactiveerd
  • Heeft een HTTP-antwoordstatuscode die overeenkomt met 4xx of 5xx
Trace Als u een traceringsbeleid configureert.
De severity instelling in het trace beleid moet gelijk zijn aan of groter zijn dan de verbosity instelling in de Application Insights-logboekregistratie.

Notitie

Zie Application Insights-limieten voor informatie over de maximale grootte en het aantal metrische gegevens en gebeurtenissen per Application Insights-exemplaar.

Aangepaste metrische gegevens verzenden

U kunt aangepaste metrische gegevens verzenden naar Application Insights vanuit uw API Management-exemplaar. API Management verzendt aangepaste metrische gegevens met behulp van het beleid voor metrische gegevens verzenden.

Notitie

Aangepaste metrische gegevens zijn een preview-functie van Azure Monitor en onderhevig aan beperkingen.

Voer de volgende configuratiestappen uit om aangepaste metrische gegevens te verzenden.

  1. Schakel aangepaste metrische gegevens (preview) in met aangepaste dimensies in uw Application Insights-exemplaar.

    1. Navigeer naar uw Application Insights-exemplaar in de portal.
    2. Selecteer In het linkermenu Gebruik en geschatte kosten.
    3. Selecteer Aangepaste metrische gegevens (preview)>met dimensies.
    4. Selecteer OK.

  2. Voeg de "metrics": true eigenschap toe aan de applicationInsights diagnostische entiteit die is geconfigureerd in API Management. Op dit moment moet u deze eigenschap toevoegen met behulp van de API Management Diagnostic - REST API maken of bijwerken . Voorbeeld:

    PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

  3. Zorg ervoor dat de Application Insights-logboekregistratie is geconfigureerd voor het bereik dat u wilt verzenden van aangepaste metrische gegevens (alle API's of één API). Zie Application Insights-logboekregistratie inschakelen voor uw API, eerder in dit artikel voor meer informatie.

  4. Configureer het emit-metric beleid in een bereik waarin Application Insights-logboekregistratie is geconfigureerd (alle API's of één API) en is ingeschakeld voor aangepaste metrische gegevens. Zie de emit-metric beleidsreferentie voor meer informatie.

Limieten voor aangepaste metrische gegevens

Azure Monitor legt gebruikslimieten op voor aangepaste metrische gegevens die van invloed kunnen zijn op uw mogelijkheid om metrische gegevens uit API Management te verzenden. Azure Monitor stelt bijvoorbeeld momenteel een limiet van 10 dimensiesleutels per metrische waarde in en een limiet van 50.000 totale actieve tijdreeksen per regio in een abonnement (binnen een periode van 12 uur).

Deze limieten hebben de volgende gevolgen voor het configureren van aangepaste metrische gegevens in API Management:

  • U kunt maximaal 10 aangepaste dimensies per emit-metric beleid configureren.

  • Het aantal actieve tijdreeksen dat door het emit-metric beleid binnen een periode van 12 uur wordt gegenereerd, is het product van het aantal unieke waarden van elke geconfigureerde dimensie gedurende de periode. Als er bijvoorbeeld drie aangepaste dimensies zijn geconfigureerd in het beleid en elke dimensie 10 mogelijke waarden binnen de periode had, zou het emit-metric beleid 1000 (10 x 10 x 10) actieve tijdreeksen bijdragen.

  • Als u het emit-metric beleid configureert in meerdere API Management-exemplaren die zich in dezelfde regio in een abonnement bevinden, kunnen alle exemplaren bijdragen aan de regionale limiet voor actieve tijdreeksen.

Gevolgen voor prestaties en steekproeven nemen uit logboeken

Waarschuwing

Het vastleggen van alle gebeurtenissen in logboeken kan ernstige gevolgen hebben voor de prestaties, afhankelijk van de hoeveelheid binnenkomende aanvragen.

Op basis van interne belastingstests is berekend dat het inschakelen van de functie voor logboekregistratie een doorvoervermindering van 40%-50% veroorzaakt wanneer de aanvraagsnelheid 1000 aanvragen per seconde overschrijdt. Application Insights is ontworpen om de prestaties van toepassingen te beoordelen met behulp van statistische analyse. Het is niet:

  • Bedoeld als controlesysteem.
  • Geschikt voor het vastleggen van elke afzonderlijke aanvraag voor API's met grote volumes.

U kunt het aantal geregistreerde aanvragen bewerken door de instelling Sampling aan te passen. Een waarde van 100% betekent dat alle aanvragen worden geregistreerd, terwijl 0% geen logboekregistratie weergeeft.

Steekproef nemen helpt het telemetrievolume te verminderen, waardoor aanzienlijke prestatievermindering effectief wordt voorkomen terwijl de voordelen van logboekregistratie blijven bestaan.

Als u de prestaties wilt verbeteren, slaat u het volgende over:

  • Aanvraag- en reactieheaders.
  • Logboekregistratie van hoofdteksten.

Video

Probleemoplossing

Het probleem van telemetriegegevensstroom van API Management naar Application Insights oplossen:

  • Onderzoek of een gekoppelde Azure Monitor Private Link Scope-resource (AMPLS) bestaat in het VNet waar de API Management-resource is verbonden. AMPLS-resources hebben een globaal bereik voor abonnementen en zijn verantwoordelijk voor het beheren van gegevensquery's en -opname voor alle Azure Monitor-resources. Het is mogelijk dat de AMPLS is geconfigureerd met een alleen-privétoegangsmodus die specifiek is bedoeld voor gegevensopname. Neem in dergelijke gevallen de Application Insights-resource en de bijbehorende Log Analytics-resource op in de AMPLS. Zodra deze toevoeging is gemaakt, worden de API Management-gegevens opgenomen in de Application Insights-resource, waardoor het probleem met telemetriegegevensoverdracht wordt opgelost.

Volgende stappen