Freigeben über

Vorgehensweise beim Integrieren von Azure API Management in Azure Application Insights

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Sie können Azure Application Insights ganz einfach in Azure API Management integrieren. Azure Application Insights ist ein erweiterbarer Dienst für Webentwickler, die Apps auf mehreren Plattformen erstellen und verwalten. In diesem Leitfaden werden Sie:

  • Gehen Sie die Integration von Application Insights in API Management durch.
  • Strategien zur Verringerung der Auswirkungen auf die Leistung Ihrer API Management-Dienstinstanz lernen.

Hinweis

In einem API Management-Arbeitsbereich kann ein Arbeitsbereichsbesitzer Application Insights unabhängig integrieren und die Application Insights-Protokollierung für die APIs des Arbeitsbereichs aktivieren. Der allgemeine Leitfaden zum Integrieren eines Arbeitsbereichs in Application Insights ähnelt dem Leitfaden für eine API Management-Instanz. Die Konfiguration ist jedoch nur auf den Arbeitsbereich festgelegt. Derzeit müssen Sie Application Insights in einen Arbeitsbereich integrieren, indem Sie eine Verbindungszeichenfolge (empfohlen) oder einen Instrumentierungsschlüssel konfigurieren.

Warnung

Bei Verwendung des selbstgehosteten Gateways garantieren wir nicht, dass alle Telemetriedaten an Azure Application Insights übertragen werden, da es auf die In-Memory-Pufferung von Application Insights angewiesen ist.

Voraussetzungen

  • Sie benötigen eine Azure API Management-Dienstinstanz. Als Erstes müssen Sie eine Instanz erstellen.

  • Um Application Insights zu verwenden, müssen Sie zunächst eine Instanz des Application Insights-Diensts erstellen. Um eine Instanz mithilfe des Azure-Portals zu erstellen, lesen Sie Arbeitsbereichsbasierte Application Insights-Ressourcen.

    Hinweis

    Die Application Insights-Ressource kann sich in einem anderen Abonnement oder sogar einem anderen Mandanten als die API Management-Ressource befinden.

  • Wenn Sie planen, Anmeldeinformationen für eine verwaltete Identität für die Verwendung mit Application Insights zu konfigurieren, führen Sie die folgenden Schritte aus:

    1. Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität für API Management.

      • Wenn Sie eine benutzerseitig zugewiesene verwaltete Identität aktivieren, notieren Sie sich die Client-ID der Identität.

    2. Weisen Sie der Identität die Rolle Herausgeber von Überwachungsmetriken zu, die auf die Application Insights-Ressource festgelegt ist. Verwenden Sie zum Zuweisen der Rolle das Azure-Portal oder andere Azure-Tools.

Übersicht über das Szenario

Im Folgenden werden allgemeine Schritte für dieses Szenario aufgeführt.

  1. Stellen Sie zunächst eine Verbindung zwischen Application Insights und API Management her.

    Sie können eine Verbindung zwischen Application Insights und Ihrem API Management mithilfe des Azure-Portal, der REST-API oder verwandter Azure-Tools herstellen. API Management konfiguriert eine Protokollierungsressource für die Verbindung.

    Wichtig

    Derzeit unterstützt API Management im Portal nur Verbindungen mit Application Insights mithilfe eines Application Insights-Instrumentierungsschlüssels. Zur Verbesserung der Sicherheit empfehlen wir die Verwendung einer Application Insights-Verbindungszeichenfolge mit einer verwalteten API Management-Identität. Verwenden Sie zum Konfigurieren der Verbindungszeichenfolge mit Anmeldeinformationen für eine verwaltete Identität die REST-API oder verwandte Tools, wie in einem späteren Abschnitt dieses Artikels gezeigt. Weitere Informationen zu den Verbindungszeichenfolgen von Application Insights finden Sie hier.

    Hinweis

    Wenn sich Ihre Application Insights-Ressource in einem anderen Mandanten befindet, müssen Sie die Protokollierung mithilfe der REST-API oder verwandter Tools erstellen, wie in einem späteren Abschnitt dieses Artikels gezeigt.

  2. Aktivieren Sie als Nächstes die Application Insights-Protokollierung für Ihre APIs.

    In diesem Artikel aktivieren Sie die Application Insights-Protokollierung für Ihre API mithilfe des Azure-Portals. API Management konfiguriert eine Diagnoseressource für die API.

Herstellen einer Verbindung mit dem Azure-Portal

Gehen Sie folgendermaßen vor, um über das Azure-Portal eine Verbindung zwischen Application Insights und API Management herzustellen.

Hinweis

