Troubleshoot common Azure Spring Apps issues

This article provides instructions for troubleshooting Azure Spring Apps development issues. For more information, see Azure Spring Apps FAQ.

Availability, performance, and application issues

My application can't start

When your application can't start, you might find that its endpoint can't be connected or it returns a 502 after a few retries.

For troubleshooting, export the logs to Azure Log Analytics. The table for Spring application logs is named AppPlatformLogsforSpring. To learn more, see Analyze logs and metrics with diagnostics settings.

The following error message might appear in your logs: org.springframework.context.ApplicationContextException: Unable to start web server

The message indicates one of two likely problems:

• One of the beans or one of its dependencies is missing.
• One of the bean properties is missing or invalid. In this case, "java.lang.IllegalArgumentException" is displayed.

Service bindings might also cause application start failures. To query the logs, use keywords that are related to the bound services. For instance, let's assume that your application has a binding to a MySQL instance that's set to local system time. If the application fails to start, the following error message might appear in the log:

"java.sql.SQLException: The server time zone value 'Coordinated Universal Time' is unrecognized or represents more than one time zone."

To fix this error, go to the server parameters of your MySQL instance, and change the time_zone value from SYSTEM to +0:00.

My application crashes or throws an unexpected error

When you're debugging application crashes, start by checking the running status and discovery status of the application. To do so, go to Apps in the Azure portal to ensure that the statuses of all the applications are Running and UP.

• If the status is Running but the discovery status isn't UP, go to the "My application can't be registered" section.

• If the discovery status is UP, go to Metrics to check the application's health. Inspect the following metrics:

  • tomcat.global.error:

    All Spring application exceptions are counted here. If this number is large, go to Azure Log Analytics to inspect your application logs.

  • jvm.memory.max:

    The maximum amount of memory available to the application. The amount might be undefined, or it might change over time if it's defined. If it's defined, the amount of used and committed memory is always less than or equal to max. However, a memory allocation might fail with an OutOfMemoryError message if the allocation attempts to increase the used memory such that used > committed, even if used <= max is still true. In such a situation, try to increase the maximum heap size by using the -Xmx parameter.

  • jvm.memory.used:

    The amount of memory in bytes that's currently used by the application. For a normal load Java application, this metric series forms a sawtooth pattern, where the memory usage steadily increases and decreases in small increments and suddenly drops a lot, and then the pattern recurs. This metric series occurs because of garbage collection inside Java virtual machine, where collection actions represent drops on the sawtooth pattern.

    This metric is important to help identify memory issues, such as:

    • A memory explosion at the very beginning.
    • The surge memory allocation for a specific logic path.
    • Gradual memory leaks.

  For more information, see Metrics.

  Note

  These metrics are available only for Spring Boot applications. To enable these metrics, add the spring-boot-starter-actuator dependency. For more information, see the Add actuator dependency section of Manage and monitor app with Spring Boot Actuator.

• If the application fails to start, verify that the application has valid jvm parameters. If jvm memory is set too high, the following error message might appear in your logs:

  "required memory 2728741K is greater than 2000M available for allocation"

To learn more about Azure Log Analytics, see Get started with Log Analytics in Azure Monitor.

My application experiences high CPU usage or high memory usage

If your application experiences high CPU or memory usage, one of two things is true:

• All the app instances experience high CPU or memory usage.
• Some of the app instances experience high CPU or memory usage.

To ascertain which situation applies, use the following steps:

1. Go to Metrics, and then select either Service CPU Usage Percentage or Service Memory Used.
2. Add an App= filter to specify which application you want to monitor.
3. Split the metrics by Instance.

If all instances are experiencing high CPU or memory usage, you need to either scale out the application or scale up the CPU or memory usage. For more information, see Tutorial: Scale an application in Azure Spring Apps.

If some instances are experiencing high CPU or memory usage, check the instance status and its discovery status.

For more information, see Metrics for Azure Spring Apps.

If all instances are up and running, go to Azure Log Analytics to query your application logs and review your code logic. This review helps you see whether any of them might affect scale partitioning. For more information, see Analyze logs and metrics with diagnostics settings.

To learn more about Azure Log Analytics, see Get started with Log Analytics in Azure Monitor. Query the logs by using the Kusto query language.

Checklist for deploying your Spring application to Azure Spring Apps

Before you onboard your application, ensure that it meets the following criteria:

• The application can run locally with the specified Java runtime version.
• The environment config (CPU/RAM/Instances) meets the minimum requirement set by the application provider.
• The configuration items have their expected values. For more information, see Set up a Spring Cloud Config Server instance for your service.
• The environment variables have their expected values.
• The JVM parameters have their expected values.
• We recommended that you disable or remove the embedded Config Server and Spring Service Registry services from the application package.
• If any Azure resources are to be bound via Service Binding, make sure the target resources are up and running.

