Updated README.md files

Author: altenhof

README.md

@@ -1,33 +1,43 @@
-# cf-java-logging-support
+# Java Logging Support for Cloud Foundry
 
-#### For the impatient:
+## Summary
 
-Version 2.x is a major rewrite of what we had before. While the usage as such should be similar, the most notable change is that you need to
+This is a collection of support libraries for Java applications running on Cloud Foundry that serve two main purposes: It provides (a) means to emit *structured application log messages* and (b) instrument parts of your application stack to *collect request metrics*.
 
-* make up your mind which parts you actually need, 
-* adjust your Maven dependencies accordingly, 
-* pick your favorite implementation, and
-* adjust your logging configuration accordingly.
+When we say structured, we actually mean in JSON format. In that sense, it's shares ideas with [logstash-logback-encoder](https://github.com/logstash/logstash-logback-encoder), but uses a simpler approach as we want to ensure that these structured messages adhere to standardized formats. With such standardized formats in place, it becomes much easier to ingest, process and search such messages in log analytic stacks like, e.g., [ELK](https://www.elastic.co/webinars/introduction-elk-stack).
+
+If you're interested in the specifications of these standardized formats, you may want to have closer look at the [beats folder](./cf-java-logging-support/beats).
+
+While [logstash-logback-encoder](https://github.com/logstash/logstash-logback-encoder) is tied to [logback](http://logback.qos.ch/), we've tried to stay implementation neutral and have implemented the core functionality on top of [slf4j](http://www.slf4j.org/),  but provide implementations for both [logback](http://logback.qos.ch/) and [log4j2](http://logging.apache.org/log4j/2.x/) (and we're open to contributions that would support other implementations).
+
+The instrumentation part is currently focusing on providing [request filters for Java Servlets](http://www.oracle.com/technetwork/java/filters-137243.html) and [client and server filters for Jersey](https://jersey.java.net/documentation/latest/filters-and-interceptors.html), but again, we're open to contributions for other APIs and frameworks.
 
-While V1 provided the one-stop super jar with baked-in, implementation specific log configuration, this is now torn apart into pieces. While we still have dependencies to other stuff, we now tag almost everything as *provided*, i.e. it's your duty to get the dependency management right in your application POM.
+## Features and dependencies
 
-##### Features and dependencies
+As you can see from the structure of this repository, we're not providing one *uber* JAR that contains everything, but provide each feature separately. We also try to stay away from wiring up too many dependencies by tagging almost all of them as *provided*, i.e. it's your duty to get all runtime dependencies resolved in your application POM file. 
+
+All in all, you should do the following:
+
+* make up your mind which features you actually need, 
+* adjust your Maven dependencies accordingly, 
+* pick your favorite logging implementation, and
+* adjust your logging configuration accordingly.
 
-Say, you want to make use the *servlet filter* feature, then you need to add the following dependency to your POM:
+Say, you want to make use of the *servlet filter* feature, then you need to add the following dependency to your POM:
 
 ``` xml
 <dependency>
   <groupId>com.sap.hcp.cf.logging</groupId>
   <artifactId>cf-java-logging-support-servlet</artifactId>
-  <version>2.0.7</version>
+  <version>2.0.6</version>
 </dependency>
 ```
 
 This feature only depends on the servlet API which you have included in your POM anyhow.
 
-##### Implementation variants and logging configurations
+## Implementation variants and logging configurations
 
-The *core* feature (on which all other features rely) is just using the `org.slf4j` API, but to actually get logs written, you need to pick an implementation feature. We now have two implementations
+The *core* feature (on which all other features rely) is just using the `org.slf4j` API, but to actually get logs written, you need to pick an implementation feature. As stated above, we have two implementations
 
 * `cf-java-logging-support-logback` based on [logback](http://logback.qos.ch/), and 
 * `cf-java-logging-support-log4j2` based on [log4j2](http://logging.apache.org/log4j/2.x/).
@@ -81,6 +91,7 @@ Here are sort of the minimal configurations you'd need:
 	<appender name="STDOUT-JSON" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.sap.hcp.cf.logback.encoder.JsonEncoder"/>
     </appender>
+  	<!-- for local development, you may want to switch to a more human-readable layout --> 
     <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
         <encoder>
             <pattern>%date %-5level [%thread] - [%logger]- %msg%n</pattern>
@@ -90,7 +101,8 @@ Here are sort of the minimal configurations you'd need:
        <!-- Use 'STDOUT' instead for human-readable output -->
        <appender-ref ref="STDOUT-JSON" />
     </root>
-    <logger name="com.sap.hcp.cf" level="${LOG_PERFX_LEVEL:-INFO}" />	
+  	<!-- request metrics are reported using INFO level, so make sure the instrumentation loggers are set to that level -->
+    <logger name="com.sap.hcp.cf" level="INFO" />	
 </configuration>
 ```
 
@@ -113,7 +125,8 @@ Here are sort of the minimal configurations you'd need:
         <!-- Use 'STDOUT' instead for human-readable output -->
         <AppenderRef ref="STDOUT-JSON" />
      </Root>
-     <Logger name="com.sap.hcp.cf" level="${LOG_PERFX_LEVEL:-INFO}"/>
+  	 <!-- request metrics are reported using INFO level, so make sure the instrumentation loggers are set to that level -->
+     <Logger name="com.sap.hcp.cf" level="INFO"/>
   </Loggers>
 </Configuration>      
 ```

cf-java-logging-support-core/beats/README.md

@@ -1,12 +1,15 @@
-# Beat Specifications for Application Logs and Request Statistics
+# Beat Specifications for Application Logs and Request Metrics
 
 The two subfolders contain the YAML specifications for
 
-* application log, and
-* request (performance) statistics
+* application logs, and
+* request (performance) metrics
 
 ["beats"](https://github.com/elastic/beats).
 
-These specifications capture which fields should ultimately show up in ElasticSearch once they've travelled through our processing pipeline. Ideally, the entity emitting the application or request log will already put things into a proper shape, but most likely the parser component (aka Logstash) will use rule sets to do a proper transformation.
+Although we can't use the corresponding software libraries (as we're talking about logging in Java, not in Go), having specifications written in that format still are of help if you consider ingesting such messages in ElasticSearch, as we do. Actually, we do automatically generate the Java field names that we use to store the data from those specification files.
+
+These specifications capture which fields should ultimately show up in ElasticSearch once they've travelled through a typical ELK processing pipeline. Ideally, the entity emitting the application log or request metrics will already put things into a proper shape, but most likely the parser component ( Logstash) will use rule sets to perform the necessary additions and/or transformations.
+
+
 
-Note that we also use the specifications to generate the Java _field names_ for our [Java logging support library](https://github.wdf.sap.corp/perfx/java-logging-support).