Microsoft empfiehlt nach Möglichkeit die Verwendung der Verbindungszeichenfolge mit Anmeldeinformationen für eine verwaltete Identität, um die Sicherheit zu erhöhen. Verwenden Sie zum Konfigurieren dieser Anmeldeinformationen die REST-API oder verwandte Tools, wie in einem späteren Abschnitt dieses Artikels gezeigt.

  1. Navigieren Sie im Azure-Portal zu Ihrer Azure API Management-Dienstinstanz.

  2. Wählen Sie Application Insights im Menü auf der linken Seite aus.

  3. Wählen Sie + Hinzufügen.
    Screenshot, der zeigt, wo eine neue Verbindung hinzugefügt wird

  4. Wählen Sie die zuvor erstellte Application Insights-Instanz aus, und geben Sie eine kurze Beschreibung.

  5. Aktivieren Sie das Kontrollkästchen Verfügbarkeitsmonitor hinzufügen, um die Verfügbarkeitsüberwachung Ihrer API Management-Instanz in Application Insights zu aktivieren.

    • Mit dieser Einstellung wird regelmäßig überprüft, ob der API Management-Gateway-Endpunkt antwortet.
    • Die Ergebnisse werden im Bereich Verfügbarkeit der Application Insights-Instanz angezeigt.

  6. Klicken Sie auf Erstellen.

  7. Überprüfen Sie, ob die neue Application Insights-Protokollierung nun in der Liste angezeigt wird.

    Screenshot: Angabe, wo die neu erstellte Application Insights-Protokollierung angezeigt wird.

Hinweis

Im Hintergrund wird eine Protokollierungsentität in der API Management-Instanz erstellt, die den Instrumentierungsschlüssel der Application Insights-Instanz enthält.

Tipp

Wählen Sie die Zeile der Protokollierung in der Liste aus (nicht den Namen der Protokollierung), wenn Sie den Instrumentierungsschlüssel aktualisieren müssen, der in der Application Insights-Protokollierung konfiguriert ist. Geben Sie den Instrumentierungsschlüssel ein, und wählen Sie Speichern aus.

Herstellen einer Verbindung über die REST-API-, Bicep- oder ARM-Vorlage

Gehen Sie folgendermaßen vor, um über die REST-API, Bicep oder eine ARM-Vorlage eine Application Insights-Protokollierung für Ihre API Management-Instanz zu erstellen. Sie können eine Protokollierung konfigurieren, die eine Verbindungszeichenfolge mit Anmeldeinformationen für eine verwaltete Identität verwendet (empfohlen), oder eine Protokollierung, die nur eine Verbindungszeichenfolge verwendet.

Weitere Informationen zu den Voraussetzungen für die Verwendung einer von API Management verwalteten Identität finden Sie hier.

Die Verbindungszeichenfolge von Application Insights wird im Abschnitt Übersicht Ihrer Application Insights-Ressource angezeigt.

Verbindungszeichenfolge mit systemseitig zugewiesener verwalteter Identität

Verwenden Sie die REST-API Logger – Erstellen oder Aktualisieren von API Management mit dem folgenden Anforderungstext.

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

Verbindungszeichenfolge mit benutzerseitig zugewiesener verwalteter Identität

Verwenden Sie die REST-API Logger – Erstellen oder Aktualisieren von API Management mit dem folgenden Anforderungstext.

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

Protokollierung nur mit Verbindungszeichenfolgen-Anmeldeinformationen

Die Verbindungszeichenfolge von Application Insights wird im Abschnitt Übersicht Ihrer Application Insights-Ressource angezeigt.

Verwenden Sie die REST-API Logger – Erstellen oder Aktualisieren von API Management mit dem folgenden Anforderungstext.

Wenn Sie den Logger für einen Arbeitsbereich konfigurieren, verwenden Sie die REST-API Arbeitsbereichs-Logger – Erstellen oder Aktualisieren.

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

Aktivieren der Application Insights-Protokollierung für Ihre API

Führen Sie die folgenden Schritte aus, um die Application Insights-Protokollierung für eine API zu aktivieren. Sie können auch die Application Insights-Protokollierung für alle APIs aktivieren.

  1. Navigieren Sie im Azure-Portal zu Ihrer Azure API Management-Dienstinstanz.

  2. Wählen Sie im Menü links APIs>APIs aus.

  3. Wählen Sie eine API aus, z. B. Swagger Petstore. Wenn diese Option konfiguriert ist, wählen Sie eine Version aus.

    Tipp

    Um die Protokollierung für alle APIs zu aktivieren, wählen Sie Alle APIs aus.

  4. Wechseln Sie zur Registerkarte Einstellungen in der oberen Leiste.

  5. Scrollen Sie nach unten zum Abschnitt Diagnoseprotokolle.
    Screenshot der Konfiguration von Diagnoseprotokollen im Portal

  6. Aktivieren Sie das Kontrollkästchen Aktivieren.

  7. Wählen Sie eine angefügte Protokollierung in der Dropdownliste Ziel aus.

  8. Geben Sie 100 als Sampling (%) ein, und aktivieren Sie das Kontrollkästchen Fehler immer protokollieren.

  9. Lassen Sie die übrigen Einstellungen unverändert. Ausführliche Informationen zu den Einstellungen finden Sie unter Referenz zu Einstellungen für die Diagnoseprotokollierung.

    Warnung

    Das Überschreiben des Standardwerts (Anzahl der zu protokollierenden Nutzlastbytes) 0 kann die Leistung Ihrer APIs erheblich beeinträchtigen.

  10. Wählen Sie Speichern aus.

  11. Im Hintergrund wird eine Diagnoseentität namens applicationinsights auf API-Ebene erstellt.

