일반적인 Azure Spring Apps 문제 해결

아티클
04/23/2024

참고 항목

기본, 표준 및 엔터프라이즈 계획은 2025년 3월 중순부터 사용되지 않으며 3년의 은퇴 기간이 있습니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 사용 중지 공지 사항을 참조하세요.

표준 소비 및 전용 계획은 2024년 9월 30일부터 사용되지 않으며 6개월 후에 완전히 종료됩니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 표준 사용량 및 전용 계획을 Azure Container Apps로 마이그레이션을 참조 하세요.

이 문서의 적용 대상: ✔️ 기본/표준 ✔️ 엔터프라이즈

이 문서에서는 Azure Spring Apps 개발 문제를 해결하기 위한 지침을 제공합니다. 자세한 내용은 Azure Spring 앱 FAQ를 참조하세요.

가용성, 성능 및 애플리케이션 문제

내 애플리케이션을 시작할 수 없습니다.

애플리케이션을 시작할 수 없는 경우 해당 엔드포인트를 연결할 수 없거나 몇 번 재시도 후 502를 반환할 수 있습니다.

문제 해결을 위해 로그를 Azure Log Analytics로 내보냅니다. Spring 애플리케이션 로그에 대한 테이블 이름은 AppPlatformLogsforSpring입니다. 자세히 알아보려면 진단 설정을 사용하여 로그 및 메트릭 분석을 참조하세요.

로그에 다음과 같은 오류 메시지가 나타날 수 있습니다. org.springframework.context.ApplicationContextException: Unable to start web server

이 메시지는 다음과 같은 두 가지 문제 중 하나를 나타냅니다.

빈 중 하나 또는 해당 종속성 중 하나가 누락되었습니다.
빈 속성 중 하나가 누락되거나 잘못되었습니다. 이 경우 "java.lang.IllegalArgumentException"이 표시됩니다.

또한 서비스 바인딩으로 인해 애플리케이션 시작 오류가 발생할 수도 있습니다. 로그를 쿼리하려면 바인딩된 서비스와 관련된 키워드를 사용합니다. 예를 들어, 애플리케이션에 로컬 시스템 시간으로 설정된 MySQL 인스턴스에 대한 바인딩이 있다고 가정합니다. 애플리케이션이 시작되지 않으면 로그에서 다음 오류가 표시될 수 있습니다.

"java.sql.SQLException: 서버 표준 시간대 값 '협정 세계시'를 인식할 수 없거나 둘 이상의 표준 시간대를 나타냅니다."

이 오류를 해결하려면 MySQL 인스턴스의 server parameters로 이동하여 시스템에서 time_zone 값을 +0:00으로 변경합니다.

애플리케이션이 충돌하거나 예기치 않은 오류를 throw함

애플리케이션 충돌이 디버그되면 먼저 애플리케이션의 실행 상태와 검색 상태를 확인하여 시작합니다. 이렇게 하려면 Azure Portal에서 앱으로 이동하여 모든 애플리케이션의 상태가 Running 및 UP인지 확인합니다.

상태가 Running이지만 검색 상태는 UP이 아닌 경우 "애플리케이션을 등록할 수 없음" 섹션으로 이동합니다.
검색 상태가 UP인 경우 메트릭으로 이동하여 애플리케이션의 상태를 확인합니다. 다음 메트릭을 검사합니다.
- tomcat.global.error:
  
  모든 Spring 애플리케이션 예외는 여기에서 계산됩니다. 이 수가 크면 Azure Log Analytics로 이동하여 애플리케이션 로그를 검사합니다.
- jvm.memory.max:
  
  애플리케이션에서 사용할 수 있는 최대 메모리 양입니다. 양은 정의되지 않을 수 있으며 정의된 경우에는 시간이 지남에 따라 변경될 수 있습니다. 정의된 경우 사용 및 커밋된 메모리의 양은 항상 최댓값보다 작거나 같습니다. 그러나 used <= max인 경우에도 used > committed와 같이 할당이 사용된 메모리를 늘리려고 하면 OutOfMemoryError 메시지와 함께 메모리 할당이 실패할 수 있습니다. 이러한 상황에서 -Xmx 매개 변수를 사용하여 최대 힙 크기를 늘려봅니다.
