Connect to an app instance for troubleshooting

This article describes how to access the shell environment inside your application instances to do advanced troubleshooting.

Although Azure Spring Apps offers various managed troubleshooting approaches, you may want to do advanced troubleshooting using the shell environment. For example, you may want to accomplish the following troubleshooting tasks:

• Directly use Java Development Kit (JDK) tools.
• Diagnose against an app’s back-end services for network connection and API call latency for both virtual-network and non-virtual-network instances.
• Diagnose storage capacity, performance, and CPU/memory issues.

Prerequisites

• Azure CLI with the Azure Spring Apps extension. Use the following command to remove previous versions and install the latest extension. If you previously installed the spring-cloud extension, uninstall it to avoid configuration and version mismatches.

  az extension remove --name spring
  az extension add --name spring
  az extension remove --name spring-cloud
  

• A deployed application in Azure Spring Apps.

• If you've deployed a custom container, a shell program. The default is /bin/sh.

Assign an Azure role

Before connecting to an app instance, you must be granted the role Azure Spring Apps Connect Role. Connecting to an app instance requires the data action permission Microsoft.AppPlatform/Spring/apps/deployments/connect/action.

You can assign an Azure role using the Azure portal or Azure CLI.

az role assignment create \
    --role 'Azure Spring Apps Connect Role' \
    --scope '<service-instance-resource-id>' \
    --assignee '<your-identity>'

Connect to an app instance

You can connect to an app instance using the Azure portal or Azure CLI.

az spring app connect \
    --service <your-service-instance> \
    --resource-group <your-resource-group> \
    --name <app-name>

az spring app connect \
    --service <your-service-instance> \
    --resource-group <your-resource-group> \
    --name <app-name> \
    --instance <instance_name>

az spring app connect \
    --service <your-service-instance> \
    --resource-group <your-resource-group> \
    --name <app-name> \
    --deployment green

az spring app connect \
    --service <your-service-instance> \
    --resource-group <your-resource-group> \
    --name <app-name> \
    --shell-cmd /bin/bash

Troubleshoot your app instance

After you connect to an app instance, you can check the status of the heap memory.

Use the following command to find the Java process ID, which is usually 1:

jps

The output should look like the following example:

Then use the following command to run the JDK tool to check the result:

jstat -gc 1

The output should look like the following example:

Disconnect from your app instance

When you're done troubleshooting, use the exit command to disconnect from the app instance, or press Ctrl+d.

Troubleshooting tools

The following list describes some of the pre-installed tools that you can use for troubleshooting:

• lsof - Lists open files.
• top - Displays system summary information and current utilization.
• ps - Gets a snapshot of the running process.
• netstat - Prints network connections and interface statistics.
• nslookup - Queries internet name servers interactively.
• ping - Tests whether a network host can be reached.
• nc - Reads from and writes to network connections using TCP or UDP.
• wget - Lets you download files and interact with REST APIs.
• df - Displays the amount of available disk space.

You can also use JDK-bundled tools such as jps, jcmd, and jstat.

The following list shows the tools available, which depend on your service plan and type of app deployment:

• Source Code, JAR, and artifacts deployment:
  • Basic, Standard, and Standard Consumption & Dedicated Plan:
    • Common tools - Yes
    • JDK tools - Yes, for Java workloads only.
• Custom image deployment: Depends on the installed tool set in your image.

Limitations

Using the shell environment inside your application instances has the following limitations:

• Because the app is running as a non-root user, you can't execute some actions requiring root permission. For example, you can't install new tools by using the system package manager apt / yum.

• Because some Linux capabilities are prohibited, tools that require special privileges, such as tcpdump, don't work.