Merge pull request #1 from wso2/master

Update

README.md

@@ -213,6 +213,65 @@ Invoke by the container during server shutdown before the  container removes the
 
 For a detailed example, check out the lifecycle sample [here](https://github.com/wso2/msf4j/tree/master/samples/lifecycle). 
 
+##Annotations for Analytics
+
+In this section, we will look at the annotations available for analytics purposes MSF4J microservices. There are annotations 
+for Metrics and HTTP Monitoring.
+
+You will need to configure [analytics](analytics) when you want to publish Metrics and HTTP Monitoring events to 
+WSO2 Data Analytics Server (DAS).
+
+The Metrics data will be published to WSO2 DAS periodically. However the HTTP Monitoring events are published on each request.
+
+For a detailed example, check out the [Metrics and HTTP Monitoring sample](samples/metrics-httpmon/metrics-httpmon-fatjar). 
+
+###Metrics Annotations
+
+You can use the Metrics annnotations in your MSF4J microservices to understand how your microservices work in production.
+
+There are three metrics annotations supported. Those are @Counted, @Metered and @Timed.
+
+Each metric must have a unique name and the MSF4J will use the fully qualified method name as the metric name by default. 
+You can give a custom name by using the "name" parameter. This custom name will be appended to the fully qualified method name 
+with a dot character. You can set the "absolute" parameter to "true" if you want use only the given name as the metric name. 
+
+For example, see following table to understand how the final metric name is built by the Metrics runtime. Let's asssume that the 
+annotation is added to the "hello" method of "HelloService" shown above.
+
+| Metrics Annotation                               | Metric Name                                         |
+| ------------------------------------------------ | --------------------------------------------------- |
+| @Counted                                         | org.example.service.HelloService.hello              |
+| @Counted(name = "helloCounter")                  | org.example.service.HelloService.hello.helloCounter |
+| @Counted(name = "helloCounter", absolute = true) | helloCounter                                        |
+
+The Metrics annotations can be used only at the Method level.
+
+You can also configure a level in Metrics Annotations. For more information about Metric Levels, 
+see [WSO2 Carbon Metrics](https://github.com/wso2/carbon-metrics). In MSF4J, you can load the metrics level configuration 
+via the System Propery named `metrics.level.configuration`.
+
+#####@Counted
+Count the method invocations. There is a parameter named "monotonic" and it is set to false by default. This means that the
+counter is decremented when the method returns. This is useful to count the current invocations of the annotated method.
+
+Use `@Counted(monotonic = true)` when you want the counter to increase monotonically. This is useful to count the total invocations 
+of the annotated method
+
+#####@Metered
+Measure the rate of method invocations. This also keeps a count of the total invocations of the annotated method.
+
+#####@Timed
+Maintain a histogram of durations of each method invocation. This also measures the rate of method invocations and keeps a count of the 
+total invocations of the annotated method. 
+
+###HTTP Monitoring Annotation
+
+You can use the annotation provided for HTTP Monitoring when you want to monitor each HTTP request and see the summary 
+in "HTTP Monitoring Dashboard".
+
+#####@HTTPMonitored
+Monitor each HTTP request. This annotation can be used at the Class level and the Method level.
+
 
 ###Complete Feature List
 * Annotation based definition of microservices

pom.xml

@@ -105,10 +105,16 @@
         <module>poms/parent</module>
         <module>jaxrs-delegates</module>
         <module>core</module>
+        <module>poms/msf4j-service</module>
         <module>analytics/msf4j-analytics</module>
-        <module>product/p2-features/org.wso2.msf4j.feature</module>
         <module>templating/msf4j-mustache-template</module>
-        <module>poms/msf4j-service</module>
+        <module>archetypes/msf4j-microservice</module>
+        <!-- Distribution -->
+        <module>distribution/msf4j-all</module>
+        <module>distribution/binary</module>
+        <module>product/p2-features/org.wso2.msf4j.feature</module>
+        <!--<module>product</module>-->
+        <!-- MSF4J Samples -->
         <module>samples/helloworld</module>
         <module>samples/stockquote/fatjar</module>
         <module>samples/stockquote/bundle</module>
@@ -120,10 +126,6 @@
         <module>samples/template</module>
         <module>samples/log-interceptor-bundle</module>
         <module>samples/lifecycle</module>
-        <module>product</module>
-        <module>distribution/msf4j-all</module>
-        <module>distribution/binary</module>
-        <module>archetypes/msf4j-microservice</module>
     </modules>
 
     <properties>

samples/README.md

@@ -6,7 +6,9 @@ This directory contain a comprehensive suite of samples demonstrating the capabi
 * JDK 1.8.*
 * Maven 3.0.x
 
-#Samples
+#Samples 
+In increasing order of complexity;
+
 * [Hello World](helloworld) - Running a Basic Microservice
 * [StockQuote (Fat jar)](stockquote/stockquote-fatjar) - Developing a Microservice as a single jar which packs all the dependencies
 * [StockQuote (OSGi bundle)](stockquote/stockquote-bundle) - Creating a Microservice as an OSGi Bundle

samples/metrics-httpmon/metrics-httpmon-fatjar/README.md

@@ -14,6 +14,8 @@ Use @Timed to keep a histogram of durations of each method invocation.
 
 The @Metered annotation also keeps a count. The @Timed annotation keeps the count and rate of events as well.
 
+See [Metrics Annotations](../../../../../#metrics-annotations) for more details.
+
 See the following example:
 
 ```java
@@ -65,6 +67,8 @@ new MicroservicesRunner()
 
 Use the @HTTPMonitored annotation when you want to monitor each HTTP request. 
 
+See [HTTP Monitoring Annotation](../../../../../#http-monitoring-annotation) for more details.
+
 See the following example to use the annotation at the Class level.
 
 ```java

samples/petstore/deployment/README.md

@@ -33,11 +33,15 @@ sudo apt-get install vagrant
 sudo apt-get install virtualbox
 ```
 
-After installing Vagrant and VirtualBox, run automated deployment.
+**Install NFS Server**
+
+```apt-get install nfs-kernel-server```
+
+After installing Vagrant, VirtualBox and NFS, run automated deployment.
 
 ##Run automated deployment 
 
-WSO2 Data Analytics Server pack (zip) into packs folder
+Copy WSO2 Data Analytics Server pack (zip) into packs folder
 
 Run the following commands.
 ```

samples/security/README.md

@@ -15,7 +15,11 @@ Here we use WSO2 Identity server as the authorization server.
  (https://docs.wso2.com/display/IS510/Configuring+a+Service+Provider)
 
 4) Then under the "configure inbound authentication" section, create an OAuth2 application which represents your
-client application. Instructions are available in the above documentation link. Once the OAuth2 application is created,
+client application. Instructions are available in the above documentation link. 
+
+For "Callback Url", provide "https://localhost:9443/oauth2/token"
+
+Once the OAuth2 application is created,
 you will get a pair of keys called OAuth Client Key and OAuth Client Secret.
 
 5) Execute following command from the installation directory to start the server.  e.g. /home/user/wso2is-5.1.0/
@@ -67,7 +71,7 @@ Use following cURL commands.
 ```
 curl -v -H "Authorization: Bearer <access_token>" http://localhost:8080/hello/john
 
-> GET /hello/sameera HTTP/1.1
+> GET /hello/john HTTP/1.1
 > Host: localhost:8080
 > User-Agent: curl/7.43.0
 > Accept: */*