Update logging Rest API
[platform-oam.git] / logging-rest-library / src / main / java / README.md
1
2 ==================================
3 Logging Library Developer Guide
4 ==================================
5 What is Logging Library?
6 =======================
7
8 Logging Library has the following given below features :
9
10 There are two .java(ACUMOSLogConstants and LogConfig.java) files and one logback.xml file is there.
11
12 1.In the ACUMOSLogConstants.java following  given below features are there.
13 Marker
14 ====================
15 Marker is a spacial class  has the given below features.
16
17 Java logging frameworks allow you to filter log messages based on the logger name and the message log level.You can tag your
18 log messages with user-defined markers in order to filter them later on.
19
20 Markers are named objects used to enrich log statements. Conforming logging system Implementations of SLF4J determine how
21 information conveyed by markers are used, if at all. In particular, many conforming logging systems ignore marker data.
22 For this example, we will be using Logback as logger with SLF4J.Logback was conceived and created as a successor to Log4J.
23 Logback supports markers for the logging calls. These Markers allow association of tags with log statements. 
24
25 Marker has following given below attributes as INVOKE,INVOKE_RETURN,INVOKE_SYNCHRONOUS,INVOKE_ASYNCHRONOUS,ENTRY & EXIT
26 ,User can select any of the attribute as per his choice.
27
28 MDC
29 =====
30
31 The MDC manages contextual information on a per thread basis. Typically, while starting to service a new client request,
32 the developer will insert pertinent contextual information, such as the client id, client's IP address, request parameters
33 etc. into the MDC.Logback components, if appropriately configured, will automatically include this information in each log
34 entry.
35
36 MDC in Log4j allows us to fill a map-like structure with pieces of information that are accessible to the appender when 
37 the log message is actually written.The MDC structure is internally attached to the executing thread in the same way a 
38 ThreadLocal variable would be.
39
40 And so, the high level idea is:to fill the MDC with pieces of information that we want to make available to the appender
41 then log a message and finally, clear the MDC.
42
43 Most server applications need to handle multiple clients simultaneously. Typically, the server application allocates a 
44 separate thread to handle a single client request. In such a system different threads handle different client requests 
45 in parallel and the log messages written by the threads interleave. In order to differentiate log messages from different
46 threads from each other a diagnostic context comes in handy.Diagnostic context is a map associated with a particular thread.
47 Each thread maintains its own map. You can store arbitrary key-value pairs in the map and in turn lay out your log messages 
48 to include the values from the map.
49
50 MDC has following given below attributes as REQUEST_ID,TARGET_SERVICE_NAME,TARGET_ENTITY,CLIENT_IP_ADDRESS,SERVER_FQDN,
51 RESPONSE_CODE,RESPONSE_DESCRIPTION,RESPONSE_SEVERITY & STATUS_CODE,User can select any of the attribute as per his choice.
52
53 We have two (1- MDC, and 2 - MDCs )
54 New MDCs are added to serve more better way for ResponseStatusMDC and ResponseSeverityMDC of MDCs.
55 It will be useful in logging the thread requests/responses.
56 For more information we have added thread specific ResponseStatusMDC  which has three attributes as  MDC_COMPLETED,  MDC_ERROR 
57 &  MDC_INPROGRESS, user can select one of these attributes in logging statements like below:
58 public enum ResponseStatusMDC {
59                      
60                      MDC_COMPLETED,
61                      MDC_ERROR,
62                      MDC_INPROGRESS
63 }
64 Also for thread specific MDC had added ResponseSeverityMDC  which has six attributes as MDC_INFO,  MDC_ERROR,  MDC_TRACE,
65  MDC_DEBUG, MDC_WARN, MDC_FATAL.user can select one of these attributes in logging statements.
66   public enum ResponseSeverityMDC
67 {    MDC_INFO,    MDC_ERROR,    MDC_TRACE,    MDC_DEBUG,    MDC_WARN,    MDC_FATAL   }
68
69 Implementation of MDC 
70 =====================
71 How MDC are called externally from other project through the method setEnteringMDCs in LogConfig.java.
72 MDC is used for thread specific request so we just call this method setEnteringMDCs().
73
74                 MDC.put(MDCs.REQUEST_ID, requestId);            
75                 MDC.put(MDCs.TARGET_ENTITY, targetEntry);
76                 MDC.put(MDCs.TARGET_SERVICE_NAME, targetService);
77                 MDC.put(MDCs.CLIENT_IP_ADDRESS, ip);
78                 MDC.put(MDCs.SERVER_FQDN, hostname);
79                 MDC.put(MDCs.USER, user);
80
81 In this method setEnteringMDCs() we write the given below lines for the specific thread.
82
83 Also whatever parameters we pass as responseCode & responseSeverity in
84 setEnteringMDCs(String targetEntry,String targetService,String user,String responseCode,String responseSeverity) method.
85
86 There are conditions according to whatever ResponseStatusMDC & ResponseSeverityMDC you want to implement in logging statements
87 that will be printed in your logging statements with the help of given below statements as :
88
89 For example if you pass responseCode as MDC_COMPLETED then  given below lines will be printed in your logging statements.
90 MDC.put(MDCs.RESPONSE_DESCRIPTION, MDCs.ResponseStatusMDC.MDC_COMPLETED.toString());
91
92 And For example if you pass responseSeverity as MDC_INFO then  given below lines will be printed in your logging statements.
93 MDC.put(MDCs.RESPONSE_SEVERITY, MDCs.ResponseSeverityMDC.MDC_INFO.toString());
94         
95
96 Header
97 =======
98 In this class there is one attribute as REQUEST_ID whose value is X-ACUMOS-RequestID.
99
100 ResponseStatus enumeration
101 ==========================
102 In this enumeration there are three types of Response Status as COMPLETED,ERROR,INPROGRESS.The end user can choose any of the
103 response attribute as per his choice.
104
105 ResponseSeverity enumeration:
106 =============================
107 In this enumeration there are five types of Response Severity is given as :INFO,ERROR,TRACE,DEBUG,WARN,FATAL.The end user can
108 choose any of the response severity attribute as per his choice.
109
110 InvocationMode enumeration
111 ==========================
112 Invocation mode can be SYNCHRONOUS or ASYNCHRONOUS as per the user requirement.
113
114 2.Another File is the LogConfig.java
115 ====================================
116 In this file there is a static method as LogConfig.setEnteringMDCs(String targetEntry,String targetService,String user,String responseCode,String responseSeverity)
117 The user puts the entries in HashMap in the given below format.
118
119                 MDC.put(MDCs.REQUEST_ID, requestId);            
120                 MDC.put(MDCs.TARGET_ENTITY, targetEntry);
121                 MDC.put(MDCs.TARGET_SERVICE_NAME, targetService);
122                 MDC.put(MDCs.CLIENT_IP_ADDRESS, ip);
123                 MDC.put(MDCs.SERVER_FQDN, hostname);
124                 MDC.put(MDCs.USER, user);
125 Where responseCode & responseSeverity the user will pass whatever thread specific ResponseStatusMDC     & ResponseSeverityMDC he wants 
126 to implement in the logging statements. 
127                 MDC.put(MDCs.RESPONSE_DESCRIPTION, MDCs.ResponseStatusMDC.MDC_COMPLETED.toString());
128                 MDC.put(MDCs.RESPONSE_SEVERITY, MDCs.ResponseSeverityMDC.MDC_INFO.toString());
129                 
130 Here the targetEntry is the maven project module name for example in maven project elk-client the targetEntry name is
131 elk-client.
132
133 Here the targetEntry is end point url of the rest api method which we want to access.For example to fetch all the indices of 
134 elastic search we define end point url of the reat api as /all/indices in the ElkClientConstants.GET_ALL_INDICES and
135 define GET_ALL_INDICES whose value is /all/indices in the ElkClientConstants.java file. 
136
137 Here the user is the who login into the web application and accessing the particular maven project module.
138
139 3.Logback.xml
140 =============
141 We have defined various appenders while help in creating the log statements.With the help of these appenders we can print
142 the logs as per user requirement.
143
144 ================================================
145 Testing Logging Library Developer Guide
146 ================================================
147 What is Logging Library Testing Rest API?
148 ================================================
149 1.Rest API Test.
150 =============================
151 We have created logging-rest-demo project, in this project we are importing the logging-demo jar so we will import all the
152 functionality & various features of the logging-demo project through the logging-demo jar.
153 We have created some Rest API methods in the test project logging-rest-demo in that we are implementing the different different
154 features of the logging-demo project.
155
156 How to implement the Logging Library jar?
157 ========================================= 
158
159 To implement the Logging Library jar,there are some few specific given below guidelines which the developer should use while
160 implementing the logging-demo jar.
161
162 1.In the starting of the implemented REST API method first use the line from the Logging Library jar as 
163  LogConfig.setEnteringMDCs(String targetEntry, String targetService, String user, String responseCode,String responseSeverity)
164
165 Where the targetEntry is your maven module name,targetService is the REST API url of the exposed method,user is who has login
166 into the system,responseCode is the ResponseStatusMDC and responseSeverity is the ResponseSeverityMDC,you can choose any values
167 out of the values given in the ResponseStatusMDC & ResponseSeverityMDC.
168
169 2.Then use the particular log levels like debug,error,info,fatal,warn etc whatever you want to implement in your logging statements.
170
171 3.Suppose you want to enrich the logs with some particular Marker then for this first initialize the MarkerFactory.getIMarkerFactory();
172 Then use the line as logger.error(MarkerFactory.getMarker(markerInputVal), "This is a serious an User Input Marker error requiring the admin's attention",new Exception("Just testing")); 
173 where markerInputVal is the particular marker which you want to use in your application.
174
175 4.In the end of the implemented REST API method use the line LogConfig.clearMDCDetails() to clear all the log MDC details.
176
177 Steps to include logging-demo.jar in your project.
178 ==================================================
179
180 Logging Library is provided in the form of as a jar,Suppose we want to add this logging-demo.jar to a new project then given
181 below are the steps to in guide this jar and use in your project.
182
183 1.Add the given below entry in dependency section of the pom.xml of your new project.
184                 <dependency>
185                         <groupId>org.acumos.platform-oam</groupId>
186                         <artifactId>logging-demo</artifactId>
187                         <version>3.0.4-SNAPSHOT</version>
188                 </dependency>
189                 
190 2.Publish the logging-demo.jar into the maven repository.
191                 
192 3.Now Suppose you want to add logging related statements in your java files then just you need to write the logger.Debug_levels
193 as per your requirement, like debug,error,fatal,info,warn.
194
195 4.Whatever logging functionality you want in your logging statements as per your requirement,you can just import from the 
196 classes files of the jar.
197
198
199 You will import the appropriate,required  and use it your project as per the end user requirement.To see how you can use the
200 logging-demo library ,you can refer to the above section Logging Library Developer Guide.
201
202
203
204
205
206
207