Use the diagnostic settings of JVM options for advanced troubleshooting in Azure Spring Apps

Article
11/19/2024

Note

The Basic, Standard, and Enterprise plans will be deprecated starting from mid-March, 2025, with a 3 year retirement period. We recommend transitioning to Azure Container Apps. For more information, see the Azure Spring Apps retirement announcement.

The Standard consumption and dedicated plan will be deprecated starting September 30, 2024, with a complete shutdown after six months. We recommend transitioning to Azure Container Apps. For more information, see Migrate Azure Spring Apps Standard consumption and dedicated plan to Azure Container Apps.

This article applies to: ✅ Java ❎ C#

This article applies to: ✅ Basic/Standard ✅ Enterprise

This article shows you how to use diagnostic settings through JVM options to conduct advanced troubleshooting in Azure Spring Apps.

There are several JVM-based application startup parameters related to heap dump, Java Flight Recorder (JFR), and garbage collection (GC) logs. In Azure Spring Apps, we support JVM configuration using JVM options.

For more information on configuring JVM-based application startup parameters, see az spring app deployment in the Azure CLI reference documentation. The following sections provide several examples of useful values for the --jvm-options parameter.

Prerequisites

A deployed Azure Spring Apps service instance. Follow our quickstart on deploying an app via the Azure CLI to get started.
At least one application already created in your service instance.
Your own persistent storage as described in How to enable your own persistent storage in Azure Spring Apps. This storage is used to save generated diagnostic files. The paths you provide in the parameter values below should be under the mount path of the persistent storage bound to your app. If you want to use a path under the mount path, be sure to create the subpath beforehand.

Generate a heap dump when out of memory

Use the following --jvm-options parameter to generate a heap dump when you encounter an out-of-memory error.

--jvm-options="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=<path-to-heap-dump-folder>"

As alternative to specifying the path to the heap dump folder, you can provide a specific file name. However, we highly recommend that you provide a folder path instead. If you provide a file name, the command will generate a heap dump for the first out-of-memory error only, due to the limitations of the HPROF file format. If you provide a folder path, you'll get a heap dump in a file with an autogenerated name for each out-of-memory error.

Generate GC logs

Use the following --jvm-options parameter to generate GC logs. For more information, see the official JVM documentation.

--jvm-options="-XX:+PrintGCDetails -Xloggc:<path-to-GC-log-file>"

Generate a JFR file on exit

Use the following --jvm-options parameter to generate a JFR file. For more information, see the official JVM documentation.

--jvm-options="-XX:StartFlightRecording=dumponexit=true,filename=<path-to-JFR-file>"

Configure the path for generated files

To ensure that you can access your files, be sure that the target path of your generated file is in the persistent storage bound to your app. For example, you can use JSON similar to the following example when you create your persistent storage in Azure Spring Apps.

    {
       "customPersistentDisks": [
          {
              "storageName": "<storage-resource-name>",
              "customPersistentDiskProperties": {
                  "type": "AzureFileVolume",
                  "shareName": "<azure-file-share-name>",
                  "mountPath": "<unique-mount-path>",
                  "mountOptions": [
                      "uid=0",
                      "gid=0"
                   ],
                   "readOnly": false
                }
          },
          {
              "storageName": "<storage-resource-name>",
              "customPersistentDiskProperties": {
                  "type": "AzureFileVolume",
                  "shareName": "<azure-file-share-name>",
                  "mountPath": "<unique-mount-path>",
                  "readOnly": true
              }
          }
       ]
    }

Alternatively, you can use the following command to append to persistent storage.

az spring app append-persistent-storage \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --persistent-storage-type AzureFileVolume \
    --storage-name <storage-resource-name> \
    --share-name <azure-file-share-name> \
    --mount-path <unique-mount-path>

Next steps

Capture heap dump and thread dump manually and use Java Flight Recorder in Azure Spring Apps

Share via