Application Insights JavaScript SDK 문제 해결
이 문서에서는 Application Insights JavaScript SDK와 관련된 다양한 문제를 해결하는 방법을 설명합니다. 이 문서의 주체에는 JavaScript 웹앱에 대한 SDK 로드 실패 및 JavaScript 앱에 대한 소스 맵 지원이 포함됩니다.
JavaScript 웹앱에 대한 SDK 로드 실패 문제 해결
다음 섹션에서는 JavaScript 웹앱에 대한 특정 SDK 로드 실패 시나리오의 증상, 원인 및 솔루션에 대해 설명합니다.
증상
<모니터링하는 웹 페이지의 헤드> 요소에서 JavaScript 코드 조각(버전 3 이상)은 SDK 스크립트가 다운로드하거나 초기화하지 않았음을 감지하면 다음 예외를 만들고 보고합니다.
SDK 로드 실패: Application Insights SDK 스크립트를 로드하지 못했습니다(자세한 내용은 스택 참조)
이 메시지는 사용자의 클라이언트(브라우저)가 Application Insights SDK를 다운로드하거나 식별된 호스팅 페이지에서 초기화할 수 없음을 나타냅니다. 따라서 원격 분석 또는 이벤트가 표시되지 않습니다.
참고 항목
이 예외는 API 또는 XMLHttpRequest를 지원하는 모든 주요 브라우저에서 fetch() 지원됩니다. 이러한 브라우저 버전은 Microsoft Internet Explorer 8 및 이전 버전을 제외합니다. 따라서 환경에 페치 폴리필이 포함되지 않는 한 이러한 브라우저는 이러한 유형의 예외를 보고하지 않습니다.
스택 세부 정보에는 사용자가 사용하는 URL에 대한 기본 정보가 포함됩니다.
| 속성 | 설명 |
|---|---|
| <CDN 엔드포인트> | SDK를 다운로드하는 데 사용되거나 다운로드하지 못한 URL입니다. |
| <도움말 링크> | 문제 해결 설명서(이 페이지)로 연결되는 URL입니다. |
| <호스트 URL> | 사용자가 사용하던 페이지의 전체 URL입니다. |
| <엔드포인트 URL> | 예외를 보고하는 데 사용된 URL입니다. 이 값은 퍼블릭 인터넷 또는 프라이빗 클라우드가 호스팅 페이지에 액세스했는지 여부를 식별하는 데 도움이 될 수 있습니다. |
다음 목록에는 이 예외가 발생하는 가장 일반적인 이유가 포함되어 있습니다.
일시적인 네트워크 연결 오류
Application Insights CDN(Content Delivery Network) 중단
스크립트를 로드한 후 SDK 초기화 실패
Application Insights JavaScript CDN의 차단
간헐적인 네트워크 연결 실패 는 특히 모바일 로밍 시나리오에서 이 예외의 가장 일반적인 이유입니다.
다음 섹션에서는 이 오류의 잠재적인 근본 원인을 해결하는 방법을 설명합니다.
참고 항목
이러한 단계 중 일부는 애플리케이션이 호스팅 HTML 페이지의 일부로 반환되는 코드 조각 <스크립트/>태그 및 해당 구성을 직접 제어한다고 가정합니다. 이러한 조건이 시나리오에 적용되지 않는 경우 이러한 단계도 적용되지 않습니다.
원인 1: 일시적인 네트워크 연결 실패
사용자가 간헐적인 네트워크 연결 실패를 경험하는 경우 다른 원인보다 가능한 솔루션이 적습니다. 그러나 이 오류는 일반적으로 빠르게 해결됩니다. 예를 들어 사용자가 사이트를 다시 로드하기 위해 페이지를 새로 고치면 업데이트된 버전이 릴리스될 때까지 파일이 다운로드되고 로컬로 캐시됩니다.
솔루션 1a: 업데이트된 버전의 SDK 다운로드
간헐적인 네트워크 연결 오류를 최소화하기 위해 모든 CDN 파일에 헤더를 구현했습니다 Cache-Control . 사용자의 브라우저에서 현재 버전의 SDK를 다운로드한 후에는 이전에 가져온 복사본을 다시 사용하기 때문에 다시 다운로드할 필요가 없습니다. (캐싱의 작동 방식을 참조하세요.) 캐싱 검사가 실패하거나 사용 가능한 새 릴리스가 있는 경우 사용자의 브라우저에서 업데이트된 버전을 다운로드해야 합니다. 따라서 검사 실패 시나리오에서 배경 수준의 "노이즈" 가 표시될 수 있습니다. 또는 새 릴리스가 발생하고 일반 공급될 때(CDN에 배포됨) 일시적인 급증이 표시될 수 있습니다.
솔루션 1b: npm 패키지를 사용하여 단일 번들에 애플리케이션과 함께 SDK 포함
SDK 부하 오류 예외가 영구적이며, 일반 클라이언트 원격 분석의 감소와 함께 많은 사용자에 대해 발생하나요? 이 경우 간헐적인 네트워크 연결 문제는 문제의 진정한 원인이 아닐 수 있으며 다른 가능한 원인을 탐색해야 합니다.
참고 항목
여러 사용자에 대해 이 오류가 발생한다는 일반적인 표시는 예외가 신속하고 지속적인 수준에서 보고된다는 것입니다.
이 경우 자체 CDN에서 SDK를 호스팅하면 이 예외 발생을 제공하거나 줄일 수 없습니다. 동일한 문제는 사용자 고유의 CDN에 영향을 미치며 npm 패키지 솔루션을 통해 SDK를 사용하는 경우에도 발생합니다. 두 번째 시나리오의 실패는 특히 Application Insights가 모니터링되는 애플리케이션의 번들에서 다른 번들에 포함된 경우 발생합니다. 이러한 번들 중 하나 이상에서 오류가 발생하도록 보장되기 때문입니다. 사용자의 관점에서 이 예외가 발생하면 전체 애플리케이션이 원격 분석 SDK(사용자에게 표시되지 않음)뿐만 아니라 로드 또는 초기화에 실패합니다. 따라서 사용자가 완전히 로드될 때까지 사이트를 계속 새로 고칠 수 있습니다.
npm 패키지를 사용하여 모니터링되는 애플리케이션과 함께 Application Insights SDK를 단일 번들에 포함할 수 있습니다. 이 시나리오에서는 간헐적 오류가 계속 발생할 수 있지만 결합된 번들은 문제를 해결할 수 있는 실제 기회를 제공합니다.
원인 2: Application Insights CDN 중단
Application Insights CDN 중단이 있는지 확인하려면 사용자와 다른 위치에서 브라우저에서 직접 CDN 엔드포인트에 액세스합니다. 예를 들어 자체 개발 컴퓨터에서 액세스를 https://js.monitor.azure.com/scripts/b/ai.2.min.js 시도할 수 있습니다. (조직에서 이 도메인을 차단하지 않은 것으로 가정합니다.)
솔루션 2: 지원 티켓 만들기
중단이 있는지 확인하는 경우 새 지원 티켓을 만들 수 있습니다.
원인 3: 스크립트를 로드한 후 SDK가 초기화되지 않음
SDK가 초기화 <되지 않으면 스크립트/> 가 CDN에서 성공적으로 다운로드되지만 초기화 중에 실패합니다. 이 오류는 누락되거나 잘못된 종속성 또는 일부 형태의 JavaScript 예외로 인해 발생합니다.
해결 방법 3: 성공적인 SDK 다운로드 또는 JavaScript 예외를 확인하거나 브라우저 디버깅을 사용하도록 설정합니다.
1단계: 성공적인 SDK 다운로드 확인
SDK가 성공적으로 다운로드되었는지 확인합니다. 스크립트 다운로드가 발생하지 않은 경우 이 시나리오는 SDK 로드 실패 예외의 원인이 아닙니다. 개발자 도구를 지원하는 브라우저를 사용합니다. F12를 선택하여 개발자 도구를 본 다음 네트워크 탭을 선택합니다. src 코드 조각 구성에 정의된 스크립트가 다운로드되었는지 확인합니다. 이렇게 하려면 응답 코드 200 (성공) 또는 304 (변경되지 않음) 확인합니다. 네트워크 트래픽을 검토하려면 Fiddler와 같은 웹 디버깅 도구를 사용할 수도 있습니다.
SDK가 성공적으로 다운로드되지 않은 경우 다음 표를 검토하여 다양한 보고 옵션을 이해합니다.
| 시나리오 | 원인 | 작업 |
|---|---|---|
| 이 문제는 소수의 사용자와 특정 브라우저 버전 또는 브라우저 버전의 하위 집합에만 영향을 줍니다. (보고된 예외에 대한 세부 정보를 확인합니다.) | 이 문제는 특정 사용자 또는 환경에서 애플리케이션이 추가 polyfill 구현을 제공해야 하는 경우에만 발생할 수 있습니다. |
GitHub에서 문제를 제출합니다. |
| 이 문제는 전체 애플리케이션 및 모든 사용자에게 영향을 줍니다. | 릴리스 관련 문제입니다. | 새 지원 티켓을 만듭니다. |
SDK가 성공적으로 다운로드된 경우 다음 섹션을 검토하여 SDK 초기화 문제를 해결합니다.
2단계: JavaScript 예외 확인
JavaScript 예외를 확인합니다. 개발자 도구를 지원하는 브라우저를 사용합니다. F12를 선택하여 개발자 도구를 보고, 페이지를 로드한 다음, 예외가 발생했는지 확인합니다. SDK 스크립트(예: ai.2.min.js)에서 예외가 발생하나요? 이 경우 다음 시나리오 중 하나가 발생했습니다.
SDK에 전달되는 구성에는 예기치 않은 구성이 포함되어 있습니다.
SDK에 전달되는 구성에 필요한 구성이 없습니다.
잘못된 릴리스가 CDN에 배포되었습니다.
잘못된 구성을 확인하려면 계측 키만 문자열 값으로 포함하도록 코드 조각에 전달된 구성(아직 수행하지 않은 경우)을 변경합니다. 다음 코드는 코드 조각 구성 변경 예제를 보여줍니다.
참고 항목
계측 키 수집에 대한 지원은 2025년 3월 31일에 종료됩니다. 계측 키 수집은 계속 작동하지만 더 이상 기능에 대한 업데이트 또는 지원을 제공하지 않습니다. 새 기능을 활용하려면 연결 문자열 전환을 참조하세요.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>"
}});
</script>
이 최소 구성을 사용하는 경우 SDK 스크립트 에 JavaScript 예외가 계속 표시되는 경우 새 지원 티켓을 만듭니다. 이 문제를 해결하려면 잘못된 빌드를 롤백해야 합니다. 이는 새로 배포된 버전이 문제의 원인일 수 있기 때문입니다.
예외가 사라지면 형식이 일치하지 않거나 예기치 않은 값으로 인해 문제가 발생할 수 있습니다. 구성 옵션을 하나씩 복원하여 문제 해결을 시작하고, 예외가 다시 발생할 때까지 각 변경 후 테스트합니다. 다음으로, 문제를 일으키는 항목에 대한 설명서를 확인합니다. 설명서가 명확하지 않거나 도움이 필요한 경우 GitHub에 문제를 제출합니다.
구성이 이전에 배포되고 작동했지만 이제 이 예외를 보고하고 있나요? 이 경우 새로 배포된 버전에 영향을 주는 문제가 있을 수 있습니다. 예외가 사용자 또는 브라우저의 작은 집합에만 영향을 주는지 확인합니다. GitHub에서 문제를 제출하거나 새 지원 티켓을 만듭니다.
3단계: 브라우저 콘솔 디버깅 사용
throw된 예외가 발생하지 않은 경우 다음 코드 조각 구성 예제와 같이 loggingLevelConsole 설정을 구성에 추가하여 콘솔 디버깅을 사용하도록 설정해야 합니다. 이 변경은 모든 초기화 오류 및 경고를 브라우저의 콘솔로 보냅니다. (브라우저 콘솔을 보려면 F12를 선택하여 개발자 도구를 연 다음 콘솔 탭.) 보고된 오류는 설명이 있어야 합니다. 추가 지원이 필요한 경우 GitHub에 문제를 제출합니다.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>",
loggingLevelConsole: 2
}});
</script>
참고 항목
초기화 중에 SDK는 알려진 주요 종속성에 대한 몇 가지 기본 검사를 수행합니다. 현재 런타임에서 이러한 검사를 제공하지 않는 경우 런타임은 오류를 콘솔에 경고 메시지로 보고합니다(설정 값이 0보다 큰 경우에만 loggingLevelConsole ).
SDK가 아직 초기화되지 않은 경우 enableDebug 구성 설정을 사용하도록 설정해 봅니다. 이 변경을 수행하면 모든 내부 오류가 예외로 throw됩니다. 이로 인해 원격 분석이 손실됩니다. 이 설정은 개발자만을 위한 설정이므로 내부 검사로 인해 더 많은 예외가 throw될 수 있습니다. 각 예외를 검토하여 SDK가 실패하는 문제를 확인합니다. 파일 이름 확장명을 .min.js .js 변경하여 수정되지 않은 버전의 스크립트를 사용합니다. 그렇지 않으면 예외를 읽을 수 없습니다. 다음 코드는 코드 조각 구성 변경 예제를 보여줍니다.
Warning
이렇게 하면 원격 분석이 손실되므로 이 개발자 전용 설정은 전체 프로덕션 환경에서 사용하도록 설정해서는 안 됩니다.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
instrumentationKey: "<instrumentation-key-guid>",
enableDebug: true
}});
</script>
이 작업이 여전히 인사이트를 제공하지 않는 경우 세부 정보 및 예제 사이트를 제공하여 GitHub에 문제를 제출해야 합니다( 사용하는 경우). 문제를 식별하는 데 도움이 되는 브라우저 버전, 운영 체제 및 JavaScript 프레임워크 세부 정보를 포함합니다.
원인 4: Application Insights JavaScript CDN 차단
Application Insights JavaScript SDK CDN 엔드포인트가 안전하지 않은 것으로 보고되거나 식별되는 경우 CDN 차단이 가능합니다. 이 경우 엔드포인트는 공개적으로 차단되고 이러한 목록의 소비자는 모든 액세스를 차단하기 시작합니다.
이 문제를 해결하려면 CDN 엔드포인트의 소유자가 엔드포인트를 안전하지 않은 것으로 표시한 차단 목록 엔터티와 함께 작동해야 합니다. 그런 다음 차단 목록 엔터티가 관련 목록에서 엔드포인트를 제거할 수 있습니다.
CDN 엔드포인트를 안전하지 않은 것으로 식별하는지 여부를 알아보려면 다음 인터넷 보안 웹 사이트를 확인합니다.
이 문제를 해결하는 데 시간이 오래 걸릴 수 있습니다. 사용자 또는 회사 IT 부서는 강제로 업데이트를 하거나 CDN 엔드포인트를 명시적으로 허용해야 할 수 있습니다. 이 문제를 해결하는 데 필요한 총 시간은 애플리케이션, 방화벽 또는 환경에서 목록의 로컬 복사본을 업데이트하는 데 필요한 빈도에 따라 달라집니다.
CDN 엔드포인트가 안전하지 않은 것으로 확인되면 지원 티켓을 만들어 가능한 한 빨리 문제를 해결합니다.
다음 섹션에서는 방해가 발생할 수 있는 방법 및 막힘을 해결하는 방법을 보다 구체적으로 설명합니다.
원인 4a: 사용자 차단(브라우저, 설치된 차단기 또는 개인 방화벽)
사용자가 다음 구성 작업을 수행했는지 확인합니다.
브라우저 플러그 인(일반적으로 광고, 맬웨어 또는 팝업 차단기 형식)이 설치됨
브라우저 또는 프록시에서 Application Insights CDN 엔드포인트 차단 또는 허용 안 함
SDK에 대한 CDN 도메인의 차단을 발생시키는 방화벽 규칙 구성(또는 DNS 항목 확인 실패)
해결 방법 4a: CDN 엔드포인트에 대한 차단 목록 예외 추가
사용자가 나열된 구성 작업을 수행한 경우 함께 작업하거나 설명서를 제공하여 CDN 엔드포인트를 허용합니다.
사용자가 공용 차단 목록을 사용하는 플러그 인을 설치했을 수 있습니다. 그렇지 않은 경우 수동으로 구성된 다른 솔루션을 사용하거나 플러그 인에서 프라이빗 도메인 차단 목록을 사용하고 있을 수 있습니다.
브라우저의 플러그 인 또는 방화벽 규칙 예외 목록에 엔드포인트를 포함하여 Application Insights CDN 엔드포인트에서 스크립트 다운로드를 허용하도록 사용자에게 지시합니다. 이러한 목록은 사용자 환경에 따라 달라집니다.
다음은 웹 사이트에 대한 액세스를 허용하거나 차단하도록 Google Chrome을 구성하는 방법을 보여 주는 이 상황의 예입니다.
원인 4b: 회사 방화벽 차단
사용자가 회사 네트워크에 있는 경우 회사 방화벽은 CDN 차단의 원본일 수 있습니다. 회사 IT 부서는 아마도 일종의 인터넷 필터링 시스템을 구현했을 것입니다.
솔루션 4b1: 기업의 CDN 엔드포인트에 대한 예외 추가
Important
사용자가 프라이빗 클라우드를 사용하고 공용 인터넷에 액세스할 수 없나요? 이 경우 Application Insights npm 패키지를 사용하여 SDK를 포함하거나 자체 CDN에 Application Insights SDK를 호스트해야 합니다.
회사의 IT 부서와 협력하여 사용자에게 필요한 규칙을 허용합니다. 이 솔루션은 사용자에 대한 예외를 추가하는 것과 유사합니다. IT 부서에서 도메인 차단 목록 또는 허용 목록 서비스에 포함(또는 제거)하여 다운로드할 Application Insights CDN 엔드포인트를 구성하도록 합니다.
솔루션 4b2: 사용자 고유의 CDN에서 SDK 호스트
사용자가 공용 CDN에서 Application Insights SDK를 다운로드하는 대신 사용자 고유의 CDN 엔드포인트에서 Application Insights SDK를 호스트할 수 있습니다. 사용 중인 버전을 더 쉽게 식별할 수 있도록 SDK의 특정 버전(ai.2.#.#.min.js)을 사용하는 것이 좋습니다. 또한 버그 수정 및 사용 가능한 새 기능을 사용할 수 있도록 SDK를 현재 버전(ai.2.min.js)으로 정기적으로 업데이트합니다.
솔루션 4b3: npm 패키지를 사용하여 Application Insights SDK 포함
코드 조각을 사용하고 공용 CDN 엔드포인트를 추가하는 대신 npm 패키지를 사용하여 SDK를 사용자 고유의 JavaScript 파일의 일부로 포함할 수 있습니다. SDK는 사용자 고유의 스크립트 내의 다른 패키지가 됩니다. 자세한 내용은 Application Insights JavaScript SDK GitHub 페이지의 npm 기반 설정 섹션을 참조하세요.
참고 항목
npm 패키지를 사용하는 경우 코드 분할 및 축소를 수행하는 데 도움이 되는 일부 형태의 JavaScript 번들러 도 사용하는 것이 좋습니다.
코드 조각과 마찬가지로 여기에 표시되는 동일한 차단 문제는 SDK npm 패키지를 사용하거나 사용하지 않고도 사용자 고유의 스크립트에 영향을 줄 수 있습니다. 애플리케이션, 사용자 및 프레임워크에 따라 코드 조각의 논리와 유사한 항목을 구현하여 이러한 문제를 감지하고 보고할 수 있습니다.
JavaScript 애플리케이션에 대한 원본 맵 지원 문제 해결
다음 표에서는 JavaScript 애플리케이션에 대한 원본 맵 지원과 관련된 특정 문제에 대해 설명하고 이러한 문제를 해결하는 데 도움이 되는 전략을 제공합니다.
| 문제 | 설명 |
|---|---|
| Blob 컨테이너에 필요한 Azure RBAC(역할 기반 액세스 제어) 설정 | 이 기능을 사용하는 포털의 모든 사용자는 Blob 컨테이너에 대한 스토리지 Blob 데이터 판독기 역할 이상을 할당해야 합니다. 이 기능을 통해 소스 맵을 사용하려는 모든 사용자에게 이 역할을 할당해야 합니다. 컨테이너를 만든 방법에 따라 이 역할이 사용자 또는 팀에 자동으로 할당되지 않았을 수 있습니다. |
| 소스 맵을 찾을 수 없음 | 이 문제를 해결하려면 다음 작업을 수행합니다.
|
"parentId 값이 없는 이벤트 행 클릭" 경고 수정
애플리케이션에서 Application Insights 및 Click Analytics 자동 수집 플러그 인을 사용하는 경우 Application Insights 통합 문서에 "parentId 값이 없는 이벤트 행 클릭"에 다음과 같은 원격 분석 경고가 표시될 수 있습니다.
원인
부모 HTML 요소에 부모 ID가 지정되지 않은 경우 이 문제가 발생할 수 있습니다. 이 조건으로 인해 모든 부모 요소에서 이벤트가 트리거됩니다.
솔루션
이 문제를 해결하려면 부모 HTML 요소에 data-parentid 특성 또는 data-<customPrefix>-parentid 특성을 추가합니다. HTML 코드의 예는 다음과 같습니다.
<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">
다음 단계
타사 정보 고지 사항
이 문서에 나와 있는 다른 공급업체 제품은 Microsoft와 무관한 회사에서 제조한 것입니다. Microsoft는 이들 제품의 성능이나 안정성에 관하여 명시적이든 묵시적이든 어떠한 보증도 하지 않습니다.
도움을 요청하십시오.
질문이 있거나 도움이 필요한 경우 지원 요청을 생성하거나Azure 커뮤니티 지원에 문의하세요. Azure 피드백 커뮤니티에 제품 피드백을 제출할 수도 있습니다.