Dela via

Så integrerar du Azure API Management med Azure Application Insights

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

Du kan enkelt integrera Azure Application Insights med Azure API Management. Azure Application Insights är en utökningsbar tjänst för webbutvecklare som skapar och hanterar appar på flera plattformar. I den här guiden kommer du att:

  • Gå igenom Application Insights-integrering i API Management.
  • Lär dig strategier för att minska prestandapåverkan på din API Management-tjänstinstans.

Kommentar

På en API Management-arbetsyta kan en arbetsyteägare oberoende integrera Application Insights och aktivera Application Insights-loggning för arbetsytans API:er. Den allmänna vägledningen för att integrera en arbetsyta med Application Insights liknar vägledningen för en API Management-instans. Konfigurationen begränsas dock endast till arbetsytan. För närvarande måste du integrera Application Insights på en arbetsyta genom att konfigurera en anslutningssträng (rekommenderas) eller en instrumentationsnyckel.

Varning

När vi använder vår egen värdbaserade gateway garanterar vi inte att all telemetri skickas till Azure Application Insights eftersom den förlitar sig på Application Insights minnesintern buffring.

Förutsättningar

  • Du behöver en Azure API Management-instans. Skapa en först.

  • Om du vill använda Application Insights skapar du en instans av Application Insights-tjänsten. Information om hur du skapar en instans med hjälp av Azure Portal finns i Arbetsytebaserade Application Insights-resurser.

    Kommentar

    Application Insights-resursen kan finnas i en annan prenumeration eller till och med en annan klientorganisation än API Management-resursen.

  • Om du planerar att konfigurera autentiseringsuppgifter för hanterad identitet som ska användas med Application Insights utför du följande steg:

    1. Aktivera en systemtilldelad eller användartilldelad hanterad identitet för API Management.

      • Om du aktiverar en användartilldelad hanterad identitet noterar du identitetens klient-ID.

    2. Tilldela identiteten rollen Monitoring Metrics Publisher , som är begränsad till Application Insights-resursen. Om du vill tilldela rollen använder du Azure Portal eller andra Azure-verktyg.

Scenarioöversikt

Följande är steg på hög nivå för det här scenariot.

  1. Skapa först en anslutning mellan Application Insights och API Management

    Du kan skapa en anslutning mellan Application Insights och API Management med hjälp av Azure Portal, REST API eller relaterade Azure-verktyg. API Management konfigurerar en loggerresurs för anslutningen.

    Viktigt!

    I portalen stöder API Management för närvarande endast anslutningar till Application Insights med hjälp av en Application Insights-instrumentationsnyckel. För förbättrad säkerhet rekommenderar vi att du använder en Application Insights-anslutningssträng med en hanterad API Management-identitet. Om du vill konfigurera anslutningssträng med autentiseringsuppgifter för hanterad identitet använder du REST-API:et eller relaterade verktyg som visas i ett senare avsnitt i den här artikeln. Läs mer om Application Insights anslutningssträng s.

    Kommentar

    Om din Application Insights-resurs finns i en annan klientorganisation måste du skapa loggaren med hjälp av REST-API:et eller relaterade verktyg som visas i ett senare avsnitt i den här artikeln.

  2. För det andra aktiverar du Application Insights-loggning för ditt API eller API:er.

    I den här artikeln aktiverar du Application Insights-loggning för ditt API med hjälp av Azure Portal. API Management konfigurerar en diagnostikresurs för API:et.

Skapa en anslutning med hjälp av Azure Portal

Följ de här stegen för att använda Azure Portal för att skapa en anslutning mellan Application Insights och API Management.

Kommentar

Där det är möjligt rekommenderar Microsoft att du använder anslutningssträng med autentiseringsuppgifter för hanterad identitet för förbättrad säkerhet. Om du vill konfigurera dessa autentiseringsuppgifter använder du REST API eller relaterade verktyg som du ser i ett senare avsnitt i den här artikeln.

  1. Gå till azure API Management-tjänstinstansen i Azure Portal.

  2. Välj Application Insights på menyn till vänster.

  3. Markera + Lägg till.
    Skärmbild som visar var du lägger till en ny anslutning

  4. Välj den Application Insights-instans som du skapade tidigare och ange en kort beskrivning.

  5. Om du vill aktivera tillgänglighetsövervakning av DIN API Management-instans i Application Insights markerar du kryssrutan Lägg till tillgänglighetsövervakare .

    • Den här inställningen kontrollerar regelbundet om API Management-gatewayens slutpunkt svarar.
    • Resultaten visas i fönstret Tillgänglighet i Application Insights-instansen.

  6. Välj Skapa.

  7. Kontrollera att den nya Application Insights-loggaren nu visas i listan.

    Skärmbild som visar var du vill visa den nyligen skapade Application Insights-loggaren.

