Skip to content

Commit 2691828

Browse files
Jay Bryantphilwebb
authored andcommitted
Update actuator docs to prefer "You can..."
Edit the actuator docs so that more "You can..." phrasing is used. For example "Auditing can be enabled by providing" becomes "You can enable auditing by providing" See gh-27759
1 parent 53363c8 commit 2691828

File tree

6 files changed

+40
-39
lines changed

6 files changed

+40
-39
lines changed

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/auditing.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Once Spring Security is in play, Spring Boot Actuator has a flexible audit framework that publishes events (by default, "`authentication success`", "`failure`" and "`access denied`" exceptions).
44
This feature can be very useful for reporting and for implementing a lock-out policy based on authentication failures.
55

6-
Auditing can be enabled by providing a bean of type `AuditEventRepository` in your application's configuration.
6+
You can enable auditing by providing a bean of type `AuditEventRepository` in your application's configuration.
77
For convenience, Spring Boot offers an `InMemoryAuditEventRepository`.
88
`InMemoryAuditEventRepository` has limited capabilities, and we recommend using it only for development environments.
99
For production environments, consider creating your own alternative `AuditEventRepository` implementation.

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/cloud-foundry.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@ Spring Boot's actuator module includes additional support that is activated when
44
The `/cloudfoundryapplication` path provides an alternative secured route to all `@Endpoint` beans.
55

66
The extended support lets Cloud Foundry management UIs (such as the web application that you can use to view deployed applications) be augmented with Spring Boot actuator information.
7-
For example, an application status page may include full health information instead of the typical "`running`" or "`stopped`" status.
7+
For example, an application status page can include full health information instead of the typical "`running`" or "`stopped`" status.
88

99
NOTE: The `/cloudfoundryapplication` path is not directly accessible to regular users.
10-
In order to use the endpoint, a valid UAA token must be passed with the request.
10+
To use the endpoint, you must pass a valid UAA token with the request.
1111

1212

1313

@@ -45,7 +45,7 @@ For example, if `server.servlet.context-path=/app`, Cloud Foundry endpoints will
4545

4646
If you expect the Cloud Foundry endpoints to always be available at `/cloudfoundryapplication/*`, regardless of the server's context-path, you will need to explicitly configure that in your application.
4747
The configuration will differ depending on the web server in use.
48-
For Tomcat, the following configuration can be added:
48+
For Tomcat, you can add the following configuration:
4949

5050
[source,java,indent=0,subs="verbatim"]
5151
----

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/endpoints.adoc

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Actuator endpoints let you monitor and interact with your application.
44
Spring Boot includes a number of built-in endpoints and lets you add your own.
55
For example, the `health` endpoint provides basic application health information.
66

7-
Each individual endpoint can be <<actuator#actuator.endpoints.enabling, enabled or disabled>> and <<actuator#actuator.endpoints.exposing, exposed (made remotely accessible) over HTTP or JMX>>.
7+
You can <<actuator#actuator.endpoints.enabling, enable or disable>> each individual endpoint and <<actuator#actuator.endpoints.exposing, expose them (make them remotely accessible) over HTTP or JMX>>.
88
An endpoint is considered to be available when it is both enabled and exposed.
99
The built-in endpoints will only be auto-configured when they are available.
1010
Most applications choose exposure via HTTP, where the ID of the endpoint along with a prefix of `/actuator` is mapped to a URL.
@@ -150,7 +150,7 @@ If you want to change only the technologies over which an endpoint is exposed, u
150150

151151
[[actuator.endpoints.exposing]]
152152
=== Exposing Endpoints
153-
Since Endpoints may contain sensitive information, careful consideration should be given about when to expose them.
153+
Since Endpoints may contain sensitive information, you should carefully consider when to expose them.
154154
The following table shows the default exposure for the built-in endpoints:
155155

