Skip to content

Commit c9bc91e

Browse files
CaldasCaldas
authored
Merge pull request #16 from Caldas/feature/improve_documentation
Refactored VTEXSplunkLoggerFormatter Documented classes
2 parents 8e34c38 + 129ea05 commit c9bc91e

13 files changed

+184
-50
lines changed

‎src/SampleWebAPI/Logging/LoggerFactoryExtensions.cs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,26 +5,53 @@
55

66
namespace VTEX.SampleWebAPI
77
{
8+
/// <summary>
9+
///
10+
/// </summary>
811
public static class LoggerFactoryExtensions
912
{
13+
/// <summary>
14+
/// Add <see cref="T:Splunk.Providers.SplunkHECRawLoggerProvider"/> as provider to logger factory.
15+
/// </summary>
16+
/// <param name="loggerFactory">Logger factory.</param>
17+
/// <param name="configuration">Configuration.</param>
18+
/// <param name="formatter">Custom text formatter.</param>
1019
public static ILoggerFactory AddHECRawSplunkLogger(this ILoggerFactory loggerFactory, SplunkLoggerConfiguration configuration, ILoggerFormatter formatter)
1120
{
1221
loggerFactory.AddProvider(new SplunkHECRawLoggerProvider(configuration, formatter));
1322
return loggerFactory;
1423
}
1524

25+
/// <summary>
26+
/// Add <see cref="T:Splunk.Providers.SplunkHECJsonLoggerProvider"/> as provider to logger factory.
27+
/// </summary>
28+
/// <param name="loggerFactory">Logger factory.</param>
29+
/// <param name="configuration">Configuration.</param>
30+
/// <param name="formatter">Custom text formatter.</param>
1631
public static ILoggerFactory AddHECJsonSplunkLogger(this ILoggerFactory loggerFactory, SplunkLoggerConfiguration configuration, ILoggerFormatter formatter)
1732
{
1833
loggerFactory.AddProvider(new SplunkHECJsonLoggerProvider(configuration, formatter));
1934
return loggerFactory;
2035
}
2136

37+
/// <summary>
38+
/// Add <see cref="T:Splunk.Providers.SplunkTcpLoggerProvider"/> as provider to logger factory.
39+
/// </summary>
40+
/// <param name="loggerFactory">Logger factory.</param>
41+
/// <param name="configuration">Configuration.</param>
42+
/// <param name="formatter">Custom text formatter.</param>
2243
public static ILoggerFactory AddTcpSplunkLogger(this ILoggerFactory loggerFactory, SplunkLoggerConfiguration configuration, ILoggerFormatter formatter)
2344
{
2445
loggerFactory.AddProvider(new SplunkTcpLoggerProvider(configuration, formatter));
2546
return loggerFactory;
2647
}
2748

49+
/// <summary>
50+
/// Add <see cref="T:Splunk.Providers.SplunkUdpLoggerProvider"/> as provider to logger factory.
51+
/// </summary>
52+
/// <param name="loggerFactory">Logger factory.</param>
53+
/// <param name="configuration">Configuration.</param>
54+
/// <param name="formatter">Custom text formatter.</param>
2855
public static ILoggerFactory AddUdpSplunkLogger(this ILoggerFactory loggerFactory, SplunkLoggerConfiguration configuration, ILoggerFormatter formatter)
2956
{
3057
loggerFactory.AddProvider(new SplunkUdpLoggerProvider(configuration, formatter));

‎src/SampleWebAPI/Logging/VTEXEventLevel.cs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11

22
namespace VTEX.SampleWebAPI.Logging
33
{
4+
/// <summary>
5+
/// This enumeration represents the log event levels defined at VTEX.
6+
/// </summary>
47
public enum VTEXEventLevel : int
58
{
69
Critical = 3,

‎src/SampleWebAPI/Logging/VTEXLogType.cs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11

22
namespace VTEX.SampleWebAPI.Logging
33
{
4+
/// <summary>
5+
/// This enumeration represents the log types defined at VTEX.
6+
/// </summary>
47
public enum VTEXLogType
58
{
69
Error,

‎src/SampleWebAPI/Logging/VTEXSplunkEntry.cs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,44 @@
33

44
namespace VTEX.SampleWebAPI.Logging
55
{
6+
/// <summary>
7+
/// This class represents a VTEX log entry.
8+
/// </summary>
69
public class VTEXSplunkEntry
710
{
11+
/// <summary>
12+
/// Workflow type is a VTEX concept almost similar as `{EventId.Name}` concept.
13+
/// </summary>
814
public string WorkflowType { get; private set; }
15+
16+
/// <summary>
17+
/// Workflow instace is a VTEX concept almost similar as `{EventId.Id}` concept.
18+
/// </summary>
919
public string WorkflowInstance { get; private set; }
20+
21+
/// <summary>
22+
/// For which account this log happened.
23+
/// </summary>
1024
public string Account { get; private set; }
25+
26+
/// <summary>
27+
/// Exception to be logged.
28+
/// </summary>
1129
public Exception Exception { get; private set; }
30+
31+
/// <summary>
32+
/// Extra parameters that will be represented as `{Key}="{Value}"` entries at Splunk text message.
33+
/// </summary>
1234
public List<Tuple<string, string>> ExtraParameters { get; private set; }
1335

36+
/// <summary>
37+
/// Initializes a new instance of the <see cref="T:VTEX.SampleWebAPI.Logging.VTEXSplunkEntry"/> class.
38+
/// </summary>
39+
/// <param name="workflowType">Workflow type.</param>
40+
/// <param name="workflowInstance">Workflow instance.</param>
41+
/// <param name="account">Account.</param>
42+
/// <param name="exception">Exception.</param>
43+
/// <param name="extraParameters">Extra parameters.</param>
1444
public VTEXSplunkEntry(string workflowType, string workflowInstance, string account = "", Exception exception = null, params Tuple<string, string>[] extraParameters)
1545
{
1646
if (string.IsNullOrWhiteSpace(workflowType))

‎src/SampleWebAPI/Logging/VTEXSplunkEntryExtensions.cs‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,23 @@
44

55
namespace VTEX.SampleWebAPI
66
{
7+
/// <summary>
8+
/// This class contains ILogger extension method to simplify the process to record a VTEX log.
9+
/// </summary>
710
public static class VTEXSplunkEntryExtensions
811
{
912
static readonly EventId EmptyEventId = new EventId();
1013

14+
/// <summary>
15+
/// Log to Splunk.
16+
/// </summary>
17+
/// <param name="logger">Logger.</param>
18+
/// <param name="logLevel">Log level.</param>
19+
/// <param name="workflowType">Workflow type.</param>
20+
/// <param name="workflowInstance">Workflow instance.</param>
21+
/// <param name="account">Account.</param>
22+
/// <param name="exception">Exception.</param>
23+
/// <param name="extraParameters">Extra parameters.</param>
1124
public static void DefineVTEXLog(this ILogger logger, LogLevel logLevel, string workflowType, string workflowInstance, string account = "", Exception exception = null, params Tuple<string, string>[] extraParameters)
1225
{
1326
string formattedMessage = string.Empty;
@@ -29,4 +42,4 @@ public static void DefineVTEXLog(this ILogger logger, LogLevel logLevel, string
2942
});
3043
}
3144
}
32-
}
45+
}

‎src/SampleWebAPI/Logging/VTEXSplunkLoggerFormatter.cs‎

Lines changed: 72 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,45 @@
11
using System;
22
using System.Linq;
3+
using System.Net.Http;
4+
using System.Threading;
35
using Microsoft.Extensions.Logging;
46
using Splunk;
57

68
namespace VTEX.SampleWebAPI.Logging
79
{
10+
/// <summary>
11+
/// This class contains all methods to format a Log event into a VTEX standard text.
12+
/// </summary>
13+
/// <remarks>
14+
/// At our Splunk environment at VTEX we expect certain standard of text to be processed and
15+
/// we also have field extraction rules to be applied.
16+
/// Thats the reason why we use a custom LoggerFormmater.
17+
/// </remarks>
818
public class VTEXSplunkLoggerFormatter : ILoggerFormatter
919
{
1020
const string DateTimeFormat = "yyyy-MM-ddTHH:mm:ss.fffZ";
1121

1222
readonly string appVersion;
1323
readonly string host;
1424

15-
public VTEXSplunkLoggerFormatter(string appVersion, string host)
25+
/// <summary>
26+
/// Initializes a new instance of the <see cref="T:VTEX.SampleWebAPI.Logging.VTEXSplunkLoggerFormatter"/> class.
27+
/// </summary>
28+
public VTEXSplunkLoggerFormatter()
1629
{
17-
this.appVersion = appVersion;
18-
this.host = host;
30+
appVersion = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationVersion;
31+
host = GetHost();
1932
}
2033

34+
/// <summary>
35+
/// Format the specified logLevel, eventId, state and exception into log string entry.
36+
/// </summary>
37+
/// <returns>Formatted log string.</returns>
38+
/// <param name="logLevel">Log level.</param>
39+
/// <param name="eventId">Event identifier.</param>
40+
/// <param name="state">Log object state.</param>
41+
/// <param name="exception">Log exception.</param>
42+
/// <typeparam name="T">Log entry.</typeparam>
2143
public string Format<T>(LogLevel logLevel, EventId eventId, T state, Exception exception)
2244
{
2345
string log;
@@ -46,11 +68,53 @@ public string Format<T>(LogLevel logLevel, EventId eventId, T state, Exception e
4668
return log;
4769
}
4870

71+
/// <summary>
72+
/// Formats the specified logLevel, eventId, state and exception into json entry.
73+
/// </summary>
74+
/// <returns>The json.</returns>
75+
/// <param name="logLevel">Log level.</param>
76+
/// <param name="eventId">Event identifier.</param>
77+
/// <param name="state">Log object state.</param>
78+
/// <param name="exception">Log exception.</param>
79+
/// <typeparam name="T">Log entry.</typeparam>
4980
public SplunkJSONEntry FormatJson<T>(LogLevel logLevel, EventId eventId, T state, Exception exception)
5081
{
5182
return new SplunkJSONEntry(Format(logLevel, eventId, state, exception), 0, host, string.Empty, "Log");
5283
}
5384

85+
/// <summary>
86+
/// Method created to get AWS EC2 host Id, or set `dev` as host if AWS internal call fails.
87+
/// </summary>
88+
string GetHost()
89+
{
90+
string ec2Host = string.Empty;
91+
try
92+
{
93+
using (HttpClient httpClient = new HttpClient())
94+
{
95+
TimeSpan timeSpan = new TimeSpan(0, 0, 5);
96+
var cancellationTokenSource = new CancellationTokenSource((int)timeSpan.TotalMilliseconds);
97+
httpClient.Timeout = timeSpan;
98+
httpClient.BaseAddress = new Uri("http://169.254.169.254/latest/meta-data/");
99+
ec2Host = httpClient
100+
.GetAsync("instance-id", cancellationTokenSource.Token)
101+
.Result
102+
.Content
103+
.ReadAsStringAsync()
104+
.Result;
105+
}
106+
}
107+
catch
108+
{
109+
ec2Host = "dev";
110+
}
111+
return ec2Host;
112+
}
113+
114+
/// <summary>
115+
/// Based on LogLevel we define the correspondent VTEX event level.
116+
/// </summary>
117+
/// <returns>VTEX event level.</returns>
54118
string GetVTEXEventLevel(LogLevel logLevel)
55119
{
56120
VTEXEventLevel eventLevel = VTEXEventLevel.Debug;
@@ -75,6 +139,10 @@ string GetVTEXEventLevel(LogLevel logLevel)
75139
return eventLevel.ToString().ToLower();
76140
}
77141

142+
/// <summary>
143+
/// Based on LogLevel we define the correspondent VTEX log type.
144+
/// </summary>
145+
/// <returns>VTEX log type.</returns>
78146
string GetVTEXLogType(LogLevel logLevel)
79147
{
80148
VTEXLogType logType = VTEXLogType.Info;
@@ -97,4 +165,4 @@ string GetVTEXLogType(LogLevel logLevel)
97165
return logType.ToString().ToLower();
98166
}
99167
}
100-
}
168+
}

‎src/SampleWebAPI/Startup.cs‎

Lines changed: 24 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -14,22 +14,30 @@ namespace VTEX.SampleWebAPI
1414
{
1515
public class Startup
1616
{
17-
static readonly ILoggerFormatter formatter = new VTEXSplunkLoggerFormatter(Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationVersion, GetHost());
17+
static readonly ILoggerFormatter formatter = new VTEXSplunkLoggerFormatter();
18+
19+
public IConfiguration Configuration { get; }
1820

1921
public Startup(IConfiguration configuration)
2022
{
2123
Configuration = configuration;
2224
}
2325

24-
public IConfiguration Configuration { get; }
25-
26-
// This method gets called by the runtime. Use this method to add services to the container.
26+
/// <summary>
27+
/// This method gets called by the runtime. Use this method to add services to the container.
28+
/// </summary>
2729
public void ConfigureServices(IServiceCollection services)
2830
{
2931
services.AddMvc();
3032
}
3133

32-
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
34+
/// <summary>
35+
/// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
36+
/// </summary>
37+
/// <returns>The configure.</returns>
38+
/// <param name="app">App.</param>
39+
/// <param name="env">Env.</param>
40+
/// <param name="loggerFactory">Logger factory.</param>
3341
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
3442
{
3543
loggerFactory.AddDebug();
@@ -48,48 +56,25 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerF
4856
}
4957
};
5058

51-
//loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, null);
52-
loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter);
59+
/**************************** Define Your Logger ****************************/
60+
/* */
61+
//loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, null); //
62+
loggerFactory.AddHECRawSplunkLogger(splunkConfiguration, formatter); //
5363

54-
//loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration, null);
55-
//loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration, formatter);
64+
//loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration, null); //
65+
//loggerFactory.AddHECJsonSplunkLogger(splunkConfiguration, formatter); //
5666

57-
//loggerFactory.AddTcpSplunkLogger(splunkConfiguration, null);
58-
//loggerFactory.AddTcpSplunkLogger(splunkConfiguration, formatter);
67+
//loggerFactory.AddTcpSplunkLogger(splunkConfiguration, null); //
68+
//loggerFactory.AddTcpSplunkLogger(splunkConfiguration, formatter); //
5969

6070
//loggerFactory.AddUdpSplunkLogger(splunkConfiguration, null);
6171
//loggerFactory.AddUdpSplunkLogger(splunkConfiguration, formatter);
72+
/* */
73+
/**************************** Define Your Logger ****************************/
6274

6375
app.UseMvc();
6476
}
6577

66-
/// <summary>
67-
/// Method created to get AWS EC2 host Id, or set `dev` as host if AWS internal call fails.
68-
/// </summary>
69-
static string GetHost()
70-
{
71-
string host = string.Empty;
72-
try
73-
{
74-
using (HttpClient httpClient = new HttpClient())
75-
{
76-
TimeSpan timeSpan = new TimeSpan(0, 0, 5);
77-
var cancellationTokenSource = new CancellationTokenSource((int)timeSpan.TotalMilliseconds);
78-
httpClient.Timeout = timeSpan;
79-
httpClient.BaseAddress = new Uri("http://169.254.169.254/latest/meta-data/");
80-
host = httpClient
81-
.GetAsync("instance-id", cancellationTokenSource.Token)
82-
.Result
83-
.Content
84-
.ReadAsStringAsync()
85-
.Result;
86-
}
87-
}
88-
catch
89-
{
90-
host = "dev";
91-
}
92-
return host;
93-
}
78+
9479
}
9580
}

‎src/SplunkLogger/BatchManager.cs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,13 @@
77
namespace Splunk
88
{
99
/// <summary>
10-
/// Class used at HEC loggers to control batch process.
10+
/// This class contains all methods and logics necessary to control a batch process.
1111
/// </summary>
12+
/// <remarks>
13+
/// Batch process is necessary to improve Splunk HEC performance. You need to dose
14+
/// your own batch size and/or interval speed but it's much better than send
15+
/// individual POST for each log entry.
16+
/// </remarks>
1217
public class BatchManager
1318
{
1419
readonly ConcurrentBag<object> events;

‎src/SplunkLogger/Providers/SplunkHECJsonLoggerProvider.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
namespace Splunk.Providers
1414
{
1515
/// <summary>
16-
/// Class used to provide Splunk HEC Json logger.
16+
/// This class is used to provide a Splunk HEC Json logger for each categoryName.
1717
/// </summary>
1818
public class SplunkHECJsonLoggerProvider : ILoggerProvider
1919
{

0 commit comments

Comments
 (0)