Add files via upload

vishalratna-microsoft · web-flow · commit 6ac862a3e9fa · 2021-12-17T21:48:39.000+05:30
diff --git a/README.md b/README.md
@@ -1,8 +1,11 @@
 ﻿
+
 # Snippet  
   
-> Snippet is a extensible android library to measure execution times of the code sections  in a way that does not compromise with the readability and can be shipped to production without any additional setup. > New behaviours can be added in the library by extending `MeasuredExecutionPath` - The code path the does the measurement code spans `ReleaseExecutionPath` - A no-op path (default path) that is usually installed in the release variants.  
->  
+`Snippet` is an extensible android library to measure execution times of the code sections  in a way that does not compromise with the readability and can be shipped to production without any additional setup. New behaviours can be added in the library by extending Execution paths. 2 execution paths provided with the library are:
+ 1. `MeasuredExecutionPath` - The code path the does the measurement code spans
+ 2. `ReleaseExecutionPath` - A no-op path (default path) that is usually installed in the release variants.  
+
   
 # Features  
   
@@ -35,8 +38,8 @@ Setup in 3 easy steps:
 **Below is the sample setup code:**  
   
 
-     if(BuildConfig.DEBUG) { 
-	Snippet.install(new Snippet.MeasuredExecutionPath());      
+    if(BuildConfig.DEBUG) { 
+		Snippet.install(new Snippet.MeasuredExecutionPath());      
         Snippet.newFilter("SampleFilter");      
         Snippet.addFlag(Snippet.FLAG_METADATA_LINE | Snippet.FLAG_METADATA_THREAD_INFO);      
     }   
@@ -45,17 +48,16 @@ Setup in 3 easy steps:
   
 > There are 3 ways to capture the code path.  
   
-1. `Snippet.capture(Closure closure)` - For continuous section of code, pass code as lambda inside  
-   the closure.  
-2. `Snippet.startCapture()/LogToken.endCapture()` - For non contiguous sections of code possibly  
-   inside the same file . Or places where `capture(closure)` does not work as in case of some  
-   anonymous inner classes.  
-3. `Snippet.startCapture(String tag)/Snippet.find(tag).endCapture()` - For code flows spanning over  
+1. `Snippet.capture(Closure closure)` - For continuous section of code, pass code as lambda inside  the closure.  
+
+2. `Snippet.startCapture()/LogToken.endCapture()` - For non contiguous sections of code possibly inside the same file . Or places where `capture(closure)` does not work as in case of some anonymous inner classes.  
+
+4. `Snippet.startCapture(String tag)/Snippet.find(tag).endCapture()` - For code flows spanning over  
    multiple files. ex. you have started a measurement in `Application.onCreate()` and end the  
    measurement on the landing activity. Use `Snippet.startCapture(tag)` to start the measurement and  
    find the token using `Snippet.find(tag)` and call `endCapture()` on that.  
   
-> Use case 1: Code that can be passed as lambda.  
+**Use case 1:** Code that can be passed as lambda.
   
 
     @Override  
@@ -69,10 +71,9 @@ Setup in 3 easy steps:
         Snippet.capture(()-> super.onCreate(savedInstanceState)); 
     }
 
-  
-> Use case 2: Measurement starts from a different class and ends in a  
-> different class. Below the measurement has started in Application  
-> class and will end in an Activity class  
+**Use case 2:** Measurement starts from a different class and ends in a  
+different class. 
+Below the measurement has started in Application class and will end in an Activity class. We use TAG based API to handle this case.  
   
 
       public class SampleApplication extends Application {  
@@ -89,7 +90,7 @@ Setup in 3 easy steps:
       }  
     }
         
-End the measurement in `MainActivity` class
+and ended in `MainActivity` class
 
     public class MainActivity extends AppCompatActivity {  
 
@@ -105,9 +106,12 @@ End the measurement in `MainActivity` class
             super.onStart();  
         }  
     }
+    
+**Use case 3:** Using Log Tokens. Log tokens can be used within a class or method easily. 
 