Hinweis

Die Anforderungen sind erfolgreich, sobald API Management die gesamte Antwort an den Client sendet.

Protokollierungen für eine einzelne API oder alle APIs

Sie können Protokollierungen auf verschiedenen Ebenen angeben:

  • Protokollierung für einzelne API
  • Eine Protokollierung für alle APIs

Beide angeben:

  • Standardmäßig setzt die Protokollierung für einzelne API (höhere Granularität) die für alle APIs außer Kraft.
  • Wenn die auf den beiden Ebenen konfigurierten Protokollierungen unterschiedlich sind und Sie beide Protokollierungen benötigen, um Telemetriedaten (Multiplexing) zu empfangen, wenden Sie sich an den Microsoft-Support. Beachten Sie, dass Multiplexing nicht unterstützt wird, wenn Sie dieselbe Protokollierung (Application Insights-Ziel) auf der Ebene „Alle APIs“ und auf einzelner API-Ebene verwenden. Damit Multiplexing ordnungsgemäß funktioniert, müssen Sie verschiedene Protokollierungen auf „Alle APIs“ und auf individueller API-Ebene konfigurieren und Unterstützung vom Microsoft-Support anfordern, um Multiplexing für Ihren Dienst zu aktivieren.

Welche Daten Application Insights hinzugefügt werden

Application Insights empfängt:

Telemetrieelement BESCHREIBUNG
Anforderung Für jede eingehende Anforderung:
  • Front-End-Anforderung
  • Front-End-Antwort
Abhängigkeit Für jede Anforderung, die an einen Back-End-Dienst weitergeleitet wird:
  • Back-End-Anforderung
  • Back-End-Antwort
Exception Für jede fehlgeschlagene Anforderung:
  • Sie ist aufgrund einer geschlossenen Clientverbindung fehlerhaft
  • Sie wurde im bei Fehler-Abschnitt der API-Richtlinien ausgelöst
  • Sie verfügt über einen mit 4xx oder 5xx übereinstimmenden Antwort-HTTP-Statuscode
Ablaufverfolgung Wenn Sie eine Richtlinie zur Ablaufverfolgung konfigurieren.
In der Application Insights-Protokollierung muss die severity-Einstellung in der trace-Richtlinie größer als die verbosity-Einstellung oder gleich sein.

Hinweis

Unter Application Insights finden Sie Informationen zur maximalen Größe und Anzahl von Metriken und Ereignissen pro Application Insights-Instanz.

Ausgabe benutzerdefinierter Metriken

Sie können benutzerdefinierte Metriken aus Ihrer API Management-Instanz an Application Insights ausgeben. API Management gibt benutzerdefinierte Metriken mithilfe von Richtlinien wie emit-metric und azure-openai-emit-token-metric aus. Im folgenden Abschnitt wird die Richtlinie emit-metric als Beispiel verwendet.

Hinweis

Benutzerdefinierte Metriken sind ein Vorschaufeature von Azure Monitor und unterliegen Einschränkungen.

Führen Sie zum Ausgeben benutzerdefinierter Metriken die folgenden Konfigurationsschritte aus.

  1. Aktivieren Sie benutzerdefinierte Metriken (Vorschau) mit benutzerdefinierten Dimensionen in Ihrer Application Insights-Instanz.

    1. Navigieren Sie im Portal zu Ihrer Application Insights-Instanz.
    2. Wählen Sie im linken Menü Nutzung und geschätzte Kosten aus.
    3. Wählen Sie Benutzerdefinierte Metriken (Vorschau)>Mit Dimensionen aus.
    4. Klicken Sie auf OK.

  2. Fügen Sie die "metrics": true-Eigenschaft der Diagnoseentität „applicationInsights“ hinzu, die in API Management konfiguriert ist. Derzeit müssen Sie diese Eigenschaft mithilfe der REST-API Diagnostic – Create or Update (Diagnose: Erstellen oder Aktualisieren) von API Management hinzufügen. Beispiel:

    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. Stellen Sie sicher, dass die Application Insights-Protokollierung in dem Bereich konfiguriert ist, in dem Sie benutzerdefinierte Metriken ausgeben möchten (entweder alle APIs oder eine einzelne API). Weitere Informationen finden Sie weiter oben in diesem Artikel unter Aktivieren der Application Insights-Protokollierung für Ihre API.

  4. Konfigurieren Sie die Richtlinie „emit-metric“ in einem Bereich, in dem die Application Insights-Protokollierung konfiguriert (entweder alle APIs oder eine einzelne API) und für benutzerdefinierte Metriken aktiviert ist. Details zur Richtlinie finden Sie im Richtlinienverweis „emit-metric“.

