Så integrerar du Azure API Management med Azure Application Insights

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.

Prerequisites

• Skapa en Azure API Management-instans.

• Skapa en instans av Application Insights-tjänsten. För att skapa en instans med hjälp av Azure-portalen, se Workspace-based Application Insights-resurser.

  Note

  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 inom Application Insights-resursen. Om du vill tilldela rollen använder du Azure Portal eller andra Azure-verktyg.

Scenarioöversikt

Följande steg ger en övergripande översikt av detta scenario.

1. Skapa en anslutning mellan Application Insights och API Management.

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

   Important

   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 ökad säkerhet, använd en Application Insights-reťazec pripojenia med en API Management-hanterad 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. Mer information finns i Anslutningssträngar i Application Insights.

   Note

   Om din Application Insights-resurs finns i en annan tenant, skapa loggaren med hjälp av REST API eller relaterade verktyg som visas i ett senare avsnitt av denna artikel.

2. Aktivera 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-portalen. API Management konfigurerar en diagnostikresurs för API:et.

Skapa en anslutning genom att använda Azure-portalen

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.

1. Gå till din Azure API Management-tjänsteinstans i Azure-portalen.

2. Under Övervakning i sidomenyn väljer du Application Insights.

3. Markera + Lägg till.
   

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 .

   • Denna inställning kontrollerar regelbundet om API-hanteringsgateway-endpointen 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.

   

Skapa en anslutning genom att använda REST API, Bicep eller ARM-mallen

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

Logger med anslutningssträng och autentiseringsuppgifter för hanterad identitet (rekommenderas)

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

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

Anslutningssträng med systemtilldelad hanterad identitet

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

Anslutningssträng med användartilldelad hanterad identitet

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

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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>'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<client-ID>"
    }
  }
}

Loggverktyg med autentisering via anslutningssträng

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

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<application-insights-resource-ID>",
    "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 din Azure API Management-tjänsteinstans i Azure-portalen.

2. Välj API:er>API:er från sidomenyn.

3. Välj ett API, till exempel Swagger Petstore. Om du har konfigurerat väljer du en version.

   Tip

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

4. Välj fliken Inställningar i det övre fältet.

5. Rulla ned till avsnittet Diagnostikloggar och markera kryssrutan Aktivera .

6. Välj den anslutna loggaren i listrutan för Destination.

7. Ange 100 som Sampling (%) och markera kryssrutan Logga alltid fel.

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

   Warning

   Att åsidosätta standardvärdet 0för antalet payload-bytes till loggvärdet kan avsevärt minska prestandan hos dina API:er.

9. Välj Spara.

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

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

Du kan specificera loggers på olika nivåer:

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

Om du specificerar 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. Multiplexing stöds inte om du använder samma logger (Application Insights-destination) på "Alla API:er"-nivå och på enda API-nivå. 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:

Extern beroendetelemetri för stödda policyer

Efter att du konfigurerat och aktiverat Application Insights-loggning samlar API-hanteringen automatiskt in extern beroendetelemetri för följande policyer. Ingen ytterligare policy eller telemetrikonfiguration krävs:

• 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 registrerar dessa externa samtal som korrelerade barnoperationer. Till exempel kan du se återförsök, hämtning av OpenID Connect-metadata av validate-jwt, en sändning till Service Bus eller vidarebefordran till serverdelen som relaterade operationer. För att verifiera telemetrin i Azure-portalen, öppna änd-till-änd-transaktionsdetaljer i din Application Insights-resurs och granska relaterade operationer för en förfrågan.

För närvarande stöds beroendespårning endast för policyerna i föregående lista.

Generera anpassade mått

Du kan generera anpassade mått till Application Insights från din API Management-instans. API-hantering skickar anpassade mätvärden genom att använda policyer som emit-metric och llm-emit-token-metric. I följande avsnitt används emit-metric principen som ett exempel.

För att generera anpassade mätvärden, utför följande konfigurationssteg:

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

   1. Gå till din Application Insights-instans i portalen.
   2. Under Konfigurera på sidomenyn väljer du Användning och uppskattade kostnader.
   3. Välj Anpassade mått (förhandsversion)>Med dimensioner.
   4. Välj OK.

2. Lägg till egenskapen "metrics": true i den applicationInsights diagnostiska entitet som du konfigurerar i API Management. För närvarande måste du lägga till denna egenskap genom att använda API Management Diagnostic - Create or Update REST API. Till exempel:

   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. Se till att Application Insights-loggaren är konfigurerad i det scope där du vill generera anpassade mätvärden (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. Konfigurera policyn emit-metric i en omfattning där Application Insights-loggning är konfigurerad (antingen alla API:er eller ett enda API) och är aktiverad för anpassade mätvärden. 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). I API Management används 5 av dessa för standarddimensioner, inklusive följande:

• Region
• Tjänst-ID
• Tjänstnamn
• Tjänsttyp

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 5 anpassade dimensioner per policy.

• Antalet aktiva tidsserier som genereras av policyn är produkten av antalet unika värden för varje konfigurerad dimension per namnrymd. 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).

• API Management begränsar varje dimension till 100 unika värden och varje metriknamnrymd till 1 000 aktiva tidsserier. När någon av gränserna nås spåras inga nya dimensionsvärden eller tidsserier, och motsvarande metriska data kasseras tyst.

• 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

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.

För att förbättra prestandan bör man hoppa över:

• Sidhuvuden för begäran och svar
• Kroppsloggning

Troubleshooting

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

• Undersök om det finns en länkad Azure Monitor Private Link Scope (AMPLS)-resurs i det virtuella nätverket där API Management-resursen är ansluten. AMPLS-resurser har ett globalt omfång över prenumerationer och ansvarar för att hantera datafrågor och datainsamling för alla Azure Monitor-resurser. Det är möjligt att AMPLS har konfigurerats med ett Private-Only å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

• Introduktion till Application Insights – OpenTelemetry-observerbarhet
• Så här loggar du händelser till Azure Event Hubs i Azure API Management
• Övervaka API Management