Merge pull request #56 from vtex/documentation/improvements

Documentation/improvements

Author: Caldas

README.md

@@ -1,16 +1,19 @@
 # SplunkLogger
-This is a C# .Net Core 2 Splunk ILogger implementation developed at **VTEX** to send log to **Splunk**
 
-| Package Name                   | Release |
-|--------------------------------|-----------------|
-| `SplunkLogger`         | [![NuGet](https://img.shields.io/nuget/v/SplunkLogger.svg)](https://www.nuget.org/packages/SplunkLogger/) |
-
-It was developed to be integrated to .Net Core 2 logging abstractions.
+This is a C# .Net Core 2 ILogger implementation developed by **VTEX** developer [Caldas](https://github.com/Caldas) to send data to Splunk.
 
 ### Features
 
-* ILoggers **HEC** (*Raw* and *Json*) and **Socket** (*TCP* and *UDP*)
-* Batch Manager class (Improve **Splunk** *HEC* performance sending data as batch)
+* Multiples ILoggers to send data via **Http** or **Socket**
+  * **Http** loggers available to send data via **Raw** or **Json** routes
+  * **Socket** loggers available to send data via **TCP** or **UDP**
+* Send **Http** events as batch (Improve **Splunk** *HEC* performance sending data as batch)
+
+### NuGet Package Status
+
+| Package Name                   | Release |
+|--------------------------------|-----------------|
+| `SplunkLogger`         | [![NuGet](https://img.shields.io/nuget/v/SplunkLogger.svg)](https://www.nuget.org/packages/SplunkLogger/) |
 
 ## Usage
 
@@ -19,103 +22,133 @@ Add *SplunkLogger* nuget library
 PM> Install-Package SplunkLogger
 ```
 
-Initialize a new *SplunkLoggerConfiguration* and the logger provider at **Configure** method at **Startup** class:
+### Configure Logger
 
+Let's say for instance that you are creating a WebAPI project, so the first step is to configure one of the Splunk loggers options:
 ```csharp
-static readonly ILoggerFormatter formatter = null;
-
 public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
 {
-    var splunkConfiguration = new SplunkLoggerConfiguration()
-    {
-        HecConfiguration = new HECConfiguration()
-        {
-            SplunkCollectorUrl = "https://localhost:8088/services/collector",
-            Token = "753c5a9c-fb59-4da0-9064-947f99dc20ba"
-        }
-    };
-    loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter);
-    app.UseMvc();
+    var splunkLoggerConfiguration = GetSplunkLoggerConfiguration(app);
+    
+    //Append Http Raw logger 
+    //loggerFactory.AddHECRawSplunkLogger(splunkLoggerConfiguration);
+    
+    //Append Http Json logger
+    loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration);
+    
+    //Append Socket TCP logger
+    //loggerFactory.AddTcpSplunkLogger(splunkConfiguration);
+    
+    //Append Socket UDP logger
+    //loggerFactory.AddUdpSplunkLogger(splunkConfiguration);
 }
 ```
 
-The case above is using a **Splunk** *HEC Raw* logger without any custom formatter as log provider.
+As you can see, no matter what is your option you always must delivery a *SplunkLoggerConfiguration* when adding a ILogger to the logger factory. You can provide it via config or as hard code:
 
-Now, in your controller you can log normally, for instance:
+#### Get Configuration From Json File
 
-```csharp
-[Route("api/[controller]")]
-public class ValuesController : Controller
-{
-    readonly ILogger logger;
+You can provide the configuration from json file using .Net Core 2 configuration binding feature. 
 
-    public ValuesController(ILoggerFactory loggerFactory)
-    {
-        logger = loggerFactory.CreateLogger<ValuesController>();
-    }
+For instance at [SampleWebAPI project](https://github.com/vtex/SplunkLogger/tree/master/src/SampleWebAPI) we use the *appsettings.json* file.
 
-    // GET api/values
-    [HttpGet]
-    public IEnumerable<string> Get()
-    {
-        logger.LogCritical(new EventId(-1, "Values Controller"), new NotImplementedException(), "Error on GET api/values route");
-        return new string[] { "value1", "value2" };
+```json
+{
+  "Logging": {
+    "IncludeScopes": false,
+    "LogLevel": {
+      "Default": "Trace",
+      "System": "Debug",
+      "Microsoft": "Debug",
+      "Splunk": "Trace"
+    }
+  },
+  "Splunk": {
+    "HecConfiguration": {
+      "BatchIntervalInMilliseconds": 5000,
+      "BatchSizeCount": 10,
+      "ChannelIdType": "None",
+      "DefaultTimeoutInMiliseconds": 10000,
+      "SplunkCollectorUrl": "https://localhost:8088/services/collector/",
+      "Token": "753c5a9c-fb59-4da0-9064-947f99dc20ba",
+      "UseAuthTokenAsQueryString": false
+    },
+    "SocketConfiguration": {
+      "HostName": "localhost",
+      "Port": 4242
     }
+  }
 }
 ```
 
--------------------------------------------
-
-# VTEXSplunkLogger
-For us at **VTEX** we need more customized log entries at Splunk and also we need easier ways to call for log registration during the code. For that, we created this *VTEXSplunkLogger* library.
-
-This project contains all **VTEX** extra classes designed to ease logging. All classes changes .Net Core 2 log abstraction to a customized log entry at **Splunk**
-
-| Package Name                   | Release |
-|--------------------------------|-----------------|
-| `VTEXSplunkLogger` | [![MyGet](https://img.shields.io/myget/vtexlab/v/VTEXSplunkLogger.svg)](https://www.myget.org/feed/vtexlab/package/nuget/VTEXSplunkLogger) |
-
-### Features
-
-* ILoggerExtensions (*Allow easy log creation*)
-* LoggerFactoryExtensions (*Simplify loggerFactory add provider method call*)
-* VTEXSplunkLoggerFormatter (*Custom `ILoggerFormatter` which creates VTEX's custom text to Splunk*)
-
+If you intend to send data via **Http** you should set **HecConfiguration** section and if you choose to send data via socket you must set **SocketConfiguration** section.
 
-## Usage
+Now we need to configure SplunkLoggerConfiguration at dependency injection and indicate to use **Splunk** section from configuration file.
+```csharp
+/// <summary>
+/// This method gets called by the runtime. Use this method to add services to the container.
+/// </summary>
+public void ConfigureServices(IServiceCollection services)
+{
+    services.Configure<SplunkLoggerConfiguration>(Configuration.GetSection("Splunk"));
+    services.AddMvc();
+}
+```
 
-Add *VTEXSplunkLogger* nuget library
-```powershell
-PM> Install-Package VTEXSplunkLogger -Source https://www.myget.org/F/vtexlab/api/v3/index.json
+Now that `SplunkLoggerConfiguration` class is configured we can retrieve it by requesting `IOptions<SplunkLoggerConfiguration>` at dependency injection service, like:
+```csharp
+/// <summary>
+/// Demonstrate how can you provide configuration to your splunk logger addapter(s) 
+/// </summary>
+SplunkLoggerConfiguration GetSplunkLoggerConfiguration(IApplicationBuilder app)
+{
+    SplunkLoggerConfiguration result = null;
+    var splunkLoggerConfigurationOption = app.ApplicationServices.GetService<IOptions<SplunkLoggerConfiguration>>();
+    if(splunkLoggerConfigurationOption != null && splunkLoggerConfigurationOption.Value != null)
+        result = app.ApplicationServices.GetService<IOptions<SplunkLoggerConfiguration>>().Value;
+    return result;
+}
 ```
 
-Initialize a new *SplunkLoggerConfiguration* and the logger provider at **Configure** method at **Startup** class:
+#### Get Static Configuration
 
-```csharp
-static readonly ILoggerFormatter formatter = new VTEXSplunkLoggerFormatter();
+If you don't want to use the configuration file, you can provide a hard coded configuration instance:
 
-public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+```csharp
+/// <summary>
+/// Demonstrate how can you provide configuration to your splunk logger addapter(s) 
+/// </summary>
+SplunkLoggerConfiguration GetSplunkLoggerConfiguration(IApplicationBuilder app)
 {
-    //TODO: Set your project name
-    ILoggerExtensions.SetApplication("ProjectX"); 
-    
-    var splunkConfiguration = new SplunkLoggerConfiguration()
+    SplunkLoggerConfiguration result = new SplunkLoggerConfiguration()
     {
         HecConfiguration = new HECConfiguration()
         {
             SplunkCollectorUrl = "https://localhost:8088/services/collector",
+            BatchIntervalInMilliseconds = 5000,
+            BatchSizeCount = 100,
+            ChannelIdType = HECConfiguration.ChannelIdOption.None,
             Token = "753c5a9c-fb59-4da0-9064-947f99dc20ba"
+        },
+        SocketConfiguration = new SocketConfiguration()
+        {
+            HostName = "localhost",
+            Port = 8111
         }
     };
-    loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter);
-    app.UseMvc();
+    return result;
 }
 ```
 
-```csharp
-using Vtex;
-// other usings ..
+Again, if you intend to use send data via **Http** you should set **HecConfiguration** property and if you choose to send data via socket you must set **SocketConfiguration** property.
+ 
+### Logging 
 
+Now that everything is configured and ILoggerFactory already have the desired ILogger instance added you can log your messages.
+
+Here is a sample of how you can log messages, in this case I'm logging a `NotImplementedException` at [SampleWebAPI project](https://github.com/vtex/SplunkLogger/tree/master/src/SampleWebAPI) `ValuesController`.
+
+```csharp
 [Route("api/[controller]")]
 public class ValuesController : Controller
 {
@@ -130,13 +163,16 @@ public class ValuesController : Controller
     [HttpGet]
     public IEnumerable<string> Get()
     {
-        logger.DefineVTEXLog(LogLevel.Critical, 
-                             "Values Controller", 
-                             "api/values", 
-                             string.Empty, 
-                             new NotImplementedException(), 
-                             new Tuple<string, string>("method", "GET"));
+        logger.LogCritical(new EventId(-1, "Values Controller"), new NotImplementedException(), "Error on GET api/values route");
         return new string[] { "value1", "value2" };
     }
 }
 ```
+
+## More Information
+
+You can read more about the projects and it's details (like send http events as batch) at [Wiki page](https://github.com/vtex/SplunkLogger/wiki)
+
+## Project Sponsored By
+
+![VTEX](https://raw.githubusercontent.com/vtex/SplunkLogger/documentation/improvements/VTEX_icon.png) **[VTEX](https://www.vtex.com)** 

VTEX_icon.png

@@ -0,0 +1,3 @@
+# Sample WebAPI Project
+
+This folder contains a sample WebAPI project that uses SplunkLogger library to send data to **Splunk**

src/SampleWebAPI/README.md

@@ -0,0 +1,3 @@
+# SplunkLogger Library
+
+This folder contains the SplunkLogger library