Grenzwerte für benutzerdefinierte Metriken

Azure Monitor legt Nutzungsgrenzwerte für benutzerdefinierte Metriken fest, die sich auf ihre Fähigkeit auswirken können, Metriken aus API Management auszugeben. Beispielsweise legt Azure Monitor derzeit einen Grenzwert von 10 Dimensionsschlüsseln pro Metrik und einen Grenzwert von insgesamt 50.000 aktiven Zeitreihen pro Region in einem Abonnement fest (innerhalb eines Zeitraums von 12 Stunden).

Diese Grenzwerte haben die folgenden Auswirkungen auf die Konfiguration benutzerdefinierter Metriken in API Management wie emit-metric und azure-openai-emit-token-metric:

  • Sie können maximal 10 benutzerdefinierte Dimensionen pro -Richtlinie konfigurieren.

  • Die Anzahl der aktiven Zeitreihen, die von der -Richtlinie innerhalb eines Zeitraums von 12 Stunden generiert werden, ist das Produkt der Anzahl eindeutiger Werte jeder konfigurierten Dimension während des Zeitraums. Wenn beispielsweise drei benutzerdefinierte Dimensionen in der Richtlinie konfiguriert wurden und jede Dimension innerhalb des Zeitraums 10 mögliche Werte aufweist, würde die  Richtlinie 1.000 (10 x 10 x 10) aktive Zeitreihen beitragen.

  • Wenn Sie die -Richtlinie in mehreren API Management-Instanzen konfigurieren, die sich in derselben Region in einem Abonnement befinden, können alle Instanzen zum regionalen aktiven Zeitreihengrenzwert beitragen.

Erfahren Sie mehr über Entwurfsbeschränkungen und -überlegungen für benutzerdefinierte Metriken in Azure Monitor.

Auswirkungen auf die Leistung und Protokollsampling

Warnung

Die Protokollierung aller Ereignisse kann abhängig von der Rate der eingehenden Anforderungen schwerwiegende Auswirkungen auf die Leistung haben.

Bei internen Auslastungstests reduzierte die Aktivierung des Protokollierungsfeatures den Durchsatz um 40-50%, wenn die Anforderungsrate 1.000 Anforderungen pro Sekunde überschritt. Bei Application Insights wird die statistische Analyse zur Bewertung der Anwendungsleistung verwendet. Es ist nicht:

  • auf den Einsatz als Überwachungssystem ausgelegt.
  • für die Protokollierung jeder einzelnen Anforderung für APIs mit hohem Volumen geeignet.

Sie können die Anzahl der protokollierten Anforderungen durch Anpassen der Einstellung Sampling beeinflussen. Ein Wert von 100 % bedeutet, dass alle Anforderungen protokolliert werden, während 0 % keine Protokollierung widerspiegelt.

Mit Sampling können Sie das Volumen von Telemetriedaten reduzieren, einen erheblichen Leistungsabfall effektiv verhindern und dabei dennoch die Vorteile der Protokollierung nutzen.

Um Leistungsprobleme zu umgehen, überspringen Sie:

  • Anforderungs- und Antwortheader
  • Textprotokollierung

Video

Problembehandlung

Behandeln von Problemen mit dem Telemetriedatenfluss von API Management zu Application Insights:

  • Untersuchen Sie, ob eine verknüpfte Azure Monitor Private Link Scope (AMPLS)-Ressource innerhalb des VNet existiert, mit dem die API-Verwaltungsressource verbunden ist. AMPLS-Ressourcen haben einen globalen Geltungsbereich für alle Abonnements und sind für die Verwaltung der Datenabfrage und -aufnahme für alle Azure Monitor-Ressourcen zuständig. Es ist möglich, dass der AMPLS mit einem Zugangsmodus „Nur privat“ speziell für die Dateneingabe konfiguriert wurde. Schließen Sie in solchen Fällen die Application Insights-Ressource und die zugehörige Log Analytics-Ressource in die AMPLS ein. Sobald diese Ergänzung vorgenommen wurde, werden die API Management Daten erfolgreich in der Application Insights-Ressource erfasst, um das Problem der Telemetriedatenübertragung zu beheben.

Zugehöriger Inhalt