Azure Application Insights와 Azure API Management를 통합하는 방법
적용 대상: 모든 API Management 계층
Azure Application Insights는 Azure API Management와 쉽게 통합할 수 있습니다. Azure Application Insights는 여러 플랫폼에서 앱을 빌드하고 관리하는 웹 개발자를 위한 확장 가능한 서비스입니다. 이 가이드에서는 다음을 수행합니다.
- Application Insights를 API Management에 통합하는 방법을 살펴봅니다.
- API Management 서비스 인스턴스에 대한 성능 영향을 줄이기 위한 전략을 알아봅니다.
참고 항목
API Management 작업 영역에서 작업 영역 소유자는 Application Insights를 독립적으로 통합하고 작업 영역의 API에 대해 Application Insights 로깅을 사용하도록 설정할 수 있습니다. Application Insights와 작업 영역을 통합하는 일반적인 지침은 API Management 인스턴스에 대한 지침과 비슷합니다. 그러나 구성의 범위는 작업 영역으로만 지정됩니다. 현재, 연결 문자열(권장) 또는 계측 키를 구성하여 Application Insights를 작업 영역에 통합해야 합니다.
Warning
Application Insights의 메모리 내 버퍼링을 활용한다고 가정할 경우 자체 호스팅 게이트웨이를 사용할 때 모든 원격 분석이 Azure Application Insights에 푸시될 것이라고 보장되지는 않습니다.
필수 조건
Azure API Management 인스턴스가 필요합니다. 먼저 하나를 만듭니다.
Application Insights를 사용하려면 Application Insights 서비스의 인스턴스를 만듭니다. Azure Portal을 사용하여 인스턴스를 만들려면 작업 영역 기반 Application Insights 리소스를 참조하세요.
참고 항목
Application Insights 리소스는 API Management 리소스와 다른 구독 또는 다른 테넌트에 있을 수 있습니다.
Application Insights와 함께 사용하도록 관리 ID 자격 증명을 구성하려면 다음 단계를 완료해야 합니다.
API Management에 대해 시스템 할당 또는 사용자 할당 관리 ID를 사용하도록 설정합니다.
- 사용자가 할당한 관리 ID를 사용하도록 설정하는 경우 ID의 클라이언트 ID를 적어 둡니다.
Application Insights 리소스로 범위가 할당된 모니터링 메트릭 게시자 역할에 ID를 할당합니다. 역할을 할당하려면 Azure Portal 또는 다른 Azure 도구를 사용합니다.
시나리오 개요
다음은 이 시나리오에 대한 대략적인 단계입니다.
먼저 Application Insights와 API Management 간의 연결을 만듭니다.
Azure Portal, REST API 또는 관련 Azure 도구를 사용하여 Application Insights와 API Management 간의 연결을 만들 수 있습니다. API Management는 연결을 위한 로거 리소스를 구성합니다.
Important
현재 포털에서 API Management는 Application Insights 계측 키를 사용하여 Application Insights에 대한 연결만 지원합니다. 보안 강화를 위해 API Management 관리 ID와 함께 Application Insights 연결 문자열을 사용하는 것이 좋습니다. 관리 ID 자격 증명을 사용하여 연결 문자열을 구성하려면 이 문서의 이후 섹션에 나와 있는 것처럼 REST API 또는 관련 도구를 사용합니다. Application Insights 연결 문자열에 대해 자세히 알아봅니다.
참고 항목
Application Insights 리소스가 다른 테넌트에 있는 경우 이 문서의 이후 섹션에 나와 있는 것처럼 REST API 또는 관련 도구를 사용하여 로거를 만들어야 합니다.
둘째, API에 대해 Application Insights 로깅을 사용하도록 설정합니다.
이 문서에서는 Azure Portal을 사용하여 API에 대해 Application Insights 로깅을 사용하도록 설정합니다. API Management는 API에 대한 진단 리소스를 구성합니다.
Azure Portal을 사용하여 연결 만들기
Azure Portal을 사용하여 Application Insights와 API Management 간의 연결을 만들려면 다음 단계를 따릅니다.
참고 항목
가능한 경우 Microsoft에서는 보안을 강화하기 위해 관리 ID 자격 증명과 함께 연결 문자열을 사용하는 것이 좋습니다. 이러한 자격 증명을 구성하려면 이 문서의 이후 섹션에 나와 있는 것처럼 REST API 또는 관련 도구를 사용합니다.
Azure Portal에서 Azure API Management 서비스 인스턴스로 이동합니다.
왼쪽 메뉴에서 Application Insights를 선택합니다.
+추가를 선택합니다.
앞에서 만든 Application Insights 인스턴스를 선택하고, 간단한 설명을 제공합니다.
Application Insights에서 API Management 인스턴스의 가용성 모니터링을 사용하도록 설정하려면, 가용성 모니터 추가 확인란을 선택합니다.
- 이 설정은 API Management 게이트웨이 엔드포인트가 응답하는지 여부를 정기적으로 유효성 검사합니다.
- 결과는 Application Insights 인스턴스의 가용성 창에 표시됩니다.
만들기를 실행합니다.
이제 새 Application Insights 로거가 목록에 나타나는지 확인합니다.
참고 항목
내부적으로, Application Insights 인스턴스의 계측 키를 포함하는 API Management 인스턴스에 로거 엔터티가 생성됩니다.
팁
Application Insights 로거에 구성된 계측 키를 업데이트해야 하는 경우 목록에서 로거의 행(로거 이름이 아님)을 선택합니다. 계측 키를 입력하고 저장을 선택합니다.
REST API, Bicep 또는 ARM 템플릿을 사용하여 연결 만들기
다음 단계에 따라 REST API, Bicep 또는 ARM 템플릿을 사용하여 API Management 인스턴스용 Application Insights 로거를 만드세요. 관리 ID 자격 증명(권장)과 함께 연결 문자열을 사용하는 로거 또는 연결 문자열만 사용하는 로거를 구성할 수 있습니다.
관리 ID 자격 증명과 함께 연결 문자열을 사용하는 로거(권장)
API Management 관리 ID를 사용하기 위한 필수 조건을 참조하세요.
Application Insights 연결 문자열은 Application Insights 리소스의 개요 섹션에 표시됩니다.
시스템이 할당한 관리 ID와 연결 문자열
API Management 로거 사용 - 다음 요청 본문으로 REST API를 만들거나 업데이트합니다.
{
"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"
}
}
}
사용자가 할당한 관리 ID와 연결 문자열
API Management 로거 사용 - 다음 요청 본문으로 REST API를 만들거나 업데이트합니다.
{
"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>"
}
}
}
연결 문자열 자격 증명만 있는 로거
Application Insights 연결 문자열은 Application Insights 리소스의 개요 섹션에 표시됩니다.
API Management 로거 사용 - 다음 요청 본문으로 REST API를 만들거나 업데이트합니다.
작업 영역에 대한 로거를 구성하는 경우 작업 영역 로거 사용 - REST API를 만들거나 업데이트합니다.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
API에 대한 Application Insights 로깅 사용
API에 대해 Application Insights 로깅을 사용하도록 설정하려면 다음 단계를 따릅니다. 모든 API에 대해 Application Insights 로깅을 사용하도록 설정할 수도 있습니다.
Azure Portal에서 Azure API Management 서비스 인스턴스로 이동합니다.
왼쪽 메뉴에서 API를 선택합니다.
API를 클릭합니다(여기서는 데모 회의 API). 구성된 경우 버전을 선택합니다.
팁
모든 API에 대한 로깅을 사용하도록 설정하려면 모든 API를 선택합니다.
위쪽 표시줄의 설정 탭으로 이동합니다.
진단 로그 섹션까지 아래로 스크롤합니다.
사용 확인란을 선택합니다.
대상 드롭다운에서 연결된 로거를 선택합니다.
샘플링(%)으로 100을 입력하고, 항상 오류 로깅 확인란을 선택합니다.
나머지 설정은 있는 그대로 둡니다. 설정에 대한 자세한 내용은 진단 로그 설정 참조를 참조하세요.
Warning
기본 로그할 페이로드 바이트 수 값(0)을 재정의하면 API 성능이 크게 저하될 수 있습니다.
저장을 선택합니다.
내부적으로
applicationinsights라는 진단 엔터티가 API 수준에서 만들어집니다.
참고 항목
API Management에서 전체 응답을 클라이언트에 보내면 요청이 성공한 것입니다.
단일 API 또는 모든 API용 로거
로거는 다양한 수준에서 지정할 수 있습니다.
- 단일 API 로거
- 모든 API에 대한 로거
다음과 같이 둘 모두를 지정합니다.
- 기본적으로 단일 API 로거(보다 세부적인 수준)는 모든 API에 대한 API 로거를 재정의합니다.
- 두 수준에서 구성된 로거가 다르고 두 로거가 모두 원격 분석(멀티플렉싱)을 수신해야 하는 경우 Microsoft 지원에 문의하세요. "모든 API" 수준과 단일 API 레벨에서 동일한 로거(Application Insights 대상)를 사용하는 경우 멀티플렉싱이 지원되지 않습니다. 멀티플렉싱이 올바르게 작동하려면 "모든 API" 및 개별 API 레벨에서 다양한 로거를 구성하고 Microsoft 지원에 도움을 요청하여 서비스에 대한 멀티플렉싱을 사용하도록 설정해야 합니다.
Application Insights에 추가되는 데이터
Application Insights에서 받는 항목은 다음과 같습니다.
| 원격 분석 항목 | 설명 |
|---|---|
| 요청 | 들어오는 모든 요청에 대해:
|
| 종속성 | 백 엔드 서비스에 전달되는 모든 요청에 대해:
|
| 예외 | 모든 실패한 요청에 대해:
|
| Trace | trace 정책을 구성하는 경우입니다. trace 정책의 severity 설정은 Application Insights 로깅의 verbosity 설정보다 크거나 같아야 합니다. |
참고 항목
Application Insights 인스턴스당 메트릭 및 이벤트의 최대 크기와 수에 대한 자세한 내용은 Application Insights 제한을 참조하세요.
사용자 지정 메트릭 내보내기
API Management 인스턴스에서 Application Insights로 사용자 지정 메트릭을 내보낼 수 있습니다. API Management는 emit-metric 및 azure-openai-emit-token-metric과 같은 정책을 사용하여 사용자 지정 메트릭을 내보냅니다. 다음 섹션에서는 emit-metric 정책을 예로 사용합니다.
사용자 지정 메트릭을 내보내려면 다음 구성 단계를 수행합니다.
Application Insights 인스턴스에서 사용자 지정 차원으로 사용자 지정 메트릭(미리 보기)을 사용하도록 설정합니다.
- 포털에서 Application Insights 인스턴스로 이동합니다.
- 왼쪽 메뉴에서 사용량 및 예상 비용을 선택합니다.
- 사용자 지정 메트릭(미리 보기)>차원 포함을 선택합니다.
- 확인을 선택합니다.
API Management에 구성된
applicationInsights진단 엔터티에"metrics": true속성을 추가합니다. 현재 API Management 진단 - 만들기 또는 업데이트 REST API를 사용하여 이 속성을 추가해야 합니다. 예시: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 [...] } }사용자 지정 메트릭(모든 API 또는 단일 API)을 내보내려는 범위에서 Application Insights 로거가 구성되어 있는지 확인합니다. 자세한 내용은 이 문서 앞부분의 API에 대해 Application Insights 로깅 사용을 참조하세요.
Application Insights 로깅이 구성되고(모든 API 또는 단일 API) 사용자 지정 메트릭에 대해 사용하도록 설정된 범위에서
emit-metric정책을 구성합니다. 정책 세부 정보는emit-metric정책 참조를 확인합니다.
사용자 지정 메트릭 한도
Azure Monitor는 API Management에서 메트릭을 내보내는 기능에 영향을 줄 수 있는 사용자 지정 메트릭에 대해 사용 제한을 적용합니다. 예를 들어, Azure Monitor는 현재 메트릭당 차원 키 제한을 10개로 설정하고 구독의 지역당 총 활성 시계열 제한을 50,000개(12시간 이내)로 설정합니다.
이러한 제한은 다음과 같은 API Management 정책에서 사용자 지정 메트릭을 구성하는 데 다음과 같은 emit-metric azure-openai-emit-token-metric영향을 줍니다.
정책당 최대 10개의 사용자 지정 차원을 구성할 수 있습니다.
12시간 이내에 정책에 의해 생성된 활성 시계열 수는 해당 기간 동안 구성된 각 차원의 고유 값 수를 곱한 것입니다. 예를 들어, 정책에 3개의 사용자 지정 차원이 구성되어 있고 각 차원에 해당 기간 내에 가능한 값이 10개 있는 경우 정책은 1,000(10 x 10 x 10)개의 활성 시계열을 제공합니다.
구독의 동일한 지역에 있는 여러 API Management 인스턴스에서 정책을 구성하는 경우 모든 인스턴스가 지역 활성 시계열 제한에 기여할 수 있습니다.
Azure Monitor에서 사용자 지정 메트릭에 대한 디자인 제한 사항 및 고려 사항에 대해 자세히 알아봅니다.
성능에 미치는 영향 및 로그 샘플링
Warning
모든 이벤트를 기록하면 들어오는 요청 속도에 따라 성능에 심각한 영향을 미칠 수 있습니다.
내부 부하 테스트에 따라 로깅 기능을 사용하도록 설정하면 요청 속도가 초당 1,000개 요청을 초과할 때 처리량이 40~50% 감소했습니다. Application Insights는 통계 분석을 사용하여 애플리케이션 성능을 평가하도록 설계되었습니다. 현재 다음과 같습니다.
- 감사 시스템이 아닙니다.
- 대용량 API에 대한 각 개별 요청을 로그하는 데 적합하지 않습니다.
샘플링 설정을 조정하여 로그된 요청 수를 조작할 수 있습니다. 값이 100%이면 모든 요청이 기록됨을 의미하고, 0%는 기록되지 않음을 의미합니다.
샘플링을 사용하면 원격 분석의 양을 줄이고 로깅의 이점을 계속 유지하면서 상당한 성능 저하를 효과적으로 방지할 수 있습니다.
성능 문제를 개선하려면 다음을 건너뜁니다.
- 요청 및 응답 헤더
- 본문 로깅
동영상
문제 해결
API Management에서 Application Insights로의 원격 분석 데이터 흐름 문제 해결:
- API Management 리소스가 연결된 VNet 내에 연결된 AMPLS(Azure Monitor Private Link 범위) 리소스가 있는지 조사합니다. AMPLS 리소스는 구독 전반에 걸쳐 전역 범위를 가지며 모든 Azure Monitor 리소스에 대한 데이터 쿼리 및 수집을 관리합니다. AMPLS가 데이터 수집을 위해 특별히 프라이빗 전용 액세스 모드로 구성되었을 가능성이 있습니다. 이러한 경우 Application Insights 리소스 및 관련 Log Analytics 리소스를 AMPLS에 포함합니다. 이렇게 추가하면 API Management 데이터가 Application Insights 리소스에 성공적으로 수집되어 원격 분석 데이터 전송 문제가 해결됩니다.
관련 콘텐츠
- Azure Application Insights에 대해 자세히 알아봅니다.
- Azure Event Hubs에 로깅을 살펴봅니다.
- Azure Managed Grafana를 사용하여 Application Insights에서 데이터를 시각화하는 방법을 알아봅니다.