jdaugherty commented on code in PR #16536:
URL: https://github.com/apache/grails-core/pull/16536#discussion_r4199897646
##########
grails-doc/src/en/guide/gettingStarted/runningAndDebuggingAnApplication.adoc:
##########
@@ -74,3 +74,189 @@ For debugging a Grails app, you have two options. You can
either right-click on
$ ./gradlew bootRun --debug-jvm
For more information on the `bootRun` command, please refer to the
link:{commandLineRef}bootRun.html[bootRun section of the Grails reference
guide].
+
+[[startupProgress]]
+=== Watching the Application Start
+
+The `grails-startup-progress` module shows how far an application has got as
it starts. Add it to the application's `build.gradle`, or select the
`grails-startup-progress` feature when generating the application:
+
+[source,groovy]
+----
+dependencies {
+ implementation 'org.apache.grails:grails-startup-progress'
+}
+----
+
+With it, in development mode, which is the `development` environment run from
the project directory as `./gradlew bootRun` does, Grails answers on the
application's port as soon as the application begins to start, rather than
leaving the port closed until the embedded server is ready. Opening the
application in a browser while it starts shows a progress page with:
+
+* the stage the start has reached: preparing the application context, loading
plugins and bean definitions, creating beans, starting the web server, and
running plugin startup hooks and `BootStrap` classes
+* how many of the application's beans have been created, and which bean is
being created now
+* the beans that have taken longest to create so far, not counting the beans
they depend on, which is usually the quickest way to find out why a start is
slow
+
+The page reloads the address it was opened at once the application is ready,
which is after `BootStrap` has finished, not merely once the web server is
listening. A browser that opens the application while `BootStrap` runs is shown
the progress page too, rather than pages from an application that has not
finished starting.
+
+Until the web server is listening, any request that is not for a web page,
such as a call to a REST endpoint, gets a `503 Service Unavailable` response
with a `Retry-After` header. Once it is listening, such requests reach the
application as they always have, including requests the application makes to
itself from `BootStrap`.
+
+If the start fails, the page shows the exception and its stack trace and stays
open. Start the application again and the page follows the new start and
reloads when it is ready.
+
+The stages, the beans, the exception and the Grails version are details of the
application's internals, so the page shows them only to a browser signed in
with the address the application logs as it starts:
+
+[source,console]
+----
+Startup progress is shown at http://localhost:8080/?grailsStartupToken=… until
the application is ready
+----
+
+Opening that address once signs the browser in for as long as the application
runs, through restarts by Spring Boot DevTools, and takes the token back out of
the address bar. A browser opened by the application, as described below, is
signed in already. Anyone else reaching the port sees only the progress bar:
the details are left out of the page and out of its data, rather than hidden in
them. The sign-in is a cookie, so it covers every tab of the browser that
signed in. The token is made afresh each time the JVM starts and is only ever
written to the log, so seeing the details takes the same access as reading the
log.
+
+Until the embedded server takes the port over, the page is served by the HTTP
server built into the JDK, so it changes nothing about how the application
itself serves requests. In the interactive shell, `grails run-app` keeps
waiting while the page holds the port, and stops waiting once the embedded
server has taken the port over, as it does for an application without the
module, so it does not wait for `BootStrap`. The page is not served when the
application:
+
+* is deployed as a WAR to a servlet container
+* uses a random port (`server.port: 0`) or SSL
+* finds its port already in use, in which case the application fails to start
exactly as it would without the page
+
+These settings control the page:
+
+[source,yaml]
+----
+grails:
+ startup:
+ progress:
+ enabled: false # whether to serve the page; by default, only
in development mode
Review Comment:
Done: the three are shown commented out, with a sentence above the block
saying they have no fixed default.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
