Health

The Health package provides a basic infrastructure that Swift applications can use for reporting their overall health status.

As an application developer, you create an instance of the Health class and then register one or more health checks. A health check can be either a closure that conforms to the HealthCheckClosure typealias or a class that conforms to the HealthCheck protocol. Once you have your health checks in place, you can ask your Health instance for its status.

Swift version

The latest version of Health works with the 4.1.2 version of the Swift binaries. You can download this version of the Swift binaries by following this link.

Usage

Add dependencies

Add Health to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest Healthrelease.

The simple dictionary contains a key-value pair that lets you know whether the application is UP or DOWN:

["status": "UP"]

The dictionary contains a key-value pair that lets you know whether the application is UP or DOWN, additional details about the health checks that failed (if any), and a Universal Time Coordinated (UTC) timestamp value:

Swift applications can use either dictionary, depending on the use case, to report the overall status of the application. For instance, an endpoint on the application could be defined that queries the Health object to get the overall status and then send it back to a client as a JSON payload.

The Status structure now conforms to the Codable protocol, which enables you to serialize an instance of this structure and send it as a response to a client. If you use this mechanism you don’t need to invoke either the toDictionary() or the toSimpleDictionary() methods in order to obtain the status payload for a client:

Caching

When you create an instance of the Health class, you can pass an optional argument (named statusExpirationTime) to its initializer as shown next:

lethealth=Health(statusExpirationTime:30000)

The statusExpirationTime parameter specifies the number of milliseconds that a given instance of Health should cache its status for before recomputing it. For instance, if the value assigned to statusExpirationTime is 30000 (as shown above), then 30 seconds must elapse before the Health instance computes its status again by querying each health check that has been registered. The default value for the statusExpirationTime parameter is 30000.

Implementing a health check

You can implement health checks by either extending the HealthCheck protocol or creating a closure that returns a State value.

The following snippet of code shows the implementation of a class named MyCustomCheck, which implements the HealthCheck protocol:

classMyCustomCheck:HealthCheck{publicvarname:String{get{return"MyCustomCheck for XYZ"}}publicvardescription:String{get{return"Description for MyCustomCheck..."}}publicfuncevaluate()->State{letstate:State=isConnected()?State.UP:State.DOWNreturnstate}privatefuncisConnected()->Bool{...}}

The following snippet of code shows the implementation for a similar health check but using a closure instead:

In the code sample above, the health of the application is exposed through the /health endpoint. Cloud environments (e.g. Cloud Foundry, Kubernetes, etc.) can then use the status information returned from the /health endpoint to monitor and manage the Swift application instance.

As an alternative to the implementation shown above for the /health endpoint, you can take advantage of the Codable protocol available in Swift 4. Since the Status struct satisfies the Codable protocol, a simpler implementation for the /health endpoint can be implemented using the new codable capabilities in Kitura 2.0 as shown below:

In addition to sending the dictionary response, a server needs to respond with a non-200 status code, if the health state is considered down. This can be accomplished with a status code such as 503 .serviceUnavailable. That way, the cloud environment can recognize the negative health response, destroy that instance of the application, and restart the application.

Using Cloud Foundry Environment

If using a Cloud Foundry environment, make sure to update your manifest.yml to support health check. In the example above, you would set the health-check-type value to http and the health-check-http-endpoint to the correct health endpoint path, which is /health in this case. Review the health check documentation for more details.