Wording for production & monitoring

pages/monitoring.md

@@ -8,13 +8,13 @@ sitemap:
 ---
 # <i class="fa fa-line-chart"></i> Monitoring your JHipster Applications
 
-JHipster provides easy ways to get started with logs and metrics monitoring of your applications. Log and metrics forwarding to a remote server can be set up simply by setting the relevant properties in your _application.yml_ configuration file. Then those logs and metrics can be displayed and analyzed in real-time using a monitoring platform. Aware of the importance of monitoring your apps in production, the JHipster project offers its own monitoring solution called the JHipster Console
+JHipster provides several easy ways to get started with logs and metrics monitoring of your applications. Logs and metrics forwarding to a remote server can be set up simply by setting the relevant properties in your `application.yml` configuration file. Then those logs and metrics can be displayed and analyzed in real-time using a monitoring platform. Aware of the importance of monitoring your applications in production, the JHipster project offers its own monitoring solution called the [JHipster Console](https://github.com/jhipster/jhipster-console), which is detailed below.
 
 ## Configuring your apps for log and metrics forwarding to a remote server
 
 ### <a name="configuring-log-forwarding"></a> Forwarding logs to the JHipster Console
 
-To configure a JHipster app to forward their logs to JHipster Console, enable logstash logging in their application-dev.yml or application-prod.yml.
+To configure a JHipster application to forward their logs to JHipster Console, enable logstash logging in their `application-dev.yml` or `application-prod.yml`:
 
     jhipster:
         logging:
@@ -24,7 +24,7 @@ To configure a JHipster app to forward their logs to JHipster Console, enable lo
                 port: 5000
                 queueSize: 512
 
-To configure metrics monitoring, enable metrics log reporting in your JHipster apps.
+To configure metrics monitoring, enable metrics log reporting in your JHipster application:
 
     jhipster:
         metrics:
@@ -36,43 +36,43 @@ Setting those properties will enrich your logs with metrics coming from Dropwiza
 
 ## <a name="jhipster-console"></a> Introducing the JHipster Console
 
-The JHipster Console is a monitoring tool based on the [ELK Stack](https://www.elastic.co/products). It provides ready to use dashboards and analytics tools to have a real time overview of your infrastructure's performance.
+The [JHipster Console](https://github.com/jhipster/jhipster-console) is a monitoring tool based on the [ELK Stack](https://www.elastic.co/products). It provides ready-to-use dashboards and analytics tools to have a real-time overview of your infrastructure's performance.
+
+The ELK stack is composed of:
 
-The ELK stack is composed of :
 - [Elasticsearch](https://www.elastic.co/products/elasticsearch) for indexing the data (logs and metrics)
 - [Logstash](https://www.elastic.co/products/logstash) to manage and process the logs received from the applications
 - [Kibana](https://www.elastic.co/products/kibana) to visualize the logs with a nice interface
 
-The JHipster Console is a docker based project that adds features on top of the official Elasticsearch, Logstash and Kibana docker images. We have made a few visual changes to Kibana and set up useful dashboards, so that you can get started to monitor your JHipster apps in minutes instead of the hours that would be needed to set up your own monitoring infrastructure.
-
+The JHipster Console is a Docker-based project that adds features on top of the official Elasticsearch, Logstash and Kibana Docker images. We have made a few visual changes to Kibana and set-up useful dashboards, so that you can get started to monitor your JHipster applications in minutes instead of the hours that would be needed to set up your own monitoring infrastructure.
 
 ## Setting up JHipster Console
 
-If you already have a JHipster microservice architecture set up with the Docker-Compose workflow, the JHipster Console can be automatically set up by the Docker-Compose sub-generator.
+If you already have a JHipster [microservice architecture]({{ site.url }}/microservices-architecture/) set up with the Docker Compose workflow, the JHipster Console can be automatically set up by the Docker Compose sub-generator.
 
-If you are using the monolith version of JHipster, you will need docker and docker-composed installed, then you can clone JHipster Console's [git repository](https://github.com/jhipster/jhipster-console) and run:
+If you are using the monolithic version of JHipster, you will need Docker and Docker Compose installed, then you can clone JHipster Console's [git repository](https://github.com/jhipster/jhipster-console) and run:
 
     docker-compose up -d
 
-It will start Elasticsearch, Logstash, Kibana and ElastAlert all at once. You will then be able to access the JHipster Console at [http://localhost:5601](http://localhost:5601). It should automatically receive logs from your applications if they have been correctly configured to forward their logs and metrics to logstash.
+It will start Elasticsearch, Logstash, Kibana and ElastAlert all at once. You will then be able to access the JHipster Console at [http://localhost:5601](http://localhost:5601). It should automatically receive logs from your applications if they have been correctly configured to forward their logs and metrics to Logstash.
 
 To stop everything, run:
 
-    docker-compose down
+    docker-compose stop
 
-Once stopped, you can remove the containers, if you don't intend to start them again:
+Once stopped, you can remove the containers if you don't intend to start them again:
 
     docker-compose rm
 
 ## Using JHipster Console
 
-Once your application is running with log and metrics forwarding enabled, you can view a dashboards by clicking on the **Load Saved Dashboards** icon ( <i class="fa fa-folder-open-o"></i> ) in the **Dashboard** tab.
+Once your application is running with logs and metrics forwarding enabled, you can view a dashboards by clicking on the **Load Saved Dashboards** icon ( <i class="fa fa-folder-open-o"></i> ) in the **Dashboard** tab.
 
 You can also use Kibana's **Discover** and **Visualize** tabs to explore your data and create new visualizations. To understand how to use Kibana's interface effectively please refer to its official documentation in particular the [Discover](https://www.elastic.co/guide/en/kibana/current/discover.html), [Visualize](https://www.elastic.co/guide/en/kibana/current/visualize.html) and [Dashboard](https://www.elastic.co/guide/en/kibana/current/dashboard.html) sections of the Kibana User Guide.
 
 ### Data persistence with docker volumes
 
-When using JHipster Console you can enable docker volumes in the _docker-compose.yml_ file by uncommenting the appropriate lines. Those volumes are used to share data between containers and the host. They will persist data and configuration even if containers are removed from your system.
+When using JHipster Console you can enable docker volumes in the `docker-compose.yml` file by uncommenting the appropriate lines. Those volumes are used to share data between containers and the host. They will persist data and configuration even if containers are removed from your system.
 
 - Elasticsearch has its data saved to `log-monitoring/log-data`
 - Logstash loads its configuration from `log-monitoring/log-config/logstash.conf`, you can edit this file to add new parsing rules for data received by logstash on UDP port 5000.
@@ -84,13 +84,13 @@ Searches, visualization and dashboards created in Kibana can be exported using t
 You can then extract the JSON description of a specific object under the `_source` field of the export.json file.
 You can then put this data in a JSON file in one of the `kibana/dashboard` sub-folder for auto-import.
 
-If you have created useful dashboards and visualizations for your JHipster apps please consider contributing those back to the community by submitting a Pull Request on the JHipster Console's github.
+If you have created useful dashboards and visualizations for your JHipster applications please consider contributing those back to the community by submitting a Pull Request on the [JHipster Console's GitHub project](https://github.com/jhipster/jhipster-console).
 
 ### <a name="alerting"></a> Alerting with Elastalert
 
 [Elastalert](https://github.com/Yelp/elastalert) is an alerting system that can generate alerts from data in Elasticsearch.
 
-### Configure Alerting
+#### Configure alerting
 
 Elastalert configuration can be modified in `alerts/config.yaml`.
 To enable alerting, you just need to set up how often you would like the alerting system to check for events, by setting for example:
@@ -100,7 +100,7 @@ To enable alerting, you just need to set up how often you would like the alertin
 
 Then you will need to write some rules that define when alerts will be thrown.
 
-### Write alertings rules
+#### Write alertings rules
 
 Add new YAML rule files in `alerts/rules` and then test them over past data with:
 

pages/production.html

@@ -17,47 +17,42 @@ <h2>Configuration</h2>
 </p>
 <p>
 <code>
-mvn -Pprod
+./mvnw -Pprod
 </code>
 </p>
 <p>
 Or when using Gradle:
 </p>
 <p>
 <code>
-gradlew -Pprod
+./gradlew -Pprod
 </code>
 </p>
 <p>
-This profile will compile, test and package your Java application with all productions settings. It will also trigger a "gulp build", so your static resources are optimized.
-</p>
-<p>
-Earlier versions of JHipster put these optimized assets in <code>src/main/webapp/dist</code>, as a child directory of the "dev" assets. As of 3.0, these have been separated and
-the optimized assets are now located in <code>target/www</code> for Maven or <code>build/www</code> for Gradle.
+This profile will compile, test and package your application with all productions settings.
 </p>
 <p>
 If you want more information on the available profiles, please go the section titled "<a href="{{ site.url }}/profiles/">Development and Production profiles</a>".
 </p>
 
-
 <h2>Generating a WAR file</h2>
 
 <p>To package the application as a "production" WAR, type:
 </p>
 
 <p>
     <code>
-    mvn -Pprod package
+    ./mvnw -Pprod package
     </code>
 </p>
 
 <p>
 Or when using Gradle:
 </p>
 <p>
-<code>
-gradlew -Pprod bootRepackage
-</code>
+    <code>
+    ./gradlew -Pprod bootRepackage
+    </code>
 </p>
 
 <p>
@@ -75,39 +70,28 @@ <h2>Generating a WAR file</h2>
 </p>
 
 <p>
-Please note that when building a WAR file with the "prod" profile, the generated archive will not include the "dev" assets!
+<b>Please note</b> that when building a WAR file with the "prod" profile, the generated archive will not include the "dev" assets!
 This means that you will have to explicitly set the "prod" profile when running or deploying the WAR file, as well, because
 otherwise you will end up with an odd combination of production front-end with development back-end.
-</p>
-
-<p>
-Once you have deployed you WAR file on your application server:
-<p>
-<ul>
-  <li>It will use by default the "dev" profile</li>
-  <li>It can run in "production mode" if you trigger the "prod" profile (there are several ways to trigger a Spring profile, for example you can add <code>-Dspring.profiles.active=prod</code> to your <code>JAVA_OPTS</code> when running your server)</li>
-</ul>
+<br/>
+There are several ways to trigger a Spring profile, for example you can add <code>-Dspring.profiles.active=prod</code> to your <code>JAVA_OPTS</code> when running your server.</p>
 
 <h2>Executing the WAR file without an application server</h2>
 <p>
-Instead of deploying on an application server, many people find it easier to just have an exectuable WAR file (which includes Tomcat 7, in fact).
+Instead of deploying on an application server, many people find it easier to just have an exectuable WAR file (which includes Tomcat 8, in fact).
 </p>
 <p>
-The first WAR file generated in the previous step is such a WAR, so you can run it in "development mode" by typing:
+The first WAR file generated in the previous step is such a WAR, so you can run it in "production" mode by typing:
 </p>
 <p>
     <code>
-    java -jar jhipster-0.0.1-SNAPSHOT.war
+    ./jhipster-0.0.1-SNAPSHOT.war --spring.profiles.active=prod
     </code>
 </p>
 <p>
-Or in "production" mode:
-</p>
-<p>
-    <code>
-    java -jar jhipster-0.0.1-SNAPSHOT.war --spring.profiles.active=prod
-    </code>
+<b>Please note</b> that we use of the Spring "prod" profile, as explained in the previous section.
 </p>
+
 <h2>Generating an optimized JavaScript application with Gulp</h2>
 <p>
 This step is automatically triggered when you build your project with the "production" profile. If you want to run it without launching a Maven build, just run:
@@ -121,7 +105,7 @@ <h2>Generating an optimized JavaScript application with Gulp</h2>
 This will process all your static resources (CSS, JavaScript, HTML, JavaScript, images...) in order to generate an optimized client-side application.
 </p>
 <p>
-This application will be generated in your <code>src/main/webapp/dist</code> folder, which by default is not checked in your Git repository (see your <code>.gitignore</code> file if you want to change this behavior).
+Those optimized assets will be generated in <code>target/www</code> for Maven or <code>build/www</code> for Gradle, and will be included in your final production WAR.
 </p>
 <p>
 This code will be served when you run the application with the "production" profile.