Skip to content

Commit 596be44

Browse files
CaldasCaldas
authored
Update README #32 
1 parent bb7e940 commit 596be44

1 file changed

Lines changed: 108 additions & 78 deletions

File tree

‎README.md‎

Lines changed: 108 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
# SplunkLogger
2-
This is a C# .Net Core 2 Splunk ILogger implementation developed at **VTEX** to send log to **Splunk**
2+
This is a C# .Net Core 2 ILogger implementation developed by **VTEX** developer (@[Caldas](https://github.com/Caldas)) to send data to Splunk.
33

4-
| Package Name | Release |
5-
|--------------------------------|-----------------|
6-
| `SplunkLogger` | [![NuGet](https://img.shields.io/nuget/v/SplunkLogger.svg)](https://www.nuget.org/packages/SplunkLogger/) |
4+
### Features
75

8-
It was developed to be integrated to .Net Core 2 logging abstractions.
6+
* Multiples ILoggers to send data via **Http** or **Socket**
7+
* **Http** loggers available to send data via **Raw** or **Json** routes
8+
* **Socket** loggers available to send data via **TCP** or **UDP**
9+
* Send **Http** events as batch (Improve **Splunk** *HEC* performance sending data as batch)
910

10-
### Features
11+
### NuGet Package Status
1112

12-
* ILoggers **HEC** (*Raw* and *Json*) and **Socket** (*TCP* and *UDP*)
13-
* Batch Manager class (Improve **Splunk** *HEC* performance sending data as batch)
13+
| Package Name | Release |
14+
|--------------------------------|-----------------|
15+
| `SplunkLogger` | [![NuGet](https://img.shields.io/nuget/v/SplunkLogger.svg)](https://www.nuget.org/packages/SplunkLogger/) |
1416

1517
## Usage
1618

@@ -19,103 +21,132 @@ Add *SplunkLogger* nuget library
1921
PM> Install-Package SplunkLogger
2022
```
2123

22-
Initialize a new *SplunkLoggerConfiguration* and the logger provider at **Configure** method at **Startup** class:
24+
### Configure Logger
2325

26+
Let's say for instance that your are creating a WebAPI project, so the first step is to configure one of the Splunk loggers options
2427
```csharp
25-
static readonly ILoggerFormatter formatter = null;
26-
2728
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
2829
{
29-
var splunkConfiguration = new SplunkLoggerConfiguration()
30-
{
31-
HecConfiguration = new HECConfiguration()
32-
{
33-
SplunkCollectorUrl = "https://localhost:8088/services/collector",
34-
Token = "753c5a9c-fb59-4da0-9064-947f99dc20ba"
35-
}
36-
};
37-
loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter);
38-
app.UseMvc();
30+
var splunkLoggerConfiguration = GetSplunkLoggerConfiguration(app);
31+
32+
//Append Http Raw logger
33+
//loggerFactory.AddHECRawSplunkLogger(splunkLoggerConfiguration);
34+
35+
//Append Http Json logger
36+
loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration);
37+
38+
//Append Socket TCP logger
39+
//loggerFactory.AddTcpSplunkLogger(splunkConfiguration);
40+
41+
//Append Socket UDP logger
42+
//loggerFactory.AddUdpSplunkLogger(splunkConfiguration);
3943
}
4044
```
4145

42-
The case above is using a **Splunk** *HEC Raw* logger without any custom formatter as log provider.
46+
As you can see, no matter what is your option you always must delivery a *SplunkLoggerConfiguration* that can be provided by two ways:
4347

44-
Now, in your controller you can log normally, for instance:
48+
#### Get Configuration From Json File
4549

46-
```csharp
47-
[Route("api/[controller]")]
48-
public class ValuesController : Controller
49-
{
50-
readonly ILogger logger;
50+
First, and most beautiful one.
5151

52-
public ValuesController(ILoggerFactory loggerFactory)
53-
{
54-
logger = loggerFactory.CreateLogger<ValuesController>();
55-
}
52+
You can provide the configuration from json file. In this case I will be using *appsettings.json* as source and loading it using .Net Core 2 configuration binding feature.
5653

57-
// GET api/values
58-
[HttpGet]
59-
public IEnumerable<string> Get()
60-
{
61-
logger.LogCritical(new EventId(-1, "Values Controller"), new NotImplementedException(), "Error on GET api/values route");
62-
return new string[] { "value1", "value2" };
54+
So first, let's check the json file.
55+
```json
56+
{
57+
"Logging": {
58+
"IncludeScopes": false,
59+
"LogLevel": {
60+
"Default": "Trace",
61+
"System": "Debug",
62+
"Microsoft": "Debug",
63+
"Splunk": "Trace"
6364
}
65+
},
66+
"Splunk": {
67+
"HecConfiguration": {
68+
"BatchIntervalInMilliseconds": 5000,
69+
"BatchSizeCount": 10,
70+
"ChannelIdType": "None",
71+
"DefaultTimeoutInMiliseconds": 10000,
72+
"SplunkCollectorUrl": "https://localhost:8088/services/collector/",
73+
"Token": "753c5a9c-fb59-4da0-9064-947f99dc20ba",
74+
"UseAuthTokenAsQueryString": false
75+
},
76+
"SocketConfiguration": {
77+
"HostName": "localhost",
78+
"Port": 4242
79+
}
80+
}
6481
}
6582
```
6683

67-
-------------------------------------------
68-
69-
# VTEXSplunkLogger
70-
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.
71-
72-
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**
73-
74-
| Package Name | Release |
75-
|--------------------------------|-----------------|
76-
| `VTEXSplunkLogger` | [![MyGet](https://img.shields.io/myget/vtexlab/v/VTEXSplunkLogger.svg)](https://www.myget.org/feed/vtexlab/package/nuget/VTEXSplunkLogger) |
84+
If you intend to use send data via **Http** you should set **HecConfiguration** section and if you choose to send data via socket you must set **SocketConfiguration** section.
7785

78-
### Features
79-
80-
* ILoggerExtensions (*Allow easy log creation*)
81-
* LoggerFactoryExtensions (*Simplify loggerFactory add provider method call*)
82-
* VTEXSplunkLoggerFormatter (*Custom `ILoggerFormatter` which creates VTEX's custom text to Splunk*)
83-
84-
85-
## Usage
86+
Now we need to configure SplunkLoggerConfiguration and indicate to use **Splunk** section from configuration file.
87+
```csharp
88+
/// <summary>
89+
/// This method gets called by the runtime. Use this method to add services to the container.
90+
/// </summary>
91+
public void ConfigureServices(IServiceCollection services)
92+
{
93+
services.Configure<SplunkLoggerConfiguration>(Configuration.GetSection("Splunk"));
94+
services.AddMvc();
95+
}
96+
```
8697

87-
Add *VTEXSplunkLogger* nuget library
88-
```powershell
89-
PM> Install-Package VTEXSplunkLogger -Source https://www.myget.org/F/vtexlab/api/v3/index.json
98+
Now that `SplunkLoggerConfiguration` class is configured we can retrieve it by requesting `IOptions<SplunkLoggerConfiguration>` at dependency injection service, like:
99+
```csharp
100+
/// <summary>
101+
/// Demonstrate how can you provide configuration to your splunk logger addapter(s)
102+
/// </summary>
103+
SplunkLoggerConfiguration GetSplunkLoggerConfiguration(IApplicationBuilder app)
104+
{
105+
SplunkLoggerConfiguration result = null;
106+
var splunkLoggerConfigurationOption = app.ApplicationServices.GetService<IOptions<SplunkLoggerConfiguration>>();
107+
if(splunkLoggerConfigurationOption != null && splunkLoggerConfigurationOption.Value != null)
108+
result = app.ApplicationServices.GetService<IOptions<SplunkLoggerConfiguration>>().Value;
109+
return result;
110+
}
90111
```
91112

92-
Initialize a new *SplunkLoggerConfiguration* and the logger provider at **Configure** method at **Startup** class:
113+
#### Get Static Configuration
93114

94-
```csharp
95-
static readonly ILoggerFormatter formatter = new VTEXSplunkLoggerFormatter();
115+
You can also provide a hard coded configuration instance:
96116

97-
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
117+
```csharp
118+
/// <summary>
119+
/// Demonstrate how can you provide configuration to your splunk logger addapter(s)
120+
/// </summary>
121+
SplunkLoggerConfiguration GetSplunkLoggerConfiguration(IApplicationBuilder app)
98122
{
99-
//TODO: Set your project name
100-
ILoggerExtensions.SetApplication("ProjectX");
101-
102-
var splunkConfiguration = new SplunkLoggerConfiguration()
123+
SplunkLoggerConfiguration result = new SplunkLoggerConfiguration()
103124
{
104125
HecConfiguration = new HECConfiguration()
105126
{
106127
SplunkCollectorUrl = "https://localhost:8088/services/collector",
128+
BatchIntervalInMilliseconds = 5000,
129+
BatchSizeCount = 100,
130+
ChannelIdType = HECConfiguration.ChannelIdOption.None,
107131
Token = "753c5a9c-fb59-4da0-9064-947f99dc20ba"
132+
},
133+
SocketConfiguration = new SocketConfiguration()
134+
{
135+
HostName = "localhost",
136+
Port = 8111
108137
}
109138
};
110-
loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter);
111-
app.UseMvc();
139+
return result;
112140
}
113141
```
114142

115-
```csharp
116-
using Vtex;
117-
// other usings ..
143+
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.
144+
145+
### Sample Logging
146+
147+
At controller you must receive `ILoggerFactory loggerFactory` and extract `ILogger`from it and use this `ILogger` instance to log any desired event, as sample below:
118148

149+
```csharp
119150
[Route("api/[controller]")]
120151
public class ValuesController : Controller
121152
{
@@ -130,13 +161,12 @@ public class ValuesController : Controller
130161
[HttpGet]
131162
public IEnumerable<string> Get()
132163
{
133-
logger.DefineVTEXLog(LogLevel.Critical,
134-
"Values Controller",
135-
"api/values",
136-
string.Empty,
137-
new NotImplementedException(),
138-
new Tuple<string, string>("method", "GET"));
164+
logger.LogCritical(new EventId(-1, "Values Controller"), new NotImplementedException(), "Error on GET api/values route");
139165
return new string[] { "value1", "value2" };
140166
}
141167
}
142168
```
169+
170+
### Sending Http Events As Batchs
171+
172+
**To Be Definied**

0 commit comments

Comments
 (0)