API for NoSQL 계정을 사용하는 Azure Cosmos DB Python SDK를 사용할 때 발생하는 문제 해결

적용 대상: NoSQL

• Python SDK
• Java SDK v4
• Async Java SDK v2
• .NET

Important

이 문서에서는 Azure Cosmos DB Python SDK에 대한 문제 해결만 다룹니다. 자세한 내용은 Azure Cosmos DB Python SDK 추가 정보 릴리스 정보, 패키지(PyPI), 패키지(Conda) 및 성능 팁을 참조하세요.

이 문서에서는 Azure Cosmos DB for NoSQL 계정으로 Azure Cosmos DB Python SDK를 사용할 때 일반적인 문제, 해결, 진단 단계 및 도구를 설명합니다. Azure Cosmos DB Python SDK는 Azure Cosmos DB for NoSQL에 액세스하기 위한 클라이언트 쪽 논리적 표현을 제공합니다. 이 문서에서는 문제가 발생하는 경우 사용자에게 도움이 되는 도구 및 방법을 설명합니다.

이 목록을 사용하여 시작합니다.

• 이 문서의 일반적인 문제 및 해결 방법 섹션을 살펴봅니다.
• GitHub의 오픈 소스에서 제공되는 Azure Cosmos DB 중앙 리포지토리에서 Python SDK를 살펴봅니다. 여기에는 능동적으로 모니터링되는 문제 섹션이 있습니다. 해결 방법이 있는 유사한 문제가 이미 제출되었는지 확인합니다. 한 가지 유용한 팁은 *Cosmos* 태그로 문제를 필터링하는 것입니다.
• Azure Cosmos DB Python SDK에 대한 성능 팁을 검토하고 제안된 사례를 따릅니다.
• 솔루션을 찾지 못한 경우 이 문서의 나머지 부분을 읽어봅니다. 그런 후, GitHub 문제를 제출합니다. GitHub 문제에 태그를 추가하는 옵션이 있는 경우 *Cosmos* 태그를 추가합니다.

진단 로깅 및 캡처

Important

최신 버전의 Python SDK를 사용하는 것이 좋습니다. 여기에서 릴리스 기록을 확인할 수 있습니다.

이 라이브러리는 로깅 진당에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 정보 수준에서 기록됩니다.

요청/응답 본문 및 미작성 헤더를 포함한 상세 디버그 수준 로깅은 logging_enable 인수를 사용하여 클라이언트에서 사용하도록 설정할 수 있습니다.

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

database = client.create_database(DATABASE_NAME, logging_enable=True)

또는 로거를 logger 인수에 전달하여 HttpLoggingPolicy Azure 코어를 확장하는 CosmosHttpLoggingPolicy을(를) 사용하여 로그할 수 있습니다. 기본적으로 HttpLoggingPolicy에서 동작을 사용합니다. enable_diagnostics_logging 인수를 전달하면 CosmosHttpLoggingPolicy이(가) 활성화되고 Cosmos 문제 디버깅과 관련된 응답에 추가 정보가 제공됩니다.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

마찬가지로 로거를 단일 요청에 전달하여 단일 작업에 대해 로깅을 사용하도록 설정할 수 있습니다. 그러나 CosmosHttpLoggingPolicy을(를) 사용하여 추가 정보를 가져오려면 클라이언트 생성자에서 enable_diagnostics_logging 인수를 전달해야 합니다.

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

다시 시도 디자인

복원력 있는 애플리케이션을 설계하고 SDK의 다시 시도 의미 체계에 대해 알아보려면 Azure Cosmos DB SDK로 복원력 있는 애플리케이션 디자인 지침을 참조하세요.

일반적인 이슈 및 해결 방법

일반 제안

최상의 성능을 얻으려면:

• 앱이 Azure Cosmos DB 계정과 동일한 지역에서 실행되고 있는지 확인합니다.
• 앱이 실행되는 호스트에서 CPU 사용량을 확인합니다. CPU 사용량이 50% 이상인 경우 더 높은 구성을 사용해서 호스트에서 앱을 실행합니다. 또는 더 많은 컴퓨터에서 부하를 분산할 수 있습니다.
  • Azure Kubernetes Service에서 애플리케이션이 실행 중인 경우 Azure Monitor를 사용하여 CPU 사용률을 모니터링할 수 있습니다.

