= Spring Boot Actuator Endpoints
:toc: left
:idprefix: spring_boot_actuator_
:sectanchors:
:icons: font
:last-update-label!:

Actuator endpoints allow you to monitor and interact with your application. Spring Boot
includes a number of built-in endpoints and you can also add your own. For example the
`health` endpoint provides basic application health information.

The way that endpoints are exposed will depend on the type of technology that you choose.
Most applications choose HTTP monitoring, where the ID of the endpoint is mapped
to a URL. For example, by default, the `health` endpoint will be mapped to `/health`.



== List of Endpoints
include::{generated}/endpoints.adoc[]



=== /auditevents
This endpoint provides information about audit events registered by the application.
Audit events can be filtered using the `after`, `principal` and `type` parameters as
defined by `AuditEventRepository`.

Example cURL request with `after` parameter:
include::{generated}/auditevents/curl-request.adoc[]

Example HTTP request with `after` parameter:
include::{generated}/auditevents/http-request.adoc[]

Example HTTP response:
include::{generated}/auditevents/http-response.adoc[]

Example cURL request with `principal` and `after` parameters:
include::{generated}/auditevents/filter-by-principal/curl-request.adoc[]

Example HTTP request with `principal` and `after` parameters:
include::{generated}/auditevents/filter-by-principal/http-request.adoc[]

Example cURL request with `principal`, `after` and `type` parameters:
include::{generated}/auditevents/filter-by-principal-and-type/curl-request.adoc[]

Example HTTP request with `principal`, `after` and `type` parameters:
include::{generated}/auditevents/filter-by-principal-and-type/http-request.adoc[]



=== /logfile
This endpoint (if available) contains the plain text logfile configured by the user
using `logging.file` or `logging.path` (by default logs are only emitted on stdout
so one of these properties has to be set for this endpoint to be active).

Example curl request:
include::{generated}/logfile/curl-request.adoc[]

Example HTTP request: [small]##link:../logfile[icon:external-link[role="silver"]]##
include::{generated}/logfile/http-request.adoc[]

Example HTTP response:
include::{generated}/logfile/http-response.adoc[]

==== Partial content

You can use the `Range` header to retrieve part of the log file's content.

Example curl request:
include::{generated}/partial-logfile/curl-request.adoc[]

Example HTTP request:
include::{generated}/partial-logfile/http-request.adoc[]

Example HTTP response:
include::{generated}/partial-logfile/http-response.adoc[]



=== /docs
This endpoint (if available) contains HTML documentation for the other endpoints. Its path
can be "/docs" (if there is an existing home page) or "/" (otherwise, including if the
HAL browser is not active).



== Hypermedia Support
If `endpoints.hypermedia.enabled` is set to `true` and
https://projects.spring.io/spring-hateoas[Spring HATEOAS] is on the classpath  (e.g.
through the `spring-boot-starter-hateoas` or if you are using
https://projects.spring.io/spring-data-rest[Spring Data REST]) then the Actuator endpoint
responses are enhanced with hypermedia in the form of "links". The default media type for
responses is https://github.com/mikekelly/hal_specification[HAL], resulting in each
resource having an extra property called "_links". You can change the media type to
another one supported by Spring HATEOAS by providing your own `@EnableHypermedia`
annotation and custom providers as necessary.

Example enhanced "/metrics" endpoint with additional "_links":

include::{generated}/metrics/hypermedia/http-response.adoc[]

WARNING: Beware of Actuator endpoint paths clashing with application endpoints.
The easiest way to avoid that is to use a `management.context-path`, e.g. "/admin".

TIP: You can disable the hypermedia support in Actuator endpoints by setting
`endpoints.actuator.enabled=false`.



=== Main entry point
When the hypermedia support is enabled, the Actuator provides a main entry point that
provides links to all of its endpoints. If `management.context-path` is empty, this entry
point is available at `/actuator`. If a management context path has been configured then
the entry point is available at the root of that context. For example, if
`management.context-path` has been set to `/admin` then the main entry point will be
available at `/admin`.

TIP: The endpoint path can always, as with all MVC endpoints, be overridden using
`endpoints.actuator.path=/yourpath` (note the leading slash).

include::{generated}/admin/http-response.adoc[]



=== Endpoints with format changes
Some endpoints in their "`raw`" form consist of an array (e.g. the `/beans` and the
`/trace` endpoints). These need to be converted to objects (maps) before they can be
enhanced with links, so their contents are inserted as a field named "`content`".
Example enhanced `/beans` endpoint with additional `_links`:

include::{generated}/beans/hypermedia/http-response.adoc[]



== HAL Browser
If Hypermedia is enabled and the HAL format is in use (which is the default), then you
can provide a browser for the resources by including a dependency on the
https://github.com/mikekelly/hal-browser[HAL browser] webjar.

For example in Maven:

[source,xml,indent=0]
----
	<dependency>
		<groupId>org.webjars</groupId>
		<artifactId>hal-browser</artifactId>
	</dependency>
----


or in Gradle:

[source,groovy,indent=0]
----
	dependencies {
		...
		compile('org.webjars:hal-browser')
		...
	}
----

NOTE: If you are using Spring Data REST, then a dependency on the
`spring-data-rest-hal-browser` will have an equivalent effect.

If you do that then the main entry point will server a static HTML page to browser clients
with some JavaScript that lets you browse the available resources.

Example:

image::hal-browser.png[HAL Browser]



== Actuator Documentation Browser
You can also provide a browser for the standard generated documentation for the Actuator
endpoints by including a dependency on the documentation jar.

For example in Maven:

[source,xml,indent=0]
----
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-actuator-docs</artifactId>
	</dependency>
----

or in Gradle:

[source,groovy,indent=0]
----
	dependencies {
		...
		compile('org.springframework.boot:spring-boot-actuator-docs')
		...
	}
----

If you do that then a new endpoint at `/` or `/docs` (relative to the
`management.context-path`) will serve up a static HTML page with this documentation in it.
The default endpoint path depends on whether or not there is already a static home page
("index.html" or a HAL browser) - if there is not and the `management.context-path` is
empty, then the docs browser shows up on the home page.
