Jak zintegrować usługę Azure API Management z usługą Azure Application Insights
DOTYCZY: Wszystkie warstwy usługi API Management
Możesz łatwo zintegrować usługę aplikacja systemu Azure Insights z usługą Azure API Management. Usługa Azure Application Insights jest rozszerzalną usługą dla deweloperów internetowych, którzy kompilują aplikacje i zarządzają nimi na wielu platformach. W tym przewodniku wykonasz następujące elementy:
- Zapoznaj się z integracją usługi Application Insights z usługą API Management.
- Poznaj strategie zmniejszania wpływu na wydajność wystąpienia usługi API Management.
Uwaga
W obszarze roboczym usługi API Management właściciel obszaru roboczego może niezależnie zintegrować usługę Application Insights i włączyć rejestrowanie usługi Application Insights dla interfejsów API obszaru roboczego. Ogólne wskazówki dotyczące integracji obszaru roboczego z usługą Application Insights są podobne do wskazówek dotyczących wystąpienia usługi API Management; jednak konfiguracja jest ograniczona tylko do obszaru roboczego. Obecnie należy zintegrować usługę Application Insights w obszarze roboczym, konfigurując parametry połączenia (zalecane) lub klucz instrumentacji.
Ostrzeżenie
W przypadku korzystania z własnej bramy nie gwarantujemy, że wszystkie dane telemetryczne zostaną wypchnięte do usługi aplikacja systemu Azure Insights, biorąc pod uwagę, że opiera się na buforowaniu w pamięci usługi Application Insights.
Wymagania wstępne
Potrzebujesz wystąpienia usługi Azure API Management. Najpierw utwórz jeden .
Aby użyć usługi Application Insights, utwórz wystąpienie usługi Application Insights. Aby utworzyć wystąpienie przy użyciu witryny Azure Portal, zobacz Zasoby usługi Application Insights oparte na obszarze roboczym.
Uwaga
Zasób usługi Application Insights może znajdować się w innej subskrypcji, a nawet w innej dzierżawie niż zasób usługi API Management.
Jeśli planujesz skonfigurować poświadczenia tożsamości zarządzanej do użycia z usługą Application Insights, wykonaj następujące kroki:
Włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika dla usługi API Management.
- Jeśli włączysz tożsamość zarządzaną przypisaną przez użytkownika, zanotuj identyfikator klienta tożsamości.
Przypisz tożsamość roli Wydawca metryk monitorowania w zakresie do zasobu usługi Application Insights. Aby przypisać rolę, użyj witryny Azure Portal lub innych narzędzi platformy Azure.
Omówienie scenariusza
Poniżej przedstawiono ogólne kroki dla tego scenariusza.
Najpierw utwórz połączenie między usługą Application Insights i usługą API Management
Połączenie między usługą Application Insights i usługą API Management można utworzyć przy użyciu witryny Azure Portal, interfejsu API REST lub powiązanych narzędzi platformy Azure. Usługa API Management konfiguruje zasób rejestratora dla połączenia.
Ważne
Obecnie w portalu usługa API Management obsługuje tylko połączenia z usługą Application Insights przy użyciu klucza instrumentacji usługi Application Insights. W przypadku zwiększonych zabezpieczeń zalecamy używanie parametry połączenia usługi Application Insights z tożsamością zarządzaną usługi API Management. Aby skonfigurować parametry połączenia przy użyciu poświadczeń tożsamości zarządzanej, użyj interfejsu API REST lub powiązanych narzędzi, jak pokazano w dalszej części tego artykułu. Dowiedz się więcej o parametry połączenia usługi Application Insights.
Uwaga
Jeśli zasób usługi Application Insights znajduje się w innej dzierżawie, musisz utworzyć rejestrator przy użyciu interfejsu API REST lub powiązanych narzędzi, jak pokazano w dalszej części tego artykułu.
Po drugie włącz rejestrowanie usługi Application Insights dla interfejsów API lub interfejsów API.
W tym artykule włączysz rejestrowanie usługi Application Insights dla interfejsu API przy użyciu witryny Azure Portal. Usługa API Management konfiguruje zasób diagnostyczny dla interfejsu API.
Tworzenie połączenia przy użyciu witryny Azure Portal
Wykonaj następujące kroki, aby utworzyć połączenie między usługą Application Insights i usługą API Management za pomocą witryny Azure Portal.
Uwaga
Jeśli to możliwe, firma Microsoft zaleca używanie parametry połączenia z poświadczeniami tożsamości zarządzanej w celu zapewnienia zwiększonych zabezpieczeń. Aby skonfigurować te poświadczenia, użyj interfejsu API REST lub powiązanych narzędzi, jak pokazano w dalszej części tego artykułu.
Przejdź do wystąpienia usługi Azure API Management w witrynie Azure Portal.
Wybierz pozycję Application Insights z menu po lewej stronie.
Wybierz + Dodaj.
Wybierz utworzone wcześniej wystąpienie usługi Application Insights i podaj krótki opis.
Aby włączyć monitorowanie dostępności wystąpienia usługi API Management w usłudze Application Insights, zaznacz pole wyboru Dodaj monitor dostępności.
- To ustawienie regularnie sprawdza, czy punkt końcowy bramy usługi API Management odpowiada.
- Wyniki są wyświetlane w okienku Dostępność wystąpienia usługi Application Insights.
Wybierz pozycję Utwórz.
Sprawdź, czy nowy rejestrator usługi Application Insights jest teraz wyświetlany na liście.
Uwaga
W tle jednostka rejestratora jest tworzona w wystąpieniu usługi API Management zawierającym klucz instrumentacji wystąpienia usługi Application Insights.
Napiwek
Jeśli musisz zaktualizować klucz instrumentacji skonfigurowany w rejestratorze usługi Application Insights, wybierz wiersz rejestratora na liście (a nie nazwę rejestratora). Wprowadź klucz instrumentacji, a następnie wybierz pozycję Zapisz.
Tworzenie połączenia przy użyciu interfejsu API REST, Bicep lub szablonu usługi ARM
Wykonaj następujące kroki, aby użyć interfejsu API REST, Bicep lub szablonu usługi ARM, aby utworzyć rejestrator usługi Application Insights dla wystąpienia usługi API Management. Można skonfigurować rejestrator, który używa parametry połączenia z poświadczeniami tożsamości zarządzanej (zalecane) lub rejestratorem, który używa tylko parametry połączenia.
Rejestrator z parametry połączenia przy użyciu poświadczeń tożsamości zarządzanej (zalecane)
Zapoznaj się z wymaganiami wstępnymi dotyczącymi używania tożsamości zarządzanej usługi API Management.
Parametry połączenia usługi Application Insights zostanie wyświetlona w sekcji Przegląd zasobu usługi Application Insights.
Parametry połączenia z tożsamością zarządzaną przypisaną przez system
Użyj rejestratora usługi API Management — utwórz lub zaktualizuj interfejs API REST z następującą treścią żądania.
{
"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"
}
}
}
Parametry połączenia z tożsamością zarządzaną przypisaną przez użytkownika
Użyj rejestratora usługi API Management — utwórz lub zaktualizuj interfejs API REST z następującą treścią żądania.
{
"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>"
}
}
}
Rejestrator z poświadczeniami parametry połączenia tylko
Parametry połączenia usługi Application Insights zostanie wyświetlona w sekcji Przegląd zasobu usługi Application Insights.
Użyj rejestratora usługi API Management — utwórz lub zaktualizuj interfejs API REST z następującą treścią żądania.
Jeśli konfigurujesz rejestrator dla obszaru roboczego, użyj rejestratora obszaru roboczego — tworzenie lub aktualizowanie interfejsu API REST.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
Włączanie rejestrowania usługi Application Insights dla interfejsu API
Wykonaj poniższe kroki, aby włączyć rejestrowanie usługi Application Insights dla interfejsu API. Można również włączyć rejestrowanie usługi Application Insights dla wszystkich interfejsów API.
Przejdź do wystąpienia usługi Azure API Management w witrynie Azure Portal.
Wybierz pozycję Interfejsy API z menu po lewej stronie.
Kliknij interfejs API, w tym przypadku pokazowy interfejs API konferencji. W przypadku skonfigurowania wybierz wersję.
Napiwek
Aby włączyć rejestrowanie dla wszystkich interfejsów API, wybierz pozycję Wszystkie interfejsy API.
Przejdź do karty Ustawienia na górnym pasku.
Przewiń w dół do sekcji Dzienniki diagnostyczne.
Zaznacz pole wyboru Włącz.
Wybierz dołączony rejestrator na liście rozwijanej Miejsce docelowe .
Wprowadź 100 jako próbkowanie (%) i zaznacz pole wyboru Zawsze rejestruje błędy.
Pozostaw pozostałe ustawienia w następujący sposób. Aby uzyskać szczegółowe informacje o ustawieniach, zobacz Informacje o ustawieniach dzienników diagnostycznych.
Ostrzeżenie
Zastąpienie domyślnej liczby bajtów ładunku w celu zarejestrowania wartości 0 może znacznie zmniejszyć wydajność interfejsów API.
Wybierz pozycję Zapisz.
W tle jednostka diagnostyczna o nazwie
applicationinsightsjest tworzona na poziomie interfejsu API.
Uwaga
Żądania są pomyślne, gdy usługa API Management wysyła całą odpowiedź do klienta.
Rejestratory dla pojedynczego interfejsu API lub wszystkich interfejsów API
Rejestratory można określić na różnych poziomach:
- Rejestrator pojedynczego interfejsu API
- Rejestrator dla wszystkich interfejsów API
Określanie obu:
- Domyślnie pojedynczy rejestrator interfejsu API (bardziej szczegółowy) zastępuje ten dla wszystkich interfejsów API.
- Jeśli rejestratory skonfigurowane na dwóch poziomach są różne i potrzebujesz obu rejestratorów do odbierania danych telemetrycznych (multipleksowania), skontaktuj się z pomoc techniczna firmy Microsoft. Należy pamiętać, że multipleksowanie nie jest obsługiwane, jeśli używasz tego samego rejestratora (miejsca docelowego usługi Application Insights) na poziomie "Wszystkie interfejsy API" i na poziomie pojedynczego interfejsu API. Aby multipleksowanie działało poprawnie, należy skonfigurować różne rejestratory na poziomie "Wszystkie interfejsy API" i indywidualny poziom interfejsu API oraz poprosić o pomoc od pomocy technicznej firmy Microsoft, aby umożliwić multipleksowanie dla twojej usługi.
Jakie dane są dodawane do usługi Application Insights
Usługa Application Insights odbiera:
| Element telemetrii | opis |
|---|---|
| Zażądaj | Dla każdego żądania przychodzącego:
|
| Zależność | Dla każdego żądania przekazanego do usługi zaplecza:
|
| Wyjątek | Dla każdego żądania, które zakończyło się niepowodzeniem:
|
| Śledzenie | Jeśli skonfigurujesz zasady śledzenia . Ustawienie severity w trace zasadach musi być równe lub większe niż verbosity ustawienie w rejestrowaniu usługi Application Insights. |
Uwaga
Zobacz Limity usługi Application Insights, aby uzyskać informacje o maksymalnym rozmiarze i liczbie metryk i zdarzeń na wystąpienie usługi Application Insights.
Emituj metryki niestandardowe
Metryki niestandardowe można emitować do usługi Application Insights z wystąpienia usługi API Management. Usługa API Management emituje metryki niestandardowe przy użyciu zasad, takich jak metryka emitowania i metryka azure-openai-emit-token-metric. W poniższej sekcji użyto emit-metric zasad jako przykładu.
Uwaga
Metryki niestandardowe są funkcją usługi Azure Monitor w wersji zapoznawczej i podlegają ograniczeniom.
Aby emitować metryki niestandardowe, wykonaj następujące kroki konfiguracji.
Włącz metryki niestandardowe (wersja zapoznawcza) z wymiarami niestandardowymi w wystąpieniu usługi Application Insights.
- Przejdź do wystąpienia usługi Application Insights w portalu.
- W menu po lewej stronie wybierz pozycję Użycie i szacowane koszty.
- Wybierz pozycję Metryki niestandardowe (wersja zapoznawcza)>Z wymiarami.
- Wybierz przycisk OK.
"metrics": trueDodaj właściwość do jednostki diagnostycznej skonfigurowanejapplicationInsightsw usłudze API Management. Obecnie należy dodać tę właściwość przy użyciu diagnostyki usługi API Management — tworzenie lub aktualizowanie interfejsu API REST. Na przykład: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 [...] } }Upewnij się, że rejestrator usługi Application Insights jest skonfigurowany w zakresie, w którym zamierzasz emitować metryki niestandardowe (wszystkie interfejsy API lub pojedynczy interfejs API). Aby uzyskać więcej informacji, zobacz Włączanie rejestrowania usługi Application Insights dla interfejsu API we wcześniejszej wersji tego artykułu.
emit-metricSkonfiguruj zasady w zakresie, w którym jest skonfigurowane rejestrowanie usługi Application Insights (wszystkie interfejsy API lub pojedynczy interfejs API) i jest włączone dla metryk niestandardowych. Aby uzyskać szczegółowe informacje o zasadach, zobacz dokumentacjęemit-metriczasad.
Limity metryk niestandardowych
Usługa Azure Monitor nakłada limity użycia dla metryk niestandardowych, które mogą mieć wpływ na możliwość emitowania metryk z usługi API Management. Na przykład usługa Azure Monitor obecnie ustawia limit 10 kluczy wymiarów na metrykę i limit 50 000 łącznych aktywnych szeregów czasowych na region w ramach subskrypcji (w okresie 12 godzin).
Te limity mają następujące konsekwencje dotyczące konfigurowania metryk niestandardowych w zasadach usługi API Management, takich jak emit-metric lub azure-openai-emit-token-metric:
Można skonfigurować maksymalnie 10 wymiarów niestandardowych na zasady.
Liczba aktywnych szeregów czasowych wygenerowanych przez zasady w okresie 12 godzin jest produktem liczby unikatowych wartości każdego skonfigurowanego wymiaru w danym okresie. Jeśli na przykład w zasadach skonfigurowano trzy wymiary niestandardowe, a każdy wymiar miał 10 możliwych wartości w danym okresie, zasady współtworzyłyby 1000 (10 x 10 x 10) aktywnych szeregów czasowych.
Jeśli skonfigurujesz zasady w wielu wystąpieniach usługi API Management, które znajdują się w tym samym regionie w ramach subskrypcji, wszystkie wystąpienia mogą współtworzyć regionalny aktywny limit szeregów czasowych.
Dowiedz się więcej o ograniczeniach i zagadnieniach dotyczących projektowania metryk niestandardowych w usłudze Azure Monitor.
Wpływ na wydajność i próbkowanie dzienników
Ostrzeżenie
Rejestrowanie wszystkich zdarzeń może mieć poważny wpływ na wydajność w zależności od szybkości żądań przychodzących.
Na podstawie wewnętrznych testów obciążeniowych włączenie funkcji rejestrowania spowodowało zmniejszenie przepływności o 40%-50%, gdy liczba żądań przekroczyła 1000 żądań na sekundę. Usługa Application Insights została zaprojektowana w celu oceny wydajności aplikacji przy użyciu analizy statystycznej. To nie jest:
- Przeznaczony do systemu inspekcji.
- Nadaje się do rejestrowania poszczególnych żądań dla interfejsów API o dużej ilości.
Możesz manipulować liczbą zarejestrowanych żądań, dostosowując ustawienie Próbkowanie. Wartość 100% oznacza, że wszystkie żądania są rejestrowane, a 0% odzwierciedla brak rejestrowania.
Próbkowanie pomaga zmniejszyć ilość danych telemetrycznych, skutecznie zapobiegając znacznemu obniżeniu wydajności przy jednoczesnym zachowaniu korzyści z rejestrowania.
Aby poprawić problemy z wydajnością, pomiń:
- Nagłówki żądań i odpowiedzi.
- Rejestrowanie treści.
Wideo
Rozwiązywanie problemów
Rozwiązanie problemu przepływu danych telemetrycznych z usługi API Management do usługi Application Insights:
- Sprawdź, czy istnieje połączony zasób zakresu usługi Private Link (AMPLS) usługi Azure Monitor w sieci wirtualnej, w której jest połączony zasób usługi API Management. Zasoby AMPLS mają globalny zakres w subskrypcjach i są odpowiedzialne za zarządzanie zapytaniami o dane i pozyskiwanie wszystkich zasobów usługi Azure Monitor. Możliwe, że zestaw AMPLS został skonfigurowany z trybem dostępu tylko do użytku prywatnego specjalnie na potrzeby pozyskiwania danych. W takich przypadkach uwzględnij zasób usługi Application Insights i skojarzony z nim zasób usługi Log Analytics w usłudze AMPLS. Po dodaniu tego dodatku dane usługi API Management zostaną pomyślnie pozyskane do zasobu usługi Application Insights, co rozwiązuje problem z przesyłaniem danych telemetrycznych.
Powiązana zawartość
- Dowiedz się więcej o aplikacja systemu Azure Insights.
- Rozważ rejestrowanie za pomocą usługi Azure Event Hubs.
- Dowiedz się więcej na temat wizualizowania danych z usługi Application Insights przy użyciu narzędzia Azure Managed Grafana