- jvm.memory.used:
  
  애플리케이션에서 현재 사용하고 있는 메모리의 양(바이트). 정상적인 Java 애플리케이션 로드의 경우 이 메트릭 계열은 톱니 패턴으로 구성됩니다. 메모리 사용이 꾸준히 증가하고 조금씩 감소하다가 급격하게 떨어지는 패턴이 반복됩니다. 이 메트릭 계열은 Java 가상 머신 내부의 가비지 수집 때문이며, 수집 작업에서 톱니 패턴의 하강을 나타냅니다.
  
  이 메트릭은 다음과 같은 메모리 문제를 식별하는 데 중요합니다.
  - 처음에 메모리 급증이 있습니다.
  - 특정 논리 경로에 대해 불안정한 메모리 할당.
  - 점진적인 메모리 누수.
자세한 내용은 메트릭을 참조하세요.

참고 항목

이러한 메트릭은 Spring Boot 애플리케이션에만 사용할 수 있습니다. 이러한 메트릭을 사용하도록 설정하려면 spring-boot-starter-actuator 종속성을 추가합니다. 자세한 내용은 Spring Boot Actuator를 사용하여 앱 관리 및 모니터링의 actuator 종속성 추가 섹션을 참조하세요.
애플리케이션이 시작되지 않으면 애플리케이션에 유효한 jvm 매개 변수가 있는지 확인합니다. jvm 메모리가 너무 높게 설정된 경우 로그에 다음과 같은 오류 메시지가 나타날 수 있습니다.

"필수 메모리 2728741K는 할당에 사용할 수 있는 2000M보다 큽니다."

Azure Log Analytics에 대한 자세한 내용은 Azure Monitor에서 Log Analytics 시작을 참조하세요.

애플리케이션에서 높은 CPU 사용 또는 높은 메모리 사용 경험

애플리케이션에서 높은 CPU/메모리 사용량이 발생하는 경우 다음 두 가지 상황 중 하나에 해당합니다.

모든 앱 인스턴스에서 높은 CPU/메모리 사용량이 발생합니다.
일부 앱 인스턴스에서 높은 CPU/메모리 사용량이 발생합니다.

적용되는 상황을 확인하려면 다음 단계를 사용합니다.

메트릭으로 이동한 다음 서비스 CPU 사용량 비율 또는 사용되는 서비스 메모리를 선택합니다.
App= 필터를 추가하여 모니터링할 애플리케이션을 지정합니다.
메트릭을 인스턴스로 분할합니다.

모든 인스턴스에서 높은 CPU/메모리 사용량이 발생하는 경우 애플리케이션을 확장하거나 CPU/메모리 사용량을 확대해야 합니다. 자세한 내용은 자습서: Azure Spring Apps에서 애플리케이션 비율 크기 조정을 참조하세요.

일부 인스턴스에서 높은 CPU/메모리 사용량이 발생하는 경우 인스턴스 상태 및 해당 검색 상태를 확인합니다.

자세한 내용은 Azure Spring Apps의 메트릭을 참조하세요.

모든 인스턴스가 실행 중인 경우 Azure Log Analytics로 이동하여 애플리케이션 로그를 쿼리하고 코드 논리를 검토합니다. 이 검토를 통해 크기 조정 분할에 영향을 줄 수 있는지 여부를 확인할 수 있습니다. 자세한 내용은 진단 설정을 사용하여 로그 및 메트릭 분석을 참조하세요.

Azure Log Analytics에 대한 자세한 내용은 Azure Monitor에서 Log Analytics 시작을 참조하세요. Kusto 쿼리 언어를 사용하여 로그를 쿼리합니다.

Spring 애플리케이션을 Azure Spring Apps에 배포하기 위한 검사 목록

애플리케이션을 온보드하기 전에 다음 조건을 충족하는지 확인합니다.

지정된 Java 런타임 버전을 사용하여 애플리케이션을 로컬로 실행할 수 있습니다.
환경 구성(CPU/RAM/인스턴스)에서 애플리케이션 공급자가 설정한 최소 요구 사항을 충족합니다.
구성 항목에 해당 예상 값이 있습니다. 자세한 내용은 서비스에 대한 Spring Cloud Config Server 인스턴스 설정을 참조하세요. Enterprise 플랜의 경우 애플리케이션 구성 서비스 사용을 참조하세요.
환경 변수에 해당 예상 값이 있습니다.
JVM 매개 변수에 해당 예상 값이 있습니다.
애플리케이션 패키지에서 포함된 Config Server 및 Spring 서비스 레지스트리 서비스를 사용하지 않도록 설정하거나 제거하는 것이 좋습니다.
Azure 리소스가 서비스 바인딩을 통해 바인딩될 경우 대상 리소스가 실행 중인지 확인합니다.

구성 및 관리

Azure Spring Apps 서비스 인스턴스를 만드는 데 문제가 발생했습니다.

