Jak zintegrować usługę Azure API Management z usługą aplikacja systemu Azure 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 aplikacja systemu Azure Insights jest rozszerzalną usługą dla deweloperów internetowych, którzy kompilują aplikacje i zarządzają nimi na wielu platformach. W tym przewodniku dowiesz się, jak:

  • Zapoznaj się z integracją usługi Application Insights z usługą API Management.
  • Zapoznaj się ze strategiami zmniejszania wpływu na wydajność instancji usługi zarządzania API.

Note

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 Application Insights są podobne do wskazówek dotyczących instancji 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.

Warning

W przypadku korzystania z własnej bramy nie gwarantujemy, że wszystkie dane telemetryczne są wypychane do usługi aplikacja systemu Azure Insights, ponieważ opiera się na buforowaniu w pamięci usługi Application Insights.

Prerequisites

  • Utwórz wystąpienie usługi Azure API Management.

  • Utwórz wystąpienie usługi Application Insights. Aby utworzyć instancję korzystając z portalu Azure, zobacz zasoby Application Insights oparte na Workspace.

    Note

    Zasób usługi Application Insights może znajdować się w innej subskrypcji, a nawet w innej dzierżawie niż zasób 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:

    1. 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ą użytkownikowi, zanotuj identyfikator klienta Client ID.

    2. Przypisz tożsamość roli Publikatora Metryk Monitorowania, przyporządkowane do zasobu Application Insights. Aby przypisać rolę, użyj witryny Azure Portal lub innych narzędzi platformy Azure.

Omówienie scenariusza

Poniższe kroki stanowią ogólny przegląd tego scenariusza.

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

    Important

    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. Aby zwiększyć bezpieczeństwo, użyj parametrów połączenia usługi Application Insights przy użyciu tożsamości zarządzanej 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. Aby dowiedzieć się więcej, zobacz Parametry połączenia w usłudze Application Insights.

    Note

    Jeśli zasób Application Insights znajduje się w innej dzierżawie, utwórz rejestrator, korzystając z interfejsu API REST lub powiązanych narzędzi, jak pokazano w dalszej części tego artykułu.

  2. Włącz monitorowanie usługi Application Insights dla jednego lub wielu 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.

Utworzenie połączenia za pomocą portalu Azure

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.

Note

Jeśli to możliwe, firma Microsoft zaleca używanie ciągu połączenia z poświadczeniami tożsamości zarządzanej w celu zwiększenia poziomu 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.

  1. Wejdź do swojej instancji usługi Azure API Management w portalu Azure.

  2. W obszarze Monitorowanie w menu paska bocznego wybierz pozycję Application Insights.

  3. Wybierz + Dodaj.
    Zrzut ekranu pokazujący, gdzie dodać nowe połączenie

  4. Wybierz utworzone wcześniej wystąpienie usługi Application Insights i podaj krótki opis.

  5. 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 API Management odpowiada.
    • Wyniki są wyświetlane w okienku Dostępność wystąpienia usługi Application Insights.

  6. Wybierz Utwórz.

  7. Sprawdź, czy nowy rejestrator usługi Application Insights jest teraz wyświetlany na liście.

    Zrzut ekranu przedstawiający miejsce wyświetlania nowo utworzonego rejestratora usługi Application Insights.

Note

W tle tworzona jest jednostka rejestratora w wystąpieniu usługi API Management, która zawiera klucz instrumentacji wystąpienia usługi Application Insights.

Tip

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.

Utwórz połączenie, używając API REST, szablonu Bicep lub ARM

Wykonaj następujące kroki, aby użyć interfejsu API REST, Bicep lub szablonu ARM do utworzenia rejestratora Application Insights dla wystąpienia API Management. Możesz skonfigurować rejestrator, który używa parametrów połączenia z poświadczeniami tożsamości zarządzanej (zalecane), lub rejestrator, który używa tylko parametrów połączenia.

Zapoznaj się z wymaganiami wstępnymi dotyczącymi używania tożsamości zarządzanej usługi API Management.

