Azure Cosmos DB .NET SDK를 사용하는 경우 문제 진단 및 해결
적용 대상: 
NoSQL
이 문서에서는 Azure Cosmos DB for NoSQL 계정에서 .NET SDK를 사용할 때 발생하는 일반적인 문제, 해결 방법, 진단 단계 및 도구에 대해 설명합니다. .NET SDK는 Azure Cosmos DB for NoSQL에 액세스하기 위한 클라이언트 쪽 논리적 표현을 제공합니다. 이 문서에서는 문제가 발생하는 경우 사용자에게 도움이 되는 도구 및 방법을 설명합니다.
문제 해결을 위한 검사 목록
애플리케이션을 프로덕션으로 이동하기 전에 다음 체크리스트를 고려해야 합니다. 검사 목록을 사용하면 표시되는 몇 가지 일반적인 문제를 방지할 수 있습니다. 문제가 발생하는 경우 신속하게 진단할 수도 있습니다.
- 최신 SDK를 사용해야 합니다. 미리 보기 SDK는 프로덕션에 사용하면 안 됩니다. 이렇게 하면 이미 수정된 알려진 문제가 발생하지 않습니다.
- 성능 팁을 검토하고 제안된 사례를 따릅니다. 이렇게 하면 크기 조정, 대기 시간 및 기타 성능 문제를 방지할 수 있습니다.
- 문제를 해결하는 데 도움이 되도록 SDK 로깅을 사용하도록 설정합니다. 로깅을 사용하도록 설정하면 성능에 영향을 줄 수 있으므로 문제를 해결할 때만 로깅을 사용하도록 설정하는 것이 가장 좋습니다. 다음 로그를 활성화할 수 있습니다.
이 문서의 일반적인 문제 및 해결 방법 섹션을 살펴봅니다.
적극적으로 모니터링되는 GitHub 문제 섹션을 확인하세요. 해결 방법이 있는 유사한 문제가 이미 제출되었는지 확인합니다. 솔루션을 찾지 못한 경우 GitHub 문제를 제출합니다. 긴급한 문제에 대한 지원 틱을 열 수 있습니다.
진단 캡처
CosmosException을 포함하여 SDK의 모든 응답에는 Diagnostics 속성이 있습니다. 이 속성은 재시도 또는 일시적 실패가 있었는지 여부를 포함하여 단일 요청과 관련된 모든 정보를 기록합니다.
진단은 문자열로 반환합니다. 버전마다 문자열이 변경되며, 다양한 시나리오의 문제 해결을 위해 개선되기 때문입니다. 각 SDK 버전에서 문자열의 서식 지정에 대한 호환성이 손상되는 변경이 발생합니다. 호환성이 손상되는 변경이 발생하지 않도록 문자열을 구문 분석하지 마세요. 다음 코드 샘플은 .NET SDK를 사용하여 진단 로그를 읽는 방법을 보여줍니다.
try
{
ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
{
// Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs
}
}
catch (CosmosException cosmosException)
{
// Log the full exception including the stack trace with: cosmosException.ToString()
// The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}
// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
// Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}
일반적인 이슈 및 해결 방법
일반 제안
- 예외 세부 정보에 포함된
aka.ms링크를 따릅니다. - 가능하면 Azure Cosmos DB 계정과 동일한 Azure 지역에서 앱을 실행합니다.
- 클라이언트 컴퓨터에 리소스가 부족하여 연결/가용성 문제가 발생할 수 있습니다. Azure Cosmos DB 클라이언트를 실행하는 노드에서 CPU 사용률을 모니터링하고 부하가 높은 경우 노드를 확장/축소하는 것이 좋습니다.
포털 메트릭 확인
포털 메트릭을 확인하면 클라이언트 쪽 문제인지 또는 서비스에 문제가 있는지 확인하는 데 도움이 됩니다. 예를 들어 측정항목에 높은 비율의 비율 제한 요청(HTTP 상태 코드 429)이 포함되어 요청이 제한되고 있음을 의미하는 경우 요청 비율이 너무 큼 섹션을 확인하십시오.
다시 시도 디자인
복원력 있는 애플리케이션을 설계하고 SDK의 다시 시도 의미 체계에 대해 알아보려면 Azure Cosmos DB SDK로 복원력 있는 애플리케이션 디자인 지침을 참조하세요.
SNAT
앱이 공용 IP 주소가 없는 Azure Virtual Machines에 배포된 경우 기본적으로 Azure SNAT 포트는 VM 외부의 모든 엔드포인트에 대한 연결을 설정합니다. VM에서 Azure Cosmos DB 엔드포인트로 허용되는 연결 수는 Azure SNAT 구성으로 제한됩니다. 이 상황은 연결 제한, 연결 종료 또는 위에서 언급한 요청 시간 초과로 이어질 수 있습니다.
Azure SNAT 포트는 VM에 개인 IP 주소가 있는 경우에만 공용 IP 주소에 연결하는 데 사용됩니다. Azure SNAT 제한을 피하기 위한 두 가지 해결 방법이 있습니다(전체 애플리케이션에서 이미 단일 클라이언트 인스턴스를 사용하고 있는 경우).
Azure Virtual Machines 가상 네트워크의 서브넷에 Azure Cosmos DB 서비스 엔드포인트를 추가합니다. 자세한 내용은 Azure Virtual Network 서비스 엔드포인트를 참조하세요.
서비스 엔드포인트를 사용하도록 설정한 경우 요청이 더 이상 공용 IP에서 Azure Cosmos DB로 전송되지 않습니다. 대신 가상 네트워크 및 서브넷 ID가 전송됩니다. 공용 IP만 허용되는 경우 이 변경 내용으로 인해 방화벽이 삭제될 수 있습니다. 방화벽을 사용하는 경우 서비스 엔드포인트를 사용하도록 설정하면 Virtual Network ACL을 사용하여 방화벽에 서브넷을 추가합니다.
Azure VM에 공용 IP를 할당합니다.
높은 네트워크 대기 시간
대기 시간 문제 해결에 대한 자세한 내용은 대기 시간 문제 해결 가이드를 참조하세요.
프록시 인증 실패
HTTP 407로 표시되는 오류가 표시되는 경우:
Response status code does not indicate success: ProxyAuthenticationRequired (407);
이 오류는 SDK에서 생성되지 않으며 Azure Cosmos DB 서비스에서 발생합니다. 네트워킹 구성과 관련된 오류입니다. 네트워크 구성의 프록시에 필요한 프록시 인증이 누락되었을 가능성이 큽니다. 프록시를 사용할 예정이 아니라면 네트워크 팀에 문의합니다. 프록시를 사용하는 경우 클라이언트 인스턴스를 만들 때 CosmosClientOptions.WebProxy에서 올바른 WebProxy 구성을 설정해야 합니다.
일반적인 쿼리 문제
쿼리 메트릭은 쿼리가 가장 많은 시간을 소비 하는 위치를 확인 하는 데 도움이 됩니다. 쿼리 메트릭에서 클라이언트와 백엔드에서 얼마나 많이 사용되고 있는지 확인할 수 있습니다. 쿼리 성능 가이드에서 자세히 알아봅니다.
Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: 오류가 발생하고 Windows를 사용하는 경우 최신 Windows 버전으로 업그레이드해야 합니다.