Configuration and management

I encountered a problem with creating an Azure Spring Apps service instance

When you set up an Azure Spring Apps service instance by using the Azure portal, Azure Spring Apps performs the validation for you.

But if you try to set up the Azure Spring Apps service instance by using the Azure CLI or the Azure Resource Manager template, verify that you meet the following conditions:

• The subscription is active.
• Azure Spring Apps is available in the region you're using. For more information, see the Azure Spring Apps FAQ.
• The resource group for the instance is already created.
• The resource name conforms to the naming rule. The name must contain only lowercase letters, numbers, and hyphens. The first character must be a letter. The last character must be a letter or number. The value must contain from 2 to 32 characters.

If you want to set up the Azure Spring Apps service instance by using the Resource Manager template, first refer to Understand the structure and syntax of Azure Resource Manager templates.

The name of the Azure Spring Apps service instance is used for requesting a subdomain name under microservices.azure.cn, so the setup fails if the name conflicts with an existing one. You might find more details in the activity logs.

I can't deploy a JAR package

You can't upload Java Archive file (JAR)/source package by using the Azure portal or the Resource Manager template.

When you deploy your application package by using the Azure CLI, the Azure CLI periodically polls the deployment progress and, in the end, it displays the deployment result.

If the polling is interrupted, you can still use the following command to fetch the deployment logs:

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

Ensure that your application is packaged in the correct executable JAR format. If it isn't packaged correctly, you receive an error message similar to the following example: Error: Invalid or corrupt jarfile /jar/11111111-1111-1111-1111-111111111111.

I can't deploy a source package

You can't upload JAR/source package by using the Azure portal or the Resource Manager template.

When you deploy your application package by using the Azure CLI, the Azure CLI periodically polls the deployment progress and, in the end, it displays the deployment result.

If the polling is interrupted, you can still use the following command to fetch the build and deployment logs:

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

However, one Azure Spring Apps service instance can trigger only one build job for one source package at one time. For more information, see Deploy an application and Set up a staging environment in Azure Spring Apps.

My application can't be registered

In most cases, this situation occurs when Required Dependencies and Service Discovery aren't properly configured in your Project Object Model (POM) file. Once it's configured, the built-in Service Registry server endpoint is injected as an environment variable with your application. Applications then register themselves with the Service Registry server and discover other dependent applications.

Wait at least two minutes before a newly registered instance starts receiving traffic.

If you're migrating an existing Spring Cloud-based solution to Azure, be sure to remove or disable your ad-hoc Service Registry and Config Server instances to avoid conflicting with the managed instances provided by Azure Spring Apps.

You can also check the Service Registry client logs in Azure Log Analytics. For more information, see Analyze logs and metrics with diagnostics settings

To learn more about Azure Log Analytics, see Get started with Log Analytics in Azure Monitor. Query the logs by using the Kusto query language.

I want to inspect my application's environment variables

Environment variables inform the Azure Spring Apps framework, ensuring that Azure understands where and how to configure the services that make up your application. Ensuring that your environment variables are correct is a necessary first step in troubleshooting potential problems. You can use the Spring Boot Actuator endpoint to review your environment variables.

1. Go to https://<your-application-test-endpoint>/actuator/health.

   A response similar to {"status":"UP"} indicates that the endpoint has been enabled. If the response is negative, include the following dependency in your POM.xml file:

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

2. With the Spring Boot Actuator endpoint enabled, go to the Azure portal and look for the configuration page of your application. Add an environment variable with the name MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE and the value *.

3. Restart your application.

4. Go to https://<your-application-test-endpoint>/actuator/env and inspect the response. It should look like this:

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

Look for the child node named systemEnvironment. This node contains your application's environment variables.

I can't find metrics or logs for my application

Go to Apps to ensure that the application statuses are Running and UP.

Check to see whether JMX is enabled in your application package. This feature can be enabled with the configuration property spring.jmx.enabled=true.

Check to see whether the spring-boot-actuator dependency is enabled in your application package and that it successfully boots up.

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

If your application logs can be archived to a storage account but not sent to Azure Log Analytics, check to see whether you set up your workspace correctly. For more information, see Create a Log Analytics workspace. Also, be aware that the Basic plan doesn't provide a service-level agreement (SLA). For more information, see Service Level Agreements (SLA) for Online Services.

Next steps

• Troubleshoot common exit code issues in Azure Spring Apps