Ciąg połączenia Application Insights zostanie wyświetlony w sekcji Przegląd zasobu usługi Application Insights.

Ciąg połączenia z zarządzaną tożsamością 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"
    }
  }
}

Łańcuch 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":"<client-ID>"
    }
  }
}

Rejestrator z poświadczeniami parametry połączenia tylko

Ciąg połączenia Application Insights zostanie wyświetlony 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łącz logowanie przy użyciu funkcji 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.

  1. Wejdź do swojej instancji usługi Azure API Management w portalu Azure.

  2. Wybierz API>API z menu paska bocznego.

  3. Wybierz interfejs API, taki jak Swagger Petstore. W przypadku skonfigurowania wybierz wersję.

    Tip

    Aby włączyć rejestrowanie dla wszystkich interfejsów API, wybierz pozycję Wszystkie interfejsy API.

  4. Wybierz kartę Ustawienia na górnym pasku.

  5. Przewiń w dół do sekcji Dzienniki diagnostyczne i zaznacz pole wyboru Włącz . Zrzut ekranu przedstawiający konfigurację dzienników diagnostycznych w portalu.

  6. Wybierz podłączony rejestrator z listy rozwijanej Miejsce docelowe.

  7. Wpisz 100 jako Sampling (%) i zaznacz pole Zawsze rejestruj błędy .

  8. Pozostaw pozostałe ustawienia w następujący sposób. Aby uzyskać szczegółowe informacje o ustawieniach, zobacz Informacje o ustawieniach dzienników diagnostycznych.

    Warning

    Nadpisanie domyślnej liczby bajtów ładunku do wartości logu0 może znacząco obniżyć wydajność twoich API.

  9. Wybierz Zapisz.

  10. Za kulisami tworzona jest na poziomie interfejsu API jednostka diagnostyczna o nazwie applicationinsights.

Note

Żą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

Możesz określić loggerów na różnych poziomach:

  • Rejestrator pojedynczego interfejsu API
  • Rejestrator dla wszystkich interfejsów API

Jeśli określisz oba:

  • 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ą techniczną firmy Microsoft. Multipleksowanie nie jest obsługiwane, jeśli używasz tego samego programu rejestrującego (miejsce docelowe Application Insights) zarówno na poziomie „Wszystkie interfejsy API”, jak 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 Description
Request Dla każdego żądania przychodzącego:
  • żądanie frontonu
  • odpowiedź frontonu
Dependency Automatyczna telemetria dotycząca zależności zewnętrznych podczas wykonywania obsługiwanych zasad, w tym żądań przekazywanych do usługi zaplecza.
Exception Dla każdego żądania, które zakończyło się niepowodzeniem:
  • Niepowodzenie z powodu zamkniętego połączenia klienta
  • Uruchomiono sekcję dotyczącą błędów zasad interfejsu API
  • Ma kod stanu HTTP odpowiedzi zgodny z 4xx lub 5xx
Trace Jeśli skonfigurujesz zasady śledzenia
Ustawienie severity w polityce trace musi być równe lub większe niż ustawienie verbosity w rejestrowaniu usługi Application Insights.

Telemetria zewnętrzna zależności dla wspieranych polityk

Po skonfigurowaniu i włączeniu logowania Application Insights, zarządzanie API automatycznie zbiera telemetrię zależności zewnętrznej dla następujących polityk. Nie jest wymagana dodatkowa konfiguracja polityk ani telemetrii:

  • 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 rejestruje te wywołania zewnętrzne jako powiązane operacje potomne. Na przykład możesz zobaczyć próby ponownego próbowania, pobieranie metadanych OpenID Connect przez validate-jwt, wysłanie Service Bus lub przekierowanie backendowe jako powiązane operacje. Aby zweryfikować dane telemetryczne w portalu Azure, otwórz Szczegóły transakcji end-to-end w zasobie Application Insights i przejrzyj powiązane operacje dla danego żądania.

Obecnie śledzenie zależności jest obsługiwane tylko dla polityk z poprzedniej listy.

Note