포털 메트릭 확인

포털 메트릭을 확인하면 클라이언트 쪽 문제인지 또는 서비스에 문제가 있는지 확인하는 데 도움이 됩니다. 예를 들어 측정항목에 높은 비율의 비율 제한 요청(HTTP 상태 코드 429)이 포함되어 요청이 제한되고 있음을 의미하는 경우 요청 비율이 너무 큼 섹션을 확인하십시오.

연결 제한

연결 제한은 [호스트 컴퓨터의 연결 제한] 또는 [Azure SNAT(PAT) 포트 고갈] 중 하나로 인해 발생할 수 있습니다.

호스트 머신의 연결 제한

일부 Linux 시스템(예: 'Red Hat')에는 열려 있는 파일의 총 수에 상한이 있습니다. Linux의 소켓은 파일로 구현되므로 이 숫자는 총 연결 수도 제한합니다. 다음 명령을 실행합니다.

ulimit -a

"nofile"로 식별되는 허용되는 열린 파일의 최대 수는 연결 풀 크기의 두 배 이상이어야 합니다. 자세한 내용은 Azure Cosmos DB Python SDK 성능 팁을 참조하세요.

Azure SNAT(PAT) 포트 고갈

공용 IP 주소 없이 앱이 Azure Virtual Machines에 배포되는 경우 기본적으로 Azure SNAT 포트는 VM 외부의 모든 엔드포인트에 대한 연결을 설정하는 데 사용됩니다. VM에서 Azure Cosmos DB 엔드포인트로 허용되는 연결 수는 Azure SNAT 구성으로 제한됩니다.

Azure SNAT 포트는 VM에 개인 IP 주소 및 VM에서 공용 IP 주소에 연결하려고 하는 프로세스가 있는 경우에만 사용됩니다. Azure SNAT 제한을 피하는 두 가지 해결 방법이 있습니다.

• Azure Virtual Machines 가상 네트워크의 서브넷에 Azure Cosmos DB 서비스 엔드포인트를 추가합니다. 자세한 내용은 Azure Virtual Network 서비스 엔드포인트를 참조하세요.

  서비스 엔드포인트를 사용하도록 설정한 경우 요청이 더 이상 공용 IP에서 Azure Cosmos DB로 전송되지 않습니다. 대신 가상 네트워크 및 서브넷 ID가 전송됩니다. 공용 IP만 허용되는 경우 이 변경 내용으로 인해 방화벽이 삭제될 수 있습니다. 방화벽을 사용하는 경우 서비스 엔드포인트를 사용하도록 설정하면 Virtual Network ACL을 사용하여 방화벽에 서브넷을 추가합니다.

• Azure VM에 공용 IP를 할당합니다.

서비스에 연결할 수 없음 - 방화벽

azure.core.exceptions.ServiceRequestError:은 SDK가 서비스에 연결할 수 없음을 나타냅니다. 호스트 컴퓨터의 연결 제한을 따릅니다.

Azure Cosmos DB 에뮬레이터 연결 오류

Azure Cosmos DB 에뮬레이터 HTTPS 인증서는 자체 서명입니다. Python SDK를 에뮬레이터와 함께 사용하려면 에뮬레이터 인증서를 가져와야 합니다. 자세한 내용은 Azure Cosmos DB 에뮬레이터 인증서 내보내기를 참조하세요.

HTTP 프록시

HTTP 프록시를 사용하는 경우 SDK ConnectionPolicy에서 구성된 연결 수를 지원할 수 있는지 확인합니다. 그렇지 않으면 연결 문제가 발생할 수 있습니다.

일반적인 쿼리 문제

쿼리 메트릭은 쿼리가 가장 많은 시간을 소비 하는 위치를 확인 하는 데 도움이 됩니다. 쿼리 메트릭에서 클라이언트와 백엔드에서 얼마나 많이 사용되고 있는지 확인할 수 있습니다. 쿼리 성능 가이드에서 자세히 알아봅니다.

다음 단계

• Python SDK에 대한 성능 지침을 알아보세요.
• Python SDK의 모범 사례를 알아보세요