Azure Portal을 사용하여 Azure Spring Apps 서비스 인스턴스를 설정하면 Azure Spring Apps에서 유효성 검사를 수행합니다.

하지만 Azure CLI 또는 Azure Resource Manager 템플릿을 사용하여 Azure Spring Apps 서비스 인스턴스를 설정하려는 경우 다음 조건을 충족하는지 확인합니다.

구독이 활성 상태입니다.
Azure Spring Apps는 사용 중인 지역에서 사용할 수 있습니다. 자세한 내용은 Azure Spring Apps FAQ를 참조하세요.
인스턴스에 대한 리소스 그룹이 이미 만들어졌습니다.
리소스 이름이 명명 규칙을 준수합니다. 이름은 소문자, 숫자 및 하이픈만 포함해야 합니다. 첫 글자는 문자여야 합니다. 마지막 글자는 문자 또는 숫자여야 합니다. 값은 2~32자를 포함해야 합니다.

Resource Manager 템플릿을 사용하여 Azure Spring Apps 서비스 인스턴스를 설정하려는 경우 먼저 Azure Resource Manager 템플릿의 구조 및 구문 이해를 참조하세요.

Azure Spring Apps 서비스 인스턴스의 이름은 azuremicroservices.io 아래의 하위 도메인 이름을 요청하는 데 사용되므로 이름이 기존 이름과 충돌하면 설정에 실패합니다. 활동 로그에서 추가 정보를 확인할 수 있습니다.

.NET Core 앱을 배포할 수 없음

Azure Portal 또는 Resource Manager 템플릿을 사용하여 .NET Core Steeltoe 앱에 대한 .zip 파일을 업로드할 수 없습니다.

Azure CLI을 사용하여 애플리케이션 패키지를 배포할 때 Azure CLI가 배포 진행률을 주기적으로 진행률을 조사하고 마지막에는 배포 결과를 표시합니다.

애플리케이션이 올바른 .zip 파일 형식으로 패키지되어 있는지 확인합니다. 올바르게 패키지되지 않은 경우 프로세스가 응답하지 않거나 오류 메시지가 표시됩니다.

JAR 패키지를 배포할 수 없음

Azure Portal 또는 Resource Manager 템플릿을 사용하여 Java 아카이브 파일(JAR)/원본 패키지를 업로드할 수 없습니다.

Azure CLI을 사용하여 애플리케이션 패키지를 배포할 때 Azure CLI가 배포 진행률을 주기적으로 진행률을 조사하고 마지막에는 배포 결과를 표시합니다.

폴링이 중단된 경우에도 다음 명령을 사용하여 배포 로그를 계속 가져올 수 있습니다.

az spring app show-deploy-log --name <app-name>

애플리케이션이 올바른 실행 가능한 JAR 형식으로 패키지되어 있는지 확인합니다. 올바르게 패키지되어 있지 않은 경우 Error: Invalid or corrupt jarfile /jar/11111111-1111-1111-1111-111111111111 예제와 유사한 오류 메시지가 표시됩니다.

원본 패키지를 배포할 수 없음

Azure Portal 또는 Resource Manager 템플릿을 사용하여 JAR/원본 패키지를 업로드할 수 없습니다.

Azure CLI을 사용하여 애플리케이션 패키지를 배포할 때 Azure CLI가 배포 진행률을 주기적으로 진행률을 조사하고 마지막에는 배포 결과를 표시합니다.

폴링이 중단된 경우에도 다음 명령을 사용하여 빌드 및 배포 로그를 계속 가져올 수 있습니다.

az spring app show-deploy-log --name <app-name>

하지만 하나의 Azure Spring Apps 서비스 인스턴스는 한 번에 하나의 원본 패키지에 대해 하나의 빌드 작업만 트리거할 수 있습니다. 자세한 내용은 애플리케이션 배포 및 Azure Spring Apps에서 스테이징 환경 설정을 참조하세요.

애플리케이션을 등록할 수 없음

대부분의 경우 이 문제는 필요한 종속성 및 서비스 검색이 POM(프로젝트 개체 모델) 파일에 제대로 구성되지 않은 경우 발생합니다. 구성된 후에는 기본 제공 서비스 레지스트리 서버 엔드포인트가 애플리케이션에서 환경 변수로 삽입됩니다. 그런 다음 애플리케이션은 Service Registry 서버에 자신을 등록하고 다른 종속 애플리케이션을 검색합니다.

새로 등록된 인스턴스가 트래픽을 받기 시작할 때까지 2분 이상 기다립니다.