Kommentar

I bakgrunden skapas en loggningsentitet i din API Management-instans som innehåller instrumentationsnyckeln för Application Insights-instansen.

Dricks

Om du behöver uppdatera instrumentationsnyckeln som konfigurerats i Application Insights-loggaren väljer du loggningsraden i listan (inte namnet på loggaren). Ange instrumentationsnyckeln och välj Spara.

Skapa en anslutning med hjälp av MALLEN REST API, Bicep eller ARM

Följ de här stegen för att använda MALLEN REST API, Bicep eller ARM för att skapa en Application Insights-loggare för din API Management-instans. Du kan konfigurera en loggare som använder anslutningssträng med autentiseringsuppgifter för hanterad identitet (rekommenderas) eller en loggare som endast använder en anslutningssträng.

Se förutsättningarna för att använda en hanterad API Management-identitet.

Application Insights-anslutningssträng visas i avsnittet Översikt för din Application Insights-resurs.

Anslutningssträng med systemtilldelad hanterad identitet

Använd API Management Logger – Skapa eller uppdatera REST API med följande begärandetext.

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

Anslutningssträng med användartilldelad hanterad identitet

Använd API Management Logger – Skapa eller uppdatera REST API med följande begärandetext.

{
  "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":"<ClientID>"
    }
  }
}

Loggare med endast anslutningssträng autentiseringsuppgifter

Application Insights-anslutningssträng visas i avsnittet Översikt för din Application Insights-resurs.

Använd API Management Logger – Skapa eller uppdatera REST API med följande begärandetext.

Om du konfigurerar loggaren för en arbetsyta använder du REST-API:et Workspace Logger – Skapa eller uppdatera .

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

Aktivera Application Insights-loggning för ditt API

Använd följande steg för att aktivera Application Insights-loggning för ett API. Du kan också aktivera Application Insights-loggning för alla API:er.

  1. Gå till azure API Management-tjänstinstansen i Azure Portal.

  2. Välj API:er i menyn till vänster.

  3. Klicka på ditt API, i det här fallet Demo Conference API. Om du har konfigurerat väljer du en version.

    Dricks

    Om du vill aktivera loggning för alla API:er väljer du Alla API:er.

  4. Gå till fliken Inställningar i det övre fältet.

  5. Rulla ned till avsnittet Diagnostikloggar .
    App Insights-loggare

  6. Markera kryssrutan Aktivera .

  7. Välj den anslutna loggaren i listrutan Mål .

  8. Ange 100 som sampling (%) och markera kryssrutan Alltid loggfel .

  9. Låt resten av inställningarna vara som de är. Mer information om inställningarna finns i Referens för inställningar för diagnostikloggar.

    Varning

    Om du åsidosätter standardvärdet Antal nyttolastbyte till loggvärdet 0 kan det avsevärt minska prestandan för dina API:er.

  10. Välj Spara.

  11. I bakgrunden skapas en diagnostikentitet med namnet applicationinsights på API-nivå.

Kommentar

Begäranden lyckas när API Management skickar hela svaret till klienten.

Loggare för ett enda API eller alla API:er

Du kan ange loggare på olika nivåer:

  • Enskild API-loggare
  • En loggare för alla API:er

Anger båda:

  • Som standard åsidosätter den enskilda API-loggaren (mer detaljerad nivå) den för alla API:er.
  • Om loggarna som konfigurerats på de två nivåerna är olika och du behöver båda loggarna för att ta emot telemetri (multiplexing) kontaktar du Microsoft Support. Observera att multiplexering inte stöds om du använder samma loggning (Application Insights-mål) på nivån "Alla API:er" och den enskilda API-nivån. För att multiplexering ska fungera korrekt måste du konfigurera olika loggare på "Alla API:er" och enskild API-nivå och begära hjälp från Microsofts support för att aktivera multiplexering för din tjänst.

Vilka data läggs till i Application Insights

Application Insights tar emot:

Telemetriobjekt beskrivning
Begär För varje inkommande begäran:
  • klientdelsbegäran
  • klientdelssvar
Beroende För varje begäran som vidarebefordras till en serverdelstjänst:
  • serverdelsbegäran
  • serverdelssvar
Undantag För varje misslyckad begäran:
  • Det gick inte på grund av en sluten klientanslutning
  • Utlöste ett on-error-avsnitt av API-principerna
  • Har en http-statuskod för svar som matchar 4xx eller 5xx
Spårning Om du konfigurerar en spårningsprincip .
Inställningen severity i trace principen måste vara lika med eller större än verbosity inställningen i Application Insights-loggningen.

Kommentar

