:toc:
:gs-rest-service: link:/guides/gs/rest-service
:spring_version: current
:icons: font
:source-highlighter: prettify
:project_id: gs-actuator-service
https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#production-ready[Spring Boot Actuator]
is a subproject of Spring Boot. It adds several production grade services to your
application with little effort on your part. In this guide, you will build an application
and then see how to add these services.
== What You Will Build
This guide takes you through creating a "`Hello, world`" RESTful web service with Spring
Boot Actuator. You will build a service that accepts the following HTTP GET request:
====
[source,sh]
----
$ curl http://localhost:9000/hello-world
----
====
It responds with the following JSON:
====
[source,json]
----
{"id":1,"content":"Hello, World!"}
----
====
There are also many features added to your application for managing the service in a
production (or other) environment. The business functionality of the service you build is
the same as in {gs-rest-service}[Building a RESTful Web Service]. You do not need to use
that guide to take advantage of this one, although it might be interesting to compare the
results.
=== What You need
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/prereq_editor_jdk_buildtools.adoc[]
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/how_to_complete_this_guide.adoc[]
[[scratch]]
== Starting with Spring Initializr
You can use this https://start.spring.io/#!type=maven-project&groupId=com.example&artifactId=actuator-service&name=actuator-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.actuatorservice&dependencies=web,actuator[pre-initialized project] and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.
To manually initialize the project:
. Navigate to https://start.spring.io.
This service pulls in all the dependencies you need for an application and does most of the setup for you.
. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.
. Click *Dependencies* and select *Spring Web* and *Spring Boot Actuator*.
. Click *Generate*.
. Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.
NOTE: If your IDE has the Spring Initializr integration, you can complete this process from your IDE.
NOTE: You can also fork the project from Github and open it in your IDE or other editor.
== Run the Empty Service
The Spring Initializr creates an empty application that you can use to get started. The
following shows the class created by the Spring Initializr:
====
[source,java,tabsize=2]
----
include::initial/src/main/java/com/example/actuatorservice/ActuatorServiceApplication.java[]
----
====
The `@SpringBootApplication` annotation provides a load of defaults (like the embedded
servlet container), depending on the contents of your classpath and other things. It also
turns on Spring MVC's `@EnableWebMvc` annotation, which activates web endpoints.
There are no endpoints defined in this application, but there is enough to launch things
and see some of Actuator's features. The `SpringApplication.run()` command knows how to
launch the web application. All you need to do is run the following command:
====
[source,bash,subs="attributes"]
----
$ ./gradlew clean build && java -jar build/libs/{project_id}-0.0.1-SNAPSHOT.jar
----
====
You have yet to write any code, so what is happening? To see the answer, wait for the
server to start, open another terminal, and try the following command (shown with its
output):
====
[source,bash]
----
$ curl localhost:8080
{"timestamp":1384788106983,"error":"Not Found","status":404,"message":""}
----
====
The output of the preceding command indicates that the server is running but that you have
not defined any business endpoints yet. Instead of a default container-generated HTML
error response, you see a generic JSON response from the Actuator `/error` endpoint. You
can see in the console logs from the server startup which endpoints are provided out of
the box. You can try a few of those endpoints, including the `/health` endpoint. The
following example shows how to do so:
====
[source,bash]
----
$ curl localhost:8080/actuator/health
{"status":"UP"}
----
====
The status is `UP`, so the actuator service is running.
See Spring Boot's
https://github.com/spring-projects/spring-boot/tree/main/spring-boot-project/spring-boot-actuator[Actuator Project]
for more details.
[[initial]]
== Create a Representation Class
First, you need to give some thought to what your API will look like.
You want to handle GET requests for `/hello-world`, optionally with a name query
parameter. In response to such a request, you want to send back JSON, representing a
greeting, that looks something like the following:
====
[source,json]
----
{
"id": 1,
"content": "Hello, World!"
}
----
====
The `id` field is a unique identifier for the greeting, and `content` contains the textual
representation of the greeting.
To model the greeting representation, create a representation class. The following listing
(from `src/main/java/com/example/actuatorservice/Greeting.java`) shows the `Greeting`
class:
====
[source,java,tabsize=2]
----
include::complete/src/main/java/com/example/actuatorservice/Greeting.java[]
----
====
Now that you need to create the endpoint controller that will serve the representation
class.
== Create a Resource Controller
In Spring, REST endpoints are Spring MVC controllers. The following Spring MVC controller
(from `src/main/java/com/example/actuatorservice/HelloWorldController.java`) handles a GET
request for the `/hello-world` endpoint and returns the `Greeting` resource:
====
[source,java,tabsize=2]
----
include::complete/src/main/java/com/example/actuatorservice/HelloWorldController.java[]
----
====
The key difference between a human-facing controller (`Controller`) and a REST endpoint
controller (`RestController`) is in how the response is created. Rather than rely on a
view (such as JSP) to render model data in HTML, an endpoint controller returns the data
to be written directly to the body of the response.
The response is written using one of Spring's message converters. Because Jackson is in the classpath,
https://docs.spring.io/spring/docs/{spring_version}/javadoc-api/org/springframework/http/converter/json/JacksonJsonHttpMessageConverter.html[`JacksonJsonHttpMessageConverter`]
will handle the conversion of a `Greeting` object to JSON if the request's `Accept` header
specifies that JSON should be returned.
NOTE: How do you know Jackson is on the classpath? Either run `mvn dependency:tree` or
`./gradlew dependencies`, and you get a detailed tree of dependencies that includes
Jackson. You can also see that it comes from
https://github.com/spring-projects/spring-boot/tree/main/starter/spring-boot-starter-json[/spring-boot-starter-json],
itself imported by
https://github.com/spring-projects/spring-boot/tree/main/starter/spring-boot-starter-webmvc[spring-boot-starter-webmvc].
== Run the Application
You can run the application from a custom main class or directly from one of the
configuration classes. For this simple example, you can use the `SpringApplication` helper
class. Note that this is the application class that the Spring Initializr created for you,
and you need not even modify it for it to work for this simple application. The following
listing (from `src/main/java/com/example/actuatorservice/HelloWorldApplication.java`)
shows the application class:
====
[source,java,tabsize=2]
----
include::complete/src/main/java/com/example/actuatorservice/HelloWorldApplication.java[]
----
====
In a conventional Spring MVC application, you would add `@EnableWebMvc` to turn on key
behaviors, including configuration of a `DispatcherServlet`. But Spring Boot turns on this
annotation automatically when it detects *spring-webmvc* on your classpath. This sets you
up to build a controller in an upcoming step.
The `@SpringBootApplication` annotation also brings in a
https://docs.spring.io/spring/docs/{spring_version}/javadoc-api/org/springframework/context/annotation/ComponentScan.html[`@ComponentScan`]
annotation, which tells Spring to scan the `com.example.actuatorservice` package for those
controllers (along with any other annotated component classes).
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/build_an_executable_jar_mainhead.adoc[]
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/build_an_executable_jar_with_both.adoc[]
Once the service is running (because you ran `spring-boot:run` in a terminal), you can test it by running the following command in a separate terminal:
====
[source,bash]
----
$ curl localhost:8080/hello-world
{"id":1,"content":"Hello, Stranger!"}
----
====
== Switch to a Different Server Port
Spring Boot Actuator defaults to running on port 8080. By adding an
`application.properties` file, you can override that setting. The following listing (from
`src/main/resources/application.properties`)shows that file with the necessary changes:
====
[source,properties]
----
include::complete/src/main/resources/application.properties[]
----
====
Run the server again by running the following command in a terminal:
====
[subs="attributes"]
----
$ ./gradlew clean build && java -jar build/libs/{project_id}-0.0.1-SNAPSHOT.jar
----
====
The service now starts on port 9000 and actuator endpoints on port 9001.
You can test that it is working on port 9000 by running the following commands in a
terminal:
====
[source,bash]
----
$ curl localhost:8080/hello-world
curl: (52) Empty reply from server
$ curl localhost:9000/hello-world
{"id":1,"content":"Hello, Stranger!"}
$ curl localhost:9001/actuator/health
{"status":"UP"}
----
====
== Test Your Application
To check whether your application works, you should write unit and integration tests for
your application.
The test class in
`src/test/java/com/example/actuatorservice/HelloWorldApplicationTests.java`
ensures that
* Your controller is responsive.
* Your management endpoint is responsive.
Note that the tests start the application on a random port.
The following listing shows the test class:
====
[source,java,tabsize=2]
----
include::complete/src/test/java/com/example/actuatorservice/ActuatorServiceApplicationTests.java[]
----
====
== Summary
Congratulations! You have just developed a simple RESTful service by using Spring, and you
added some useful built-in services with Spring Boot Actuator.
== See Also
The following guides may also be helpful:
* https://spring.io/guides/gs/spring-boot/[Building an Application with Spring Boot]
* https://spring.io/guides/gs/serving-web-content/[Serving Web Content with Spring MVC]
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/footer.adoc[]