기존의 Spring Cloud 기반 솔루션을 Azure로 마이그레이션하는 경우 Azure Spring Apps를 통해 제공되는 관리되는 인스턴스와의 충돌을 방지하려면 임시 서비스 레지스트리 및 ‘Config Server’ 인스턴스를 제거하거나 사용하지 않도록 설정해야 합니다.

Azure Log Analytics에서 서비스 레지스트리 클라이언트 로그도 확인합니다. 자세한 내용은 진단 설정을 사용하여 로그 및 메트릭 분석 참조

Azure Log Analytics에 대한 자세한 내용은 Azure Monitor에서 Log Analytics 시작을 참조하세요. Kusto 쿼리 언어를 사용하여 로그를 쿼리합니다.

내 애플리케이션의 환경 변수를 검사하려고 합니다.

환경 변수는 Azure에서 애플리케이션을 형성하는 서비스를 구성하는 위치와 방법을 이해할 수 있도록 Azure Spring Apps 프레임워크에 정보를 알려 줍니다. 환경 변수가 올바른지 확인하는 것은 잠재적인 문제 해결에 필수적인 첫 번째 단계입니다. Spring Boot Actuator 엔드포인트를 사용하여 환경 변수를 검토할 수 있습니다.

Warning

이 프로시저는 테스트 엔드포인트를 사용하여 환경 변수를 노출합니다. 테스트 엔드포인트에 공개적으로 액세스할 수 있거나 애플리케이션에 도메인 이름을 할당한 경우에는 더이상 진행하지 마십시오.

https://<your-application-test-endpoint>/actuator/health(으)로 이동합니다.

{"status":"UP"}과 유사한 응답은 엔드포인트가 사용하도록 설정되었음을 나타냅니다. 응답이 부정이면 POM.xml 파일에 다음 종속성을 포함합니다.
```
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```
Spring Boot Actuator 엔드포인트가 사용하도록 설정된 상태에서 Azure Portal로 이동하여 애플리케이션의 구성 페이지를 찾습니다. 이름이 MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE이고 값이 *인 환경 변수를 추가합니다.
애플리케이션을 다시 시작합니다.

https://<your-application-test-endpoint>/actuator/env로 이동하여 응답을 검사합니다. 다음과 같이 표시됩니다.

{
    "activeProfiles": [],
    "propertySources": {,
        "name": "server.ports",
        "properties": {
            "local.server.port": {
                "value": 1025
            }
        }
    }
}

systemEnvironment라는 자식 노드를 찾습니다. 이 노드에는 애플리케이션의 환경 변수가 포함됩니다.

Important

애플리케이션에 대한 공용 액세스를 가능하게 하려면 환경 변수의 노출을 역방향으로 바꾸어야 합니다. Azure Portal로 이동하여 애플리케이션의 구성 페이지를 찾은 후, 환경 변수 MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE를 삭제합니다.

애플리케이션에 대한 메트릭 또는 로그를 찾을 수 없음

앱으로 이동하여 애플리케이션 상태가 Running 및 UP인지 확인합니다.

애플리케이션 패키지에서 JMX를 사용하도록 설정되어 있는지 확인합니다. 이 기능은 구성 속성 spring.jmx.enabled=true를 사용하여 설정할 수 있습니다.

애플리케이션 패키지에서 spring-boot-actuator 종속성을 사용하도록 설정하고 성공적으로 부팅되었는지 확인합니다.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

애플리케이션 로그를 스토리지 계정에 보관할 수 있지만 Azure Log Analytics에 보내지 않은 경우 작업 영역을 올바르게 설정했는지 확인합니다. 자세한 내용은 Log Analytics 작업 영역 만들기를 참조하세요. 또한 기본 플랜은 SLA(서비스 수준 계약)를 제공하지 않습니다. 자세한 내용은 온라인 서비스에 대한 SLA(서비스 수준 계약)를 참조하세요.

엔터프라이즈 계획

오류 112039: Azure Marketplace에서 구매하지 못했습니다.

Azure Spring Apps Enterprise 플랜 인스턴스 만들기가 오류 코드 "112039"로 인해 실패합니다. 자세한 내용은 다음 목록에서 자세한 오류 메시지를 확인하세요.

"Microsoft.SaaS RP가 Azure 구독에 등록되지 않았기 때문에 Azure Marketplace에서 구매하지 못했습니다.": Azure Spring Apps Enterprise 플랜은 VMware에서 SaaS 제품을 구매합니다.