Se Application Insights-gränser för information om maximal storlek och antal mått och händelser per Application Insights-instans.

Generera anpassade mått

Du kan generera anpassade mått till Application Insights från din API Management-instans. API Management genererar anpassade mått med hjälp av principer som emit-metric och azure-openai-emit-token-metric. I följande avsnitt används emit-metric principen som ett exempel.

Kommentar

Anpassade mått är en förhandsversionsfunktion i Azure Monitor och omfattas av begränsningar.

Utför följande konfigurationssteg för att generera anpassade mått.

  1. Aktivera anpassade mått (förhandsversion) med anpassade dimensioner i Application Insights-instansen.

    1. Gå till Application Insights-instansen i portalen.
    2. I den vänstra menyn väljer du Användning och uppskattade kostnader.
    3. Välj Anpassade mått (förhandsversion)>Med dimensioner.
    4. Välj OK.

  2. "metrics": true Lägg till egenskapen till den diagnostikentitet applicationInsights som har konfigurerats i API Management. För närvarande måste du lägga till den här egenskapen med hjälp av API Management Diagnostic – Skapa eller uppdatera REST API. Till exempel:

    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. Kontrollera att Application Insights-loggaren har konfigurerats i det omfång som du tänker generera anpassade mått (antingen alla API:er eller ett enda API). Mer information finns i Aktivera Application Insights-loggning för ditt API tidigare i den här artikeln.

  4. emit-metric Konfigurera principen i ett omfång där Application Insights-loggning har konfigurerats (antingen alla API:er eller ett enda API) och är aktiverat för anpassade mått. Information om principer finns i principreferensen emit-metric .

Gränser för anpassade mått

Azure Monitor inför användningsgränser för anpassade mått som kan påverka din möjlighet att generera mått från API Management. Azure Monitor anger till exempel för närvarande en gräns på 10 dimensionsnycklar per mått och en gräns på 50 000 totala aktiva tidsserier per region i en prenumeration (inom en 12-timmarsperiod).

Dessa gränser har följande konsekvenser för att konfigurera anpassade mått i en API Management-princip som emit-metric eller azure-openai-emit-token-metric:

  • Du kan konfigurera högst 10 anpassade dimensioner per princip.

  • Antalet aktiva tidsserier som genereras av principen inom en 12-timmarsperiod är produkten av antalet unika värden för varje konfigurerad dimension under perioden. Om till exempel tre anpassade dimensioner konfigurerades i principen och varje dimension hade 10 möjliga värden inom perioden, skulle principen bidra med 1 000 aktiva tidsserier (10 x 10 x 10).

  • Om du konfigurerar principen i flera API Management-instanser som finns i samma region i en prenumeration kan alla instanser bidra till den regionala gränsen för aktiva tidsserier.

Läs mer om designbegränsningar och överväganden för anpassade mått i Azure Monitor.

Prestandakonsekvenser och loggsampling

Varning

Loggning av alla händelser kan ha allvarliga prestandakonsekvenser, beroende på frekvens för inkommande begäranden.

Baserat på interna belastningstester orsakade aktivering av loggningsfunktionen en minskning av dataflödet med 40–50 % när begärandefrekvensen överskred 1 000 begäranden per sekund. Application Insights är utformat för att utvärdera programprestanda med hjälp av statistisk analys. Det är inte:

  • Avsett att vara ett granskningssystem.
  • Passar för att logga varje enskild begäran för högvolym-API:er.

Du kan ändra antalet loggade begäranden genom att justera inställningen Sampling. Ett värde på 100 % innebär att alla begäranden loggas, medan 0 % innebär att inget loggas.

Sampling bidrar till att minska telemetrivolymen, vilket effektivt förhindrar betydande prestandaförsämring samtidigt som nyttan med loggning kvarstår.

Om du vill förbättra prestandaproblemen hoppar du över:

  • Begärande- och svarsrubriker.
  • Innehållsloggning.

Video

Felsökning

Åtgärda problemet med telemetridataflöde från API Management till Application Insights:

  • Undersöka om det finns en länkad AZURE Monitor Private Link-omfångsresurs (AMPLS) i det virtuella nätverk där API Management-resursen är ansluten. AMPLS-resurser har ett globalt omfång mellan prenumerationer och ansvarar för att hantera datafrågor och inmatning för alla Azure Monitor-resurser. Det är möjligt att AMPLS har konfigurerats med ett privat åtkomstläge specifikt för datainmatning. I sådana fall inkluderar du Application Insights-resursen och dess associerade Log Analytics-resurs i AMPLS. När det här tillägget har gjorts matas API Management-data in i Application Insights-resursen, vilket löser problemet med telemetridataöverföring.

Relaterat innehåll