Aby uzyskać informacje o maksymalnym rozmiarze oraz liczbie metryk i zdarzeń na instancję Application Insights, zobacz Limity Application Insights.

Emituj metryki niestandardowe

Można emitować metryki niestandardowe do usługi Application Insights z instancji usługi API Management. Zarządzanie API generuje niestandardowe metryki za pomocą polityk takich jak emit-metric i llm-emit-token-metric. W poniższej sekcji użyto emit-metric polityki jako przykład.

Note

Niestandardowe metryki są funkcją podglądową Azure Monitor i podlegają ograniczeniom.

Aby generować niestandardowe metryki, wykonaj następujące kroki konfiguracyjne:

  1. Włącz metryki niestandardowe (wersja zapoznawcza) z wymiarami niestandardowymi w wystąpieniu usługi Application Insights.

    1. Przejdź do instancji usługi Application Insights w portalu.
    2. W obszarze Konfiguruj w menu paska bocznego wybierz pozycję Użycie i szacowane koszty.
    3. Wybierz pozycję Metryki niestandardowe (wersja zapoznawcza)>Z wymiarami.
    4. Kliknij przycisk OK.

  2. Dodaj właściwość "metrics": true do obiektu diagnostycznego applicationInsights, który konfigurujesz w usłudze API Management. Obecnie musisz dodać tę właściwość za pomocą interfejsu API REST usługi API Management Diagnostic - Create or Update. Przykład:

    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. Upewnij się, że logger Application Insights jest skonfigurowany w zakresie, w którym chcesz generować niestandardowe metryki (albo wszystkie API, albo jedno API). Aby uzyskać więcej informacji, zobacz Włączanie rejestrowania usługi Application Insights dla interfejsu API we wcześniejszej wersji tego artykułu.

  4. Konfiguruj politykę emit-metric w zakresie, w którym logowanie Application Insights jest skonfigurowane (albo wszystkie API, albo jedno API) i włączone dla niestandardowych metryk. Aby uzyskać szczegółowe informacje o zasadach, zobacz odniesienie emit-metric do zasad.

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). W usłudze API Management 5 z nich są używane dla wymiarów domyślnych, w tym następujących:

  • Region
  • Identyfikator usługi
  • Nazwa usługi
  • Rodzaj usługi

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 5 wymiarów niestandardowych na politykę.

  • Liczba aktywnych szeregów czasowych generowanych przez politykę jest iloczynem liczby unikalnych wartości każdego skonfigurowanego wymiaru w przestrzeni nazw. 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.

  • Zarządzanie API ogranicza każdy wymiar do 100 unikalnych wartości, a każda przestrzeń nazw metryki do 1000 aktywnych szeregów czasowych. Gdy którykolwiek z tych limitów zostanie osiągnięty, nowe wartości wymiarowe lub szeregi czasowe nie są śledzone, a odpowiadające im dane metryczne są cicho odrzucane.

  • 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 limit aktywnych szeregów czasowych.

Dowiedz się więcej o ograniczeniach i zagadnieniach dotyczących projektowania metryk niestandardowych w usłudze Azure Monitor.

Konsekwencje dla wydajności i próbkowanie dzienników

Warning

Rejestrowanie wszystkich zdarzeń może mieć poważne konsekwencje dla wydajności, 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 każdego poszczególnego żądania dla interfejsów API o dużym obciążeniu.

Możesz manipulować liczbą zarejestrowanych żądań, dostosowując ustawienie Próbkowania. 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 danych ciała

Troubleshooting

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 Azure Monitor Private Link (AMPLS) w sieci wirtualnej, w której jest połączony zasób usługi API Management. Zasoby AMPLS mają globalny zakres we wszystkich subskrypcjach i są odpowiedzialne za zarządzanie zapytaniami o dane i pozyskiwaniem danych dla wszystkich zasobów usługi Azure Monitor. Możliwe, że zestaw AMPLS został skonfigurowany z trybem dostępu Private-Only przeznaczonym specjalnie do 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.

Treści powiązane

  • Last updated on