Azure Spring Apps Enterprise 인스턴스를 만들기 전에 Microsoft.SaaS 리소스 공급자를 등록해야 합니다. 리소스 공급자 등록 방법을 참조하세요.
"Azure 구독 시장에서 카탈로그 제품 vmware-inc.azure-spring-cloud-vmware-tanzu-2를 로드하지 못했습니다.": Azure 구독의 청구 계정 주소가 지원되는 위치에 없습니다.

자세한 내용은 '<위치>' 시장에 사용할 수 있는 계획이 없음 섹션을 참조하세요.
"Marketplace 법적 계약의 서명 확인으로 인해 Azure Marketplace에서 구매하지 못했습니다. Azure 구독이 vmware-inc.azure-spring-cloud-vmware-tanzu-2.asa-ent-hr-mtr에 동의했는지 확인합니다.: Azure 구독이 구입할 제품 및 플랜에 대한 약관에 동의하지 않았습니다.

Azure 구독으로 이동하고 다음 Azure CLI 명령을 실행하여 약관에 동의합니다.
```
az term accept \
    --publisher vmware-inc \
    --product azure-spring-cloud-vmware-tanzu-2 \
    --plan asa-ent-hr-mtr
```
그래도 문제가 해결되지 않으면 다음 정보로 지원 팀에 문의할 수 있습니다.
- AZURE_TENANT_ID: Azure 구독을 호스팅하는 Azure 테넌트 ID
- AZURE_SUBSCRIPTION_ID: Azure Spring Apps 인스턴스를 만드는 데 사용되는 Azure 구독 ID
- SPRING_CLOUD_NAME: 실패한 인스턴스 이름
- ERROR_MESSAGE: 관찰된 오류 메시지

'<위치>' 시장에 사용할 수 있는 계획이 없음

Azure Marketplace의 SaaS 제안 Azure Spring Apps Enterprise를 방문하면 다음 이미지와 같이 "시장 '<위치>'에 사용할 수 있는 계획이 없습니다."라는 메시지가 표시될 수 있습니다.

Azure Spring Apps Enterprise 플랜은 고객이 Azure Marketplace 제안을 통해 Tanzu 구성 요소에 대한 라이선스 비용을 지불해야 합니다. Azure Marketplace에서 구매하려면 Azure 구독에 대한 청구 계정의 국가 또는 지역이 SaaS 제품의 지원되는 지리적 위치에 있어야 합니다.

Azure Spring Apps Enterprise는 이제 Azure Marketplace가 지원하는 모든 지리적 위치를 지원합니다. 상업용 Marketplace에 대한 지리적 가용성 및 통화 지원의 지원되는 지리적 위치 섹션을 참조하세요.

관리자 액세스 권한이 있는 경우 구독에 대한 청구 계정을 볼 수 있습니다. 청구 계정 보기를 참조하세요.

VMware Spring Runtime 지원이 필요합니다(Enterprise 플랜만 해당).

Enterprise 플랜에는 VMware Spring Runtime 지원이 기본 제공되어 있으므로 문제가 VMware Spring Runtime 지원 범위에 있다고 생각되면 VMware에 대한 지원 티켓을 열 수 있습니다. VMware Spring Runtime 지원 자체를 더 잘 이해하려면 VMware Spring Runtime을 참조하세요. 이 지원 서비스 등록 및 사용에 대한 자세한 내용은 VMware의 엔터프라이즈 FAQ에서 지원 섹션을 참조하세요. 다른 문제가 있으면 Microsoft에 지원 티켓을 엽니다.

다음을 통해 공유

일반적인 Azure Spring Apps 문제 해결

가용성, 성능 및 애플리케이션 문제

내 애플리케이션을 시작할 수 없습니다.

애플리케이션이 충돌하거나 예기치 않은 오류를 throw함

애플리케이션에서 높은 CPU 사용 또는 높은 메모리 사용 경험

Spring 애플리케이션을 Azure Spring Apps에 배포하기 위한 검사 목록

구성 및 관리

Azure Spring Apps 서비스 인스턴스를 만드는 데 문제가 발생했습니다.

.NET Core 앱을 배포할 수 없음

JAR 패키지를 배포할 수 없음

원본 패키지를 배포할 수 없음

애플리케이션을 등록할 수 없음

내 애플리케이션의 환경 변수를 검사하려고 합니다.

애플리케이션에 대한 메트릭 또는 로그를 찾을 수 없음

엔터프라이즈 계획

오류 112039: Azure Marketplace에서 구매하지 못했습니다.

'<위치>' 시장에 사용할 수 있는 계획이 없음

VMware Spring Runtime 지원이 필요합니다(Enterprise 플랜만 해당).

다음 단계

피드백

추가 리소스