Stream Azure Spring Apps job logs in real time (Preview)

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.

This article describes how to use the Azure CLI to get real-time logs of jobs for troubleshooting. You can also use diagnostics settings to analyze diagnostics data in Azure Spring Apps. For more information, see Analyze logs and metrics with diagnostics settings. For more information on streaming logs, see Stream Azure Spring Apps application console logs in real time .

Prerequisites

  • Azure CLI with the Azure Spring Apps extension, version 1.24.0 or higher. You can install the extension by using the following command: az extension add --name spring.

Assign an Azure role

To stream logs of jobs, you must have the relevant Azure roles assigned to you. The following table lists the required role and the operations for which this role is granted permission:

Required role Operations
Azure Spring Apps Job Log Reader Role Microsoft.AppPlatform/Spring/jobs/executions/logstream/action
Microsoft.AppPlatform/Spring/jobs/executions/listInstances/action

Use the following steps to assign an Azure role using the Azure portal:

  1. Open the Azure portal.

  2. Open your Azure Spring Apps service instance.

  3. In the navigation pane, select Access Control (IAM).

  4. On the Access Control (IAM) page, select Add, and then select Add role assignment.

    Screenshot of the Azure portal that shows the Access Control (IAM) page with the Add role assignment option highlighted.

  5. On the Add role assignment page, in the Name list, search for and select the target role, and then select Next.

    Screenshot of the Azure portal that shows the Add role assignment page with the Azure Spring Apps Job Log Reader Role name highlighted.

  6. Select Members and then search for and select your username.

  7. Select Review + assign.

View tail logs

This section provides examples of using the Azure CLI to produce tail logs.

View tail logs for a specific instance

Every time a job is triggered, a new job execution is created. Also, depending on the parallelism setting for your job, several replicas or instances execute in parallel.

Use the following command to list all instances in a job execution:

az spring job execution instance list \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --job <job-name> \
    --execution <job-execution-name>

You can get all instance names of the job execution from the output.

To view the tail logs for a specific instance, use the az spring job logs command with the -i/--instance argument, as shown in the following example:

az spring job logs \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <job-name> \
    --execution <job-execution-name> \
    --instance <instance-name>

View tail logs for all instances in one command

To view the tail logs for all instances, use the --all-instances argument, as shown in the following example. The instance name is the prefix of each log line. When there are multiple instances, logs are printed in batch for each instance. This way logs of one instance aren't interleaved with the logs of another instance.

az spring job logs \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <job-name> \
    --execution <job-execution-name> \
    --all-instances

Stream new logs continuously

By default, az spring job logs prints only existing logs streamed to the console and then exits. If you want to stream new logs, add the -f/--follow argument.

When you use the -f/--follow option to tail instant logs, the Azure Spring Apps log streaming service sends heartbeat logs to the client every minute unless the job is writing logs constantly. Heartbeat log messages use the following format: 2023-12-18 09:12:17.745: No log from server.

Stream logs for a specific instance

Use the following commands to get instance names and stream logs for a specific instance:

az spring job execution instance list \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --job <job-name> \
    --execution <job-execution-name>

az spring job logs \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <job-name> \
    --execution <job-execution-name> \
    --instance <instance-name> \
    --follow

Stream logs for all instances

Use the following command to stream logs for all instances:

az spring job logs \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <job-name> \
    --execution <job-execution-name> \
    --all-instances \
    --follow

When you stream logs for multiple instances in a job execution, the logs of one instance interleave with the logs of others.

Stream logs in a virtual network injection instance

For an Azure Spring Apps instance deployed in a custom virtual network, you can access log streaming by default from a private network. For more information, see Deploy Azure Spring Apps in a virtual network

Azure Spring Apps also enables you to access real-time job logs from a public network.

Note

Enabling the log streaming endpoint on the public network adds a public inbound IP to your virtual network. Be sure to use caution if this is a concern for you.

Use the following steps to enable a log streaming endpoint on the public network:

  1. Select the Azure Spring Apps service instance deployed in your virtual network and then select Networking in the navigation pane.

  2. Select the Vnet injection tab.

  3. Switch the status of Dataplane resources on public network to Enable to enable a log streaming endpoint on the public network. This process takes a few minutes.

    Screenshot of the Azure portal that shows the Networking page with the Vnet injection tab selected and the Troubleshooting section highlighted.

After you enable the log stream public endpoint, you can access the job logs from a public network just like you would access a normal instance.

Secure traffic to the log streaming public endpoint

Log streaming for jobs uses Azure RBAC to authenticate the connections to the jobs. As a result, only users who have the proper roles can access the logs.

To ensure the security of your jobs when you expose a public endpoint for them, secure the endpoint by filtering network traffic to your service with a network security group. For more information, see Tutorial: Filter network traffic with a network security group using the Azure portal. A network security group contains security rules that allow or deny inbound network traffic to, or outbound network traffic from, several types of Azure resources. For each rule, you can specify source and destination, port, and protocol.

Note

If you can't access job logs in the virtual network injection instance from the internet after you enable a log stream public endpoint, check your network security group to see whether you've allowed such inbound traffic.

The following table shows an example of a basic rule that we recommend. You can use commands like nslookup with the endpoint <service-name>.private.microservices.azure.cn to get the target IP address of a service.

Priority Name Port Protocol Source Destination Action
100 Rule name 80 TCP Internet Service IP address Allow
110 Rule name 443 TCP Internet Service IP address Allow

Next steps