-> Use case 3: Using Log Tokens. Log tokens can be used within a class or method easily. If you need to use log tokens across multiple files, it would be difficult try using tags.
- 
+If you need to use log tokens to measure code spread across multiple files and your measurements do not deal with multiple threads, use TAG based API discussed above. 
+
+**LogTokens** will shine if you need to fire multiple threads at the same time and measurement is inside the common code that all the threads execute. Then create separate log token and hand over to different threads. We are working to fix this limitation.
 
      public class MainActivity extends AppCompatActivity {        
             
@@ -125,29 +129,23 @@ End the measurement in `MainActivity` class
           }  
       
 
-> The measurements looks like below all the specified information is  
-> captured out of the box.  
-  
+Snippet capture all the context information such as class, method, thread, line number out of the box and creates pretty logs as shown below. So that you can locate your logs easily. 
+On top of that if you need more verbosity, then each API has a string based overload too. You can explore that also.
  
-
     2021-12-11 15:11:24.197 11400-11400/com.microsoft.sample D/SampleFilter: [Class = MainActivity]|::::|[Method = onCreate]|::::|<Line no. 21>|::::|[Thread name = main]|::::||::::|(18 ms) 
     2021-12-11 15:11:24.376 11400-11400/com.microsoft.sample D/SampleFilter: Time to set the content view|::::|[Class = MainActivity]|::::|[Method = onCreate]|::::|<Line no. 29>|::::|[Thread name = main]|::::||::::|(178 ms) 
     2021-12-11 15:11:24.377 11400-11400/com.microsoft.sample D/SampleFilter: [Class = MainActivity]|::::|[Method = onCreate]|::::|<Line no. 32>|::::|[Thread name = main]|::::||::::|(295 ms)  
 
-We can create multiple execution path implementations by extending MeasuredExecutionPath classes,  
-and do additional work with the data that is provided by the measured path such as logging it in  
-remote servers, putting all the data to a DB, files etc. Check `FileExecutionPath` in the sample  
-app.  
+We can create multiple execution path implementations by extending MeasuredExecutionPath classes,  and do customised work with the data that is provided by the measured path such as logging it in remote servers, putting all the data to a DB, files etc. Check `FileExecutionPath` in the sample  app.  
   
-Check out the sample app in `app/` to see it in action.  
+Check out the sample app in `app/` to see the process in action.  
   
 ## Splits  
   
-**Splits** can be defined as a logical span of code within a capture. Splits can span within same  
-file or different files. The purpose is to double down on the focussed areas, and help in debugging.  
-It could be used for seeing what is the contribution of a small portion of code within a capture and  
-find of problem areas.    
-**It is advisable to always use splits only for debugging purposes.** **It is not advised to ship splits related code to production.** **How to use splits**  
+**Splits** can be defined as a logical span of code within a capture. Splits can span within same file or different files. The purpose is to double down on the focussed areas, and help in debugging.  
+It could be used for seeing what is the contribution of a small portion of code within a capture and  find of problem areas.    
+
+**It is advisable to always use splits only for debugging purposes.** **It is not advised to ship splits related code to production.** **Below is the demo on how to use splits**  
   
 1. Once you get a log token using `Snippet.startCapture()` call.  
 2. You can call `logtoken.addSplit()` call. It will print the amount of time that has passed since  
@@ -162,8 +160,7 @@ find of problem areas.
 ## ThreadLocks  
   
 Thread lock is the functionality where the thread that started the measurement  
-using `startCapture()` could only end it. If other thread tries to do that, an error is logged and  
-action is skipped. It can be enabled easily like this  
+using `startCapture()` could only end it. If other thread tries to do that, an error is logged and action is skipped. It can be enabled easily like this  
   
 Snippet.startCapture().enableThreadLock()  
   
@@ -174,30 +171,27 @@ Snippet.startCapture().enableThreadLock()
 * may want to add some extra information into the existing information and add it to files.  
 * We can plugin a custom execution path or method through `Snippet.install(executionPath)` method.  
   
-Snippet comes with a `MeasuredExecutionPath` & `ReleaseExecutionPath` , measured path is the one  
-that routes the the Snippet API calls to the core library functionality, but `ReleaseExecutionPath`  
-make Snippet no-op. Release path is the default path for Snippet. User has to set the path for  
-specific build types using `Snippet.install(executionPath)`  
+Snippet comes with a `MeasuredExecutionPath` & `ReleaseExecutionPath` , measured path is the one that routes the the Snippet API calls to the core library functionality, and `ReleaseExecutionPath` make Snippet no-op. Release path is the default path for Snippet. User has to set the path for specific build types using `Snippet.install(executionPath)`  . Below is an example, where we set the `MeasuredExecutionPath` on DEBUG builds and `FileExecutionPath` on RELEASE builds.
   