156156
[cols="1,1,1"]
@@ -280,7 +280,7 @@ To change which endpoints are exposed, use the following technology-specific `in
280280
The `include` property lists the IDs of the endpoints that are exposed.
281281
The `exclude` property lists the IDs of the endpoints that should not be exposed.
282282
The `exclude` property takes precedence over the `include` property.
283-
Both `include` and `exclude` properties can be configured with a list of endpoint IDs.
283+
You can configure both the `include` and the `exclude` properties with a list of endpoint IDs.
284284

285285
For example, to stop exposing all endpoints over JMX and only expose the `health` and `info` endpoints, use the following property:
286286

@@ -317,7 +317,7 @@ TIP: If you want to implement your own strategy for when endpoints are exposed,
317317
[[actuator.endpoints.security]]
318318
=== Security
319319
For security purposes, all actuators other than `/health` are disabled by default.
320-
The configprop:management.endpoints.web.exposure.include[] property can be used to enable the actuators.
320+
You can use the configprop:management.endpoints.web.exposure.include[] property to enable the actuators.
321321

322322
NOTE: Before setting the `management.endpoints.web.exposure.include`, ensure that the exposed actuators do not contain sensitive information and/or are secured by placing them behind a firewall or by something like Spring Security.
323323

@@ -366,7 +366,7 @@ This means that the actuator endpoints that require a `POST` (shutdown and logge
366366

367367
NOTE: We recommend disabling CSRF protection completely only if you are creating a service that is used by non-browser clients.
368368

369-
Additional information about CSRF protection can be found in the {spring-security-docs}#csrf[Spring Security Reference Guide].
369+
You can find additional information about CSRF protection in the {spring-security-docs}#csrf[Spring Security Reference Guide].
370370

371371

372372

@@ -465,7 +465,7 @@ When exposed via JMX, the parameters are mapped to the parameters of the MBean's
465465
Parameters are required by default.
466466
They can be made optional by annotating them with either `@javax.annotation.Nullable` or `@org.springframework.lang.Nullable`.
467467

468-
Each root property in the JSON request body can be mapped to a parameter of the endpoint.
468+
You can map each root property in the JSON request body to a parameter of the endpoint.
469469
Consider the following JSON request body:
470470

471471
[source,json,indent=0,subs="verbatim"]
@@ -517,7 +517,7 @@ The path of the predicate is determined by the ID of the endpoint and the base p
517517
The default base path is `/actuator`.
518518
For example, an endpoint with the ID `sessions` will use `/actuator/sessions` as its path in the predicate.
519519

520-
The path can be further customized by annotating one or more parameters of the operation method with `@Selector`.
520+
You can further customize the path by annotating one or more parameters of the operation method with `@Selector`.
521521
Such a parameter is added to the path predicate as a path variable.
522522
The variable's value is passed into the operation method when the endpoint operation is invoked.
523523
If you want to capture all remaining path elements, you can add `@Selector(Match=ALL_REMAINING)` to the last parameter and make it a type that is conversion compatible with a `String[]`.
@@ -579,7 +579,7 @@ If an operation is invoked without a required parameter, or with a parameter tha
579579

580580
[[actuator.endpoints.implementing-custom.web.range-requests]]
581581
===== Web Endpoint Range Requests
582-
An HTTP range request can be used to request part of an HTTP resource.
582+
You can use an HTTP range request to request part of an HTTP resource.
583583
When using Spring MVC or Spring Web Flux, operations that return a `org.springframework.core.io.Resource` automatically support range requests.
584584

585585
NOTE: Range requests are not supported when using Jersey.
@@ -605,8 +605,8 @@ For new endpoints, the `@Endpoint` and `@WebEndpoint` annotations should be pref
605605

606606
[[actuator.endpoints.implementing-custom.controller]]
607607
==== Controller Endpoints
608-
`@ControllerEndpoint` and `@RestControllerEndpoint` can be used to implement an endpoint that is only exposed by Spring MVC or Spring WebFlux.
609-
Methods are mapped using the standard annotations for Spring MVC and Spring WebFlux such as `@RequestMapping` and `@GetMapping`, with the endpoint's ID being used as a prefix for the path.
608+
You can use `@ControllerEndpoint` and `@RestControllerEndpoint` to implement an endpoint that is exposed only by Spring MVC or Spring WebFlux.
609+
Methods are mapped by using the standard annotations for Spring MVC and Spring WebFlux, such as `@RequestMapping` and `@GetMapping`, with the endpoint's ID being used as a prefix for the path.
610610
Controller endpoints provide deeper integration with Spring's web frameworks but at the expense of portability.
611611
The `@Endpoint` and `@WebEndpoint` annotations should be preferred whenever possible.
612612

@@ -652,7 +652,7 @@ By default, the final system health is derived by a `StatusAggregator` which sor
652652
The first status in the sorted list is used as the overall health status.
653653
If no `HealthIndicator` returns a status that is known to the `StatusAggregator`, an `UNKNOWN` status is used.
654654

655-
TIP: The `HealthContributorRegistry` can be used to register and unregister health indicators at runtime.
655+
TIP: You can use the `HealthContributorRegistry` to register and unregister health indicators at runtime.
656656

657657

658658

@@ -1154,7 +1154,7 @@ The following `InfoContributor` beans are auto-configured by Spring Boot, when a
11541154
| Exposes build information if a `META-INF/build-info.properties` file is available.
11551155
|===
11561156

1157-
TIP: It is possible to disable them all by setting the configprop:management.info.defaults.enabled[] property.
1157+
TIP: You can disable them all by setting the configprop:management.info.defaults.enabled[] property.
11581158

11591159

11601160

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/jmx.adoc

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
[[actuator.jmx]]
22
== Monitoring and Management over JMX
33
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications.
4-
By default, this feature is not enabled and can be turned on by setting the configuration property configprop:spring.jmx.enabled[] to `true`.
4+
By default, this feature is not enabled.
5+
You can turn it on by setting the configprop:spring.jmx.enabled[] configuration property to `true`.
56
Spring Boot exposes the most suitable `MBeanServer` as a bean with an ID of `mbeanServer`.
67
Any of your beans that are annotated with Spring JMX annotations (`@ManagedResource`, `@ManagedAttribute`, or `@ManagedOperation`) are exposed to it.
78

@@ -68,7 +69,7 @@ For example, with Maven, you would add the following dependency:
6869
</dependency>
6970
----
7071

71-
The Jolokia endpoint can then be exposed by adding `jolokia` or `*` to the configprop:management.endpoints.web.exposure.include[] property.
72+
You can then expose the Jolokia endpoint by adding `jolokia` or `*` to the configprop:management.endpoints.web.exposure.include[] property.
7273
You can then access it by using `/actuator/jolokia` on your management HTTP server.
7374

7475
NOTE: The Jolokia endpoint exposes Jolokia's servlet as an actuator endpoint.

0 commit comments

Comments
 (0)