Azure API Management integreren met Azure-toepassing Insights

TOEPASBAAR OP: Alle API Management-niveaus

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

  • Verken 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.

Note

In een API Management-werkruimte kan een eigenaar van een werkruimte onafhankelijk Application Insights integreren en Application Insights-logboekregistratie inschakelen voor de API's van de werkruimte. De algemene richtlijnen voor het integreren van een werkruimte met Application Insights zijn vergelijkbaar met de richtlijnen voor een API Management-exemplaar; De configuratie is echter alleen gericht op de werkruimte. Op dit moment moet u Application Insights integreren in een werkruimte door een verbindingsreeks (aanbevolen) of een instrumentatiesleutel te configureren.

Warning

Wanneer u onze zelf-hostende gateway gebruikt, garanderen we niet dat alle telemetrie naar Azure-toepassing Insights wordt gepusht, omdat deze afhankelijk is van buffering in het geheugen van Application Insights.

Prerequisites

  • Maak een Azure API Management-exemplaar.

  • Maak een exemplaar van de Application Insights-service. Om een instantie te maken met behulp van het Azure-portaal, zie Workspace-based Application Insights-resources.

    Note

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

  • Als u van plan bent om referenties voor beheerde identiteiten te configureren voor gebruik met Application Insights, voert u de volgende stappen uit:

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

      • 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 in de context van de Application Insights-resource. Als u de rol wilt toewijzen, gebruikt u Azure Portal of andere Azure-hulpprogramma's.

Overzicht van scenario

De volgende stappen geven een overzicht van dit scenario op hoog niveau.

  1. Maak 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.

    Important

    Momenteel ondersteunt API Management in de portal alleen verbindingen met Application Insights met behulp van een Application Insights-instrumentatiesleutel. Voor verbeterde beveiliging gebruik je een Application Insights-verbindingsreeks met een beheerde identiteit van API Management. Als u verbindingsreeks wilt configureren met referenties voor beheerde identiteiten, gebruikt u de REST API of gerelateerde hulpprogramma's, zoals wordt weergegeven in een latere sectie van dit artikel. Zie Verbindingsreeksen in Application Insights voor meer informatie.

    Note

    Als je Application Insights-bron in een andere tenant zit, maak dan de logger aan met behulp van de REST API of gerelateerde tools, zoals in een latere sectie van dit artikel wordt getoond.

  2. Schakel 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.

Maak een verbinding aan door gebruik te maken van het Azure-portaal

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

Note

Waar mogelijk raadt Microsoft aan om gebruik te maken van verbindingstrings met beheerde identiteitsreferenties voor verbeterde beveiliging. Als u deze referenties wilt configureren, gebruikt u de REST API of gerelateerde hulpprogramma's, zoals wordt weergegeven in een latere sectie van dit artikel.

  1. Ga naar je Azure API Management service-instantie in het Azure portal.

  2. Selecteer Application Insights onder Bewaking in het zijbalkmenu.

  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.

    • Deze instelling controleert regelmatig of het API-beheergateway-endpoint reageert.
    • Resultaten worden weergegeven in het deelvenster Beschikbaarheid van het Application Insights-exemplaar.

  6. Klik op Creëren.

  7. Controleer of de nieuwe Application Insights-logger nu in de lijst te zien is.

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

Note

Achter de schermen wordt een logger-entiteit gemaakt in uw API Management-instantie, met de instrumentatiesleutel van de Application Insights-instantie.

Tip

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

Maak een verbinding door gebruik te maken van de REST API, Bicep of ARM-sjabloon

Volg deze stappen om de REST API, Bicep of ARM-sjabloon te gebruiken om een Application Insights-logboekregistratie te maken voor uw API Management-exemplaar. Je kunt een logger configureren die een verbindingsreeks gebruikt met managed identity credentials (aanbevolen), of een logger die alleen een verbindingsreeks gebruikt.

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

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

Verbindingsreeks met door het systeem toegewezen beheerde identiteit

Gebruik de API Management Logger - REST API maken of bijwerken met de volgende aanvraagbody.

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

Verbindingsreeks met door de gebruiker toegewezen beheerde identiteit

Gebruik de API Management Logger - REST API maken of bijwerken met de volgende aanvraagbody.

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

Logger met alleen verbindingsreeksreferenties

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

Gebruik de API Management Logger - REST API maken of bijwerken met de volgende aanvraagbody.

Als u de logger voor een werkruimte configureert, gebruikt u de Workspace Logger - Create or Update REST API.

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

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. Ga naar je Azure API Management service-instantie in het Azure portal.

  2. Selecteer API's>API’s in het zijbalkmenu.

  3. Selecteer een API, zoals Swagger Petstore. Als deze is geconfigureerd, selecteert u een versie.

    Tip

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

  4. Selecteer het tabblad Instellingen op de bovenste balk.

  5. Scroll omlaag naar de sectie Diagnostische logboeken en vink het vakje Inschakelen aan. Schermopname van de configuratie van diagnostische logboeken in de portal.

  6. Selecteer de gekoppelde logger in de Bestemming vervolgkeuzelijst.

  7. Voer 100 in als Sampling (%) en selecteer het vakje 'Altijd fouten loggen '.

  8. Laat de rest van de instellingen staan. Bekijk de instellingenreferentie voor diagnostische logboeken voor meer details over de instellingen.

    Warning

    Het overschrijven van het standaard aantal payloadbytes tot logwaarde0 kan de prestaties van je API's aanzienlijk verminderen.

  9. Selecteer Opslaan.

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