-if(BuildConfig.DEBUG) { // For debug builds prints the measurements    
-Snippet.install(new Snippet.MeasuredExecutionPath()); Snippet.newFilter("SampleFilter");      
-} else {      
-// For release builds write the measurememnts to file.    
-Snippet.install(new FileExecutionPath()); Snippet.newFilter("ReleaseFilter");      
-}      
-Snippet.addFlag(Snippet.FLAG_METADATA_LINE | Snippet.FLAG_METADATA_THREAD_INFO);  
+
+    if(BuildConfig.DEBUG) {
+         Snippet.install(new Snippet.MeasuredExecutionPath());    
+         Snippet.newFilter("SampleFilter");      
+    } else {      
+         Snippet.install(new FileExecutionPath()); 
+         Snippet.newFilter("ReleaseFilter");      
+    }      
+    Snippet.addFlag(Snippet.FLAG_METADATA_LINE | Snippet.FLAG_METADATA_THREAD_INFO);  
+
   
 ## Writing a custom execution path  
   
 1. Extend `ExecutionPath`, in our example we will extend `MeasuredExecutionPath`.  
-2. Override `ExecutionPath#capture(Closure)` and  `ExecutionPath#capture(String, Closure)` This will  
-   make sure that you are implementing a custom code for lambda based API.  
-3. You need to provide a custom log token also and override the `LogToken#endCapture()`  
-  and `LogToken#endCapture(String)` so that you can perform the custom actions on all types(  
-   contiguous/non contiguous) of code.  
-4. For doing this extend ExtendableLogToken and override  `ExtendableLogToken#endCapture(String)`,  
-   and  `ExtendableLogToken#endCapture()`. Once done, return the `ExtendableLogToken` instance  
-   from  `Snippet#startCapture(String)`, and  `Snippet#startCapture(String)` methods.  
+
+2. Override `ExecutionPath#capture(Closure)` and  `ExecutionPath#capture(String, Closure)` This will make sure that you are implementing a custom code for lambda based API.  
+4. You need to provide a custom log token also and override the `LogToken#endCapture()`  and `LogToken#endCapture(String)` so that you can perform the custom actions on all types(contiguous/non contiguous) of code.  
+5. For doing this extend ExtendableLogToken and override  `ExtendableLogToken#endCapture(String)`,  
+   and  `ExtendableLogToken#endCapture()`. Once done, return the `ExtendableLogToken` instance from  `Snippet#startCapture(String)`, and  `Snippet#startCapture(String)` methods.  
   
 **NOTE**: In almost all the cases, every new execution path that would be created, would require a  new extension of `ExtendableLogToken`  
   
@@ -267,9 +261,10 @@ Snippet.addFlag(Snippet.FLAG_METADATA_LINE | Snippet.FLAG_METADATA_THREAD_INFO);
             ExecutionContext context = super.endCapture();      
             writeToFile(context);      
             return context;      
-         }      
-    }      
-}   
+          }      
+       }    
+    }     
+
 
 
 Finally, install it at the application create,  
@@ -284,22 +279,13 @@ Cheers,
   
 ## Contributing  
   
-This project welcomes contributions and suggestions. Most contributions require you to agree to a      
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us      
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.  
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.  
   
-When you submit a pull request, a CLA bot will automatically determine whether you need to  
-provide      
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the  
-instructions      
-provided by the bot. You will only need to do this once across all repos using our CLA.  
+When you submit a pull request, a CLA bot will automatically determine whether you need to  provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.  
   
 This project has adopted  
-the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).      
-For more information see  
-the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or      
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or  
-comments.  
+the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see  
+the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or      contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.  
   
 ## Trademarks  
   
@@ -327,3 +313,4 @@ dependencies {
     implementation 'com.github.microsoft:snippet-timekeeper:Tag'
 }
 ```
+
