Monitor App Service instances using Health check

This article uses Health check in the Azure portal to monitor App Service instances. Health check increases your application's availability by re-routing requests away from unhealthy instances, and replacing instances if they remain unhealthy. Your App Service plan should be scaled to two or more instances to fully utilize Health check. The Health check path should check critical components of your application. For example, if your application depends on a database and a messaging system, the Health check endpoint should connect to those components. If the application cannot connect to a critical component, then the path should return a 500-level response code to indicate the app is unhealthy.

Health check failure

What App Service does with Health checks

  • When given a path on your app, Health check pings this path on all instances of your App Service app at 1-minute intervals.
  • If an instance doesn't respond with a status code between 200-299 (inclusive) after ten requests, App Service determines it is unhealthy¬†and removes it. (The required number of failed requests for an instance to be deemed unhealthy is configurable to a minimum of 2 requests.)
  • After removal, Health check continues to ping the unhealthy instance. If the instance begins to respond with a healthy status code (200-299) then the instance is returned to the load balancer.
  • If an instance remains unhealthy for one hour, it will be replaced with new instance.
  • When scaling out, App Service pings the Health check path to ensure new instances are ready.

Note

  • Health check doesn't follow 302 redirects.
  • At most one instance will be replaced per hour, with a maximum of three instances per day per App Service Plan.
  • If your health check is giving the status Waiting for health check response then the check is likely failing due to an HTTP status code of 307, which can happen if you have HTTPS redirect enabled but have HTTPS Only disabled.

Enable Health Check

Health check navigation in Azure Portal

  • To enable Health check, browse to the Azure portal and select your App Service app.
  • Under Monitoring, select Health check.
  • Select Enable and provide a valid URL path on your application, such as /health or /api/health.
  • Click Save.

Caution

Health check configuration changes restart your app. To minimize impact to production apps, we recommend configuring staging slots and swapping to production.

Configuration

In addition to configuring the Health check options, you can also configure the following app settings:

App setting name Allowed values Description
WEBSITE_HEALTHCHECK_MAXPINGFAILURES 2 - 10 The required number of failed requests for an instance to be deemed unhealthy and removed from the load balancer. For example, when set to 2, your instances will be removed after 2 failed pings. (Default value is 10)
WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT 0 - 100 By default, no more than half of the instances will be excluded from the load balancer at one time to avoid overwhelming the remaining healthy instances. For example, if an App Service Plan is scaled to four instances and three are unhealthy, two will be excluded. The other two instances (one healthy and one unhealthy) will continue to receive requests. In the worst-case scenario where all instances are unhealthy, none will be excluded.
To override this behavior, set app setting to a value between 0 and 100. A higher value means more unhealthy instances will be removed (default value is 50).

Authentication and security

Health check integrates with App Service's authentication and authorization features. No additional settings are required if these security features are enabled.

If you're using your own authentication system, the Health check path must allow anonymous access. To secure the Health check endpoint, you should first use features such as IP restrictions, client certificates, or a Virtual Network to restrict application access. Once you have those features in-place, you can authenticate the health check request by inspecting the header, x-ms-auth-internal-token, and validating that it matches the SHA256 hash of the environment variable WEBSITE_AUTH_ENCRPYTION_KEY. If they match, then the health check request is valid and originating from App Service.

using System;
using System.Text;

/// <summary>
/// Method <c>HeaderMatchesEnvVar</c> returns true if <c>headerValue</c> matches WEBSITE_AUTH_ENCRYPTION_KEY.
/// </summary>
public Boolean HeaderMatchesEnvVar(string headerValue) {
    var sha = System.Security.Cryptography.SHA256.Create();
    String envVar = Environment.GetEnvironmentVariable("WEBSITE_AUTH_ENCRYPTION_KEY");
    String hash = System.Convert.ToBase64String(sha.ComputeHash(Encoding.UTF8.GetBytes(envVar)));
    return hash == headerValue;
}

Note

The x-ms-auth-internal-token header is only available on Windows App Service.

Monitoring

After providing your application's Health check path, you can monitor the health of your site using Azure Monitor. From the Health check blade in the Portal, click the Metrics in the top toolbar. This will open a new blade where you can see the site's historical health status and option to create a new alert rule. Health check metrics will aggregate the successful pings & display failures only when the instance was deemed unhealthy based on the health check configuration. For more information on monitoring your sites, see the guide on Azure Monitor.

Limitations

  • Health check should not be enabled on Premium Functions sites. Due to the rapid scaling of Premium Functions, the Health check requests can cause unnecessary fluctuations in HTTP traffic. Premium Functions have their own internal health probes that are used to inform scaling decisions.
  • Health check can be enabled for Free and Shared App Service Plans so you can have metrics on the site's health and set up alerts, but because Free and Shared sites cannot scale out, any unhealthy instances will not be replaced. You should scale up to the Basic tier or higher so you can scale out to 2 or more instances and utilize the full benefit of Health check. This is recommended for production-facing applications as it will increase your app's availability and performance.

Frequently Asked Questions

What happens if my app is running on a single instance?

If your app is only scaled to one instance and becomes unhealthy, it will not be removed from the load balancer because that would take your application down entirely. Scale out to two or more instances to get the re-routing benefit of Health check. If your app is running on a single instance, you can still use Health check's monitoring feature to keep track of your application's health.

Why are the Health check request not showing in my web server logs?

The Health check request are sent to your site internally, so the request will not show in the web server logs. This also means the request will have an origin of 127.0.0.1 since it the request being sent internally. You can add log statements in your Health check code to keep logs of when your Health check path is pinged.

Are the Health check requests sent over HTTP or HTTPS?

On Windows App Service, the Health check requests will be sent via HTTPS when HTTPS Only is enabled on the site. Otherwise, they are sent over HTTP. On Linux App Service, the health check requests are only sent over HTTP and cannot be sent over HTTPS at this time.

What if I have multiple apps on the same App Service Plan?

Unhealthy instances will be always be removed from the load balancer rotation regardless of other apps on the App Service Plan (up to the percentage specified in WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT). When an app on an instance remains unhealthy for over one hour, the instance will only be replaced if all other apps with Health check enabled are also unhealthy. Apps which do not have Health check enabled will not be taken into account.

Example

Imagine you have two applications (or one app with a slot) with Health check enabled, called App A and App B. They are on the same App Service Plan and that the Plan is scaled out to 4 instances. If App A becomes unhealthy on two instances, the load balancer will stop sending requests to App A on those two instances. Requests will still be routed to App B on those instances assuming App B is healthy. If App A remains unhealthy for over an hour on those two instances, those instances will only be replaced if App B is also unhealthy on those instances. If App B is healthy, the instance will not be replaced.

Visual diagram explaining the example scenario above.

Note

If there were another site or slot on the Plan (Site C) without Health check enabled, it would not be taken into consideration for the instance replacement.

What if all my instances are unhealthy?

In the scenario where all instances of your application are unhealthy, App Service will remove instances from the load balancer up to the percentage specified in WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT. In this scenario, taking all unhealthy app instances out of the load balancer rotation would effectively cause an outage for your application.

Does Health Check work on App Service Environments?

Yes, on App Service Environments (ASEs), the platform will ping your instances on the specified path and remove any unhealthy instances from the load balancer so requests will not be routed to them. However, currently these unhealthy instances will not be replaced with new instances if they remain unhealthy for 1 hour.

Next steps