Note

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

Loggers voor één API of alle API's

Je kunt loggers op verschillende niveaus specificeren:

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

Als je beide specificeert:

  • 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 te ontvangen (multiplexing), neemt u contact op met Microsoft Ondersteuning. Multiplexing wordt niet ondersteund als je dezelfde logger (Application Insights-bestemming) gebruikt op het "Alle API's"-niveau en op het enkele API-niveau. 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 Description
Request Voor elke binnenkomende aanvraag:
  • front-endverzoek
  • frontend reactie
Dependency Automatische externe afhankelijkheidstelemetrie van ondersteunde beleidsuitvoering, inclusief verzoeken die worden doorgestuurd naar een backend-service.
Exception 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.

Telemetrie van externe afhankelijkheid voor ondersteunde beleidsmaatregelen

Nadat je Application Insights-logging hebt geconfigureerd en ingeschakeld, verzamelt API Management automatisch externe afhankelijkheidstelemetrie voor de volgende beleidslijnen. Er is geen extra beleids- of telemetrieconfiguratie nodig:

  • authentication-managed-identity
  • authentication-token
  • azure-openai-semantic-cache-lookup
  • cosmosdb-request-handler
  • forward-request
  • get-authorization-context
  • http-data-source
  • invoke-dapr-binding
  • llm-content-safety
  • llm-semantic-cache-lookup
  • send-request
  • send-one-way-request
  • send-service-bus-message
  • sql-data-source
  • validate-jwt

Application Insights registreert deze externe oproepen als gecorreleerde kindoperaties. Je kunt bijvoorbeeld herhalingspogingen, het ophalen van OpenID Connect-metadata door validate-jwt, het verzenden via Service Bus of het doorsturen naar de backend zien als gerelateerde bewerkingen. Om de telemetrie in het Azure-portaal te verifiëren, opent u Details van end-to-end-transacties in uw Application Insights-resource en bekijkt u de gerelateerde bewerkingen voor een aanvraag.

Momenteel wordt het bijhouden van afhankelijkheden alleen ondersteund voor de beleidsregels in de bovenstaande lijst.

Note

Voor informatie over de maximale grootte en het aantal metrics en gebeurtenissen per Application Insights-instantie, zie Application Insights-limieten.

Aangepaste metrische gegevens verzenden

U kunt aangepaste metrische gegevens verzenden naar Application Insights vanuit uw API Management-exemplaar. API Management genereert aangepaste metrics door gebruik te maken van beleidsregels zoals emit-metric en llm-emit-token-metric. In de volgende sectie wordt het emit-metric beleid als voorbeeld gebruikt.

Note

Aangepaste metrics zijn een previewfunctie van Azure Monitor en zijn onderhevig aan beperkingen.

Om aangepaste metrics te genereren, voltooi je de volgende configuratiestappen:

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

    1. Ga naar je Application Insights-instantie in het portaal.
    2. Selecteer Onder Configureren in het zijbalkmenu de optie Gebruik en geschatte kosten.
    3. Selecteer Aangepaste metrieken (voorvertoning)>Met dimensies.
    4. Kies OK.

  2. Voeg de "metrics": true eigenschap toe aan de applicationInsights diagnostische entiteit die je configureert in API Management. Momenteel moet je deze eigenschap toevoegen door gebruik te maken van de API Management Diagnostic - Create or Update REST API. Voorbeeld:

    PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
        "metrics": true
        [...]
    }
  }
}

  3. Zorg ervoor dat de Application Insights-logger is geconfigureerd op het bereik waar je aangepaste metrics wilt genereren (alle API's of één enkele API). Zie Application Insights-logboekregistratie inschakelen voor uw API, eerder in dit artikel voor meer informatie.

  4. Configureer het emit-metric beleid op een scope waar Application Insights-logging is geconfigureerd (ofwel alle API's of één enkele API) en ingeschakeld is voor aangepaste metrics. 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). In API Management worden 5 van deze gebruikt voor standaarddimensies, waaronder de volgende:

  • Region
  • Service-ID
  • Servicenaam
  • Diensttype

Deze limieten hebben de volgende gevolgen voor het configureren van aangepaste metrische gegevens in een API Management-beleid, zoals emit-metric of azure-openai-emit-token-metric:

  • U kunt maximaal 5 aangepaste dimensies per beleid configureren.

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

  • API Management beperkt elke dimensie tot 100 unieke waarden en elke metrieknaamruimte tot 1.000 actieve tijdreeksen. Wanneer een van beide limieten wordt bereikt, worden nieuwe dimensiewaarden of tijdreeksen niet bijgehouden en worden de bijbehorende metriekgegevens stilletjes weggegooid.

  • Als u het 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.

Meer informatie over ontwerpbeperkingen en overwegingen voor aangepaste metrische gegevens in Azure Monitor.

Gevolgen voor prestaties en steekproeven nemen uit logboeken

Warning

Het vastleggen van alle gebeurtenissen kan ernstige gevolgen hebben voor de prestaties, afhankelijk van de snelheid van 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:

  • Headers voor aanvragen en antwoorden
  • Logboekregistratie van hoofdtekst

Troubleshooting

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

  • Onderzoek of er een gekoppelde Azure Monitor Private Link Scope-resource (AMPLS) bestaat in het virtuele netwerk 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 Private-Only-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.

Verwante inhoud

  • Laatst bijgewerkt om