From b4cc44866e807bdcb63b026137ea3864e6afd739 Mon Sep 17 00:00:00 2001 From: Jeroen Date: Sun, 22 Oct 2023 18:02:15 +0200 Subject: [PATCH] Updated documentation --- EonaCat.Logger/EonaCat.Logger.csproj | 2 +- EonaCat.Logger/Splunk/Models/SplunkPayload.cs | 11 + EonaCat.Logger/Splunk/SplunkServer.cs | 12 +- README.md | 353 +++++++++++++++++- Testers/EonaCat.Logger.Test.Web/Program.cs | 1 - 5 files changed, 368 insertions(+), 11 deletions(-) diff --git a/EonaCat.Logger/EonaCat.Logger.csproj b/EonaCat.Logger/EonaCat.Logger.csproj index d71afe3..2ba29cf 100644 --- a/EonaCat.Logger/EonaCat.Logger.csproj +++ b/EonaCat.Logger/EonaCat.Logger.csproj @@ -7,7 +7,7 @@ net7.0; icon.ico - 1.2.2 + 1.2.3 EonaCat (Jeroen Saey) true EonaCat (Jeroen Saey) diff --git a/EonaCat.Logger/Splunk/Models/SplunkPayload.cs b/EonaCat.Logger/Splunk/Models/SplunkPayload.cs index c10d7e6..ae82b85 100644 --- a/EonaCat.Logger/Splunk/Models/SplunkPayload.cs +++ b/EonaCat.Logger/Splunk/Models/SplunkPayload.cs @@ -6,8 +6,19 @@ namespace EonaCat.Logger.Splunk.Models { public class SplunkPayload { + /// + /// Event data for splunk + /// public string EventData { get; set; } + + /// + /// SourceType for splunk + /// public string SourceType { get; set; } + + /// + /// Host for splunk + /// public string Host { get; set; } } } diff --git a/EonaCat.Logger/Splunk/SplunkServer.cs b/EonaCat.Logger/Splunk/SplunkServer.cs index 4f44b81..487d8a0 100644 --- a/EonaCat.Logger/Splunk/SplunkServer.cs +++ b/EonaCat.Logger/Splunk/SplunkServer.cs @@ -1,11 +1,8 @@ using EonaCat.Json; using EonaCat.Logger.Splunk.Models; using System; -using System.Net; using System.Net.Http; -using System.Net.Security; using System.Text; -using System.Threading; using System.Threading.Tasks; namespace EonaCat.Logger.SplunkServer @@ -62,10 +59,19 @@ namespace EonaCat.Logger.SplunkServer private string _splunkHecUrl = "https://127.0.0.1:8088/services/collector/event"; private string _splunkHecToken = "splunk-hec-token"; + /// + /// Determines if a HEC token is available + /// public bool HasHecToken => !string.IsNullOrWhiteSpace(SplunkHecToken) && SplunkHecToken != "splunk-hec-token"; + /// + /// Determines if a HEC url is available + /// public bool HasHecUrl => !string.IsNullOrWhiteSpace(SplunkHecUrl); + /// + /// Determines if the splunk URL is local + /// public bool IsLocalHost => HasHecUrl && (SplunkHecUrl.ToLower().Contains("127.0.0.1") || SplunkHecUrl.ToLower().Contains("localhost")); diff --git a/README.md b/README.md index a5da14c..9e86eec 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,354 @@ # EonaCat.Logger -EonaCat Logger - -Log application information to log files - +Log application information to log files. Be sure the following dependencies are added: -Microsoft.Extensions.Logging.Abstractions +> Microsoft.Extensions.Logging.Abstractions Microsoft.Extensions.DependencyInjection.Abstractions Microsoft.Extensions.DependencyInjection -Microsoft.Extensions.Logging \ No newline at end of file +Microsoft.Extensions.Logging + +**Easy way of logging without configuring anything:** +```csharp +LogManager.Instance.Write("INFO", ELogType.INFO, true); +LogManager.Instance.Write("WARNING", ELogType.WARNING, true); +LogManager.Instance.Write("ERROR", ELogType.ERROR, true); +LogManager.Instance.Write("DEBUG", ELogType.DEBUG, true); +LogManager.Instance.Write("CRITICAL", ELogType.CRITICAL, true); +LogManager.Instance.Write("TRACE", ELogType.TRACE, true); +LogManager.Instance.Write("TRAFFIC", ELogType.TRAFFIC, true); +LogManager.Instance.Write("NONE", ELogType.NONE, true); +``` + +**Logging in ASP .Net 6.0 or higher: ** + +```csharp +public class Program + { + public static void Main(string[] args) + { + CreateHostBuilder(args).Build().Run(); + } + + public static IHostBuilder CreateHostBuilder(string[] args) + { + // Add services to the container. + FileLoggerOptions options = new FileLoggerOptions(); + options.MaxRolloverFiles = 20; + options.FileSizeLimit = 1 * 1024 * 1024 / 4; + options.UseLocalTime = true; + + var builder = Host.CreateDefaultBuilder(args) + .ConfigureWebHostDefaults(webBuilder => + { + webBuilder.UseStartup(); + }).ConfigureLogging(x => x.AddEonaCatFileLogger(fileLoggerOptions: options, filenamePrefix: "web")); + return builder; + } + } +``` + +**Example of *advanced* logging class:** + +```csharp +// Import necessary namespaces. +using EonaCat.Logger; +using EonaCat.Logger.Managers; +using EonaCat.Logger.Syslog; +using EonaCat.Logger.SplunkServer; +using EonaCat.Logger.GrayLog; + +namespace EonaCat.Logger.Advanced +{ + // The GrayLogSettings class represents settings for GrayLog servers. + internal class GrayLogSettings + { + // Constructor for GrayLogSettings class. + public GrayLogSettings(string facility, string source, string version = "1.1") + { + Facility = facility; + Source = source; + Version = version; + } + + // Facility represents the facility for GrayLog logs. + public string Facility { get; } + // Source represents the source for GrayLog logs. + public string Source { get; } + // Version represents the version for GrayLog logs (default is "1.1"). + public string Version { get; } + } + + // The Logger class provides advanced logging functionality. + internal class Logger + { + private static readonly LogManager _logManager; + private static ConsoleLogTextWriter _consoleLogTextWriter; + + // Exposes a TextWriter property to allow for logging to the console. + public static TextWriter ConsoleLog { get; internal set; } + + // Static constructor for the Logger class. + static Logger() + { + // Create and configure a LogManager for logging. + _logManager = new LogManager(new LoggerSettings { RemoveMessagePrefix = true }); + _logManager.OnException += _logManager_OnException; + _logManager.Settings.FileLoggerOptions.FileNamePrefix = "advanced"; + _logManager.Settings.UseLocalTime = true; + _logManager.Settings.FileLoggerOptions.UseLocalTime = true; + _logManager.Settings.SysLogServers = new List(); + _logManager.Settings.SplunkServers = new List(); + _logManager.Settings.GrayLogServers = new List(); + _logManager.StartNewLogAsync(); + } + + // Event handler for LogManager exceptions, writes messages to the console. + private static void _logManager_OnException(object? sender, ErrorMessage e) + { + Console.WriteLine(e.Message); + if (e.Exception != null) + { + Console.WriteLine(e.Exception); + } + } + + // Redirects console output to the log. + public static void RedirectConsoleToLog() + { + // Create the callback function to capture console output and log it. + static void callback(string line) => Info(line, writeToConsole: false); + + _consoleLogTextWriter = new ConsoleLogTextWriter(callback); + Console.SetOut(_consoleLogTextWriter); + } + + // Adds a GrayLog server with the specified hostname and port. + public static void AddGrayLogServer(string hostname, int port) + { + _logManager.Settings.GrayLogServers.Add(new GrayLogServer(hostname, port)); + } + + // Removes a GrayLog server from the configuration. + public static bool RemoveGrayLogServer(GrayLogServer grayLogServer) + { + return _logManager.Settings.GrayLogServers.Remove(grayLogServer); + } + + // Sets the state for sending logs to GrayLog servers. + public static void GrayLogState(bool state) + { + _logManager.Settings.SendToGrayLogServers = state; + } + + // Adds a Splunk server with the specified HEC URL and token. + public static void AddSplunkServer(string splunkHecUrl, string splunkHecToken, bool disableSSL = false) + { + var splunkServer = new SplunkServer(splunkHecUrl, splunkHecToken); + if (disableSSL) + { + splunkServer.DisableSSLValidation(); + } + _logManager.Settings.SplunkServers.Add(splunkServer); + } + + // Removes a Splunk server from the configuration. + public static bool RemoveSplunkServer(SplunkServer splunkServer) + { + return _logManager.Settings.SplunkServers.Remove(splunkServer); + } + + // Sets the state for sending logs to Splunk servers. + public static void SplunkState(bool state) + { + _logManager.Settings.SendToSplunkServers = state; + } + + // Adds a Syslog server with the specified IP address and port. + public static void AddSyslogServer(string ipAddress, int port) + { + _logManager.Settings.SysLogServers.Add(new SyslogServer(ipAddress, port)); + } + + // Removes a Syslog server from the configuration. + public static bool RemoveSyslogServer(SyslogServer syslogServer) + { + return _logManager.Settings.SysLogServers.Remove(syslogServer); + } + + // Sets the state for sending logs to Syslog servers. + public static void SysLogState(bool state) + { + _logManager.Settings.SendToSyslogServers = state; + } + + // Logs an informational message. + public static void Info(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.INFO, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + + // Internal method to write logs. + private static void Write(string message, ELogType logType, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + if (grayLogSettings != null) + { + // Log the message with specified settings. + _logManager.Write(message, logType, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings.Facility, grayLogSettings.Source, grayLogSettings.Version); + } + else + { + // Log the message with default settings. + _logManager.Write(message, logType, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers); + } + } + + // Logs a debug message. + public static void Debug(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.DEBUG, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + + // Logs an error message along with an exception. + public static void Error(Exception exception, string message = null, bool isCriticalException = false, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + if (grayLogSettings != null) + { + // Log the exception and message with specified settings. + _logManager.Write(exception, message, criticalException: isCriticalException, writeToConsole: writeToConsole, sendToSysLogServers: sendToSysLogServers, sendToSplunkServers: sendToSplunkServers, customSplunkSourceType: customSplunkSourceType, sendToGrayLogServers: sendToGrayLogServers, grayLogFacility: grayLogSettings.Facility, grayLogSource: grayLogSettings.Source, grayLogVersion: grayLogSettings.Version); + } + else + { + // Log the exception and message with default settings. + _logManager.Write(exception, message, criticalException: isCriticalException, writeToConsole: writeToConsole, sendToSysLogServers: sendToSysLogServers, sendToSplunkServers: sendToSplunkServers, customSplunkSourceType: customSplunkSourceType, sendToGrayLogServers: sendToGrayLogServers); + } + } + + // Logs an error message. + public static void Error(string message = null, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, string grayLogFacility = null, string grayLogSource = null, string grayLogVersion = "1.1", bool isCriticalException = false) + { + if (isCriticalException) + { + // Log a critical error message. + _logManager.Write(message, ELogType.CRITICAL, writeToConsole); + } + else + { + // Log a regular error message. + _logManager.Write(message, ELogType.ERROR, writeToConsole); + } + } + + // Logs a warning message. + public static void Warning(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.WARNING, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + + // Logs a critical message. + public static void Critical(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.CRITICAL, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + + // Logs a traffic message. + public static void Traffic(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.TRAFFIC, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + + // Logs a trace message. + public static void Trace(string message, bool? writeToConsole = null, bool? sendToSysLogServers = null, bool? sendToSplunkServers = null, string? customSplunkSourceType = null, bool? sendToGrayLogServers = null, GrayLogSettings grayLogSettings = null) + { + Write(message, ELogType.TRACE, writeToConsole, sendToSysLogServers, sendToSplunkServers, customSplunkSourceType, sendToGrayLogServers, grayLogSettings); + } + } +} +``` + +**Code for enabling GrayLog in the above *advanced* logger class:** + +```csharp + // Set grayLog information + var ipAddress = "192.168.10.50" + var port = 9000; + +Logger.AddGrayLogServer(ipAddress, port); +Logger.GrayLogState(true); +``` +**Code for enabling Splunk in the above *advanced* logger class:** + +```csharp +// Set Splunk information +var splunkHecUrl = "https://192.168.10.51:8088/services/collector"; +var splunkHecToken = "cf0c7e68-e14b-48c1-949f-efdf5d388254"; + +Logger.AddSplunkServer(splunkHecUrl, splunkHecToken, true); +Logger.SplunkState(true); +``` + +**Code for enabling SysLog in the above *advanced* logger class:** + +```csharp + // Set sysLog information + var ipAddress = "192.168.10.53"; + var port = 514; + +Logger.AddSyslogServer(ipAddress, port); +Logger.SysLogState(true); +``` + + +**Logging Test with *default* LogManager:** + +```csharp +Task.Run(() => +{ + var loggerSettings = new LoggerSettings(); + loggerSettings.UseLocalTime = true; + loggerSettings.FileLoggerOptions.UseLocalTime = true; + loggerSettings.MaxLogType = ELogType.TRACE; + loggerSettings.FileLoggerOptions.FileSizeLimit = 1024 * 1024 * 1; + loggerSettings.FileLoggerOptions.FileNamePrefix = "AllTypes"; + loggerSettings.FileLoggerOptions.MaxRolloverFiles = 5; + + // Create an instance of the logManager with the specified loggerSettings + var logger = new LogManager(loggerSettings); + + // 10.000.000 lines to go :) + for (int i = 0; i < 10000000; i++) + { + logger.Write($"test to file {i} INFO", ELogType.INFO); + logger.Write($"test to file {i} CRITICAL", ELogType.CRITICAL); + logger.Write($"test to file {i} DEBUG", ELogType.DEBUG); + logger.Write($"test to file {i} ERROR", ELogType.ERROR); + logger.Write($"test to file {i} TRACE", ELogType.TRACE); + logger.Write($"test to file {i} TRAFFIC", ELogType.TRAFFIC); + logger.Write($"test to file {i} WARNING", ELogType.WARNING); + logger.Write($"test to file {i} NONE", ELogType.NONE); + Console.WriteLine($"Logged: {i}"); + Task.Delay(1); + } +}); +``` + +How to retrieve exceptions thrown by the library (from splunk, syslog and grayLog) + +```csharp +LogManager logManager = new LogManager(); +logManager.OnException += LogManager_OnException; + +private void LogHelper_OnException(object sender, ErrorMessage e) +{ + if (e.Exception != null) + { + Console.WriteLine(e.Exception); + } + + if (e.Message != null) + { + Console.WriteLine("Error message from logger: " + e.Message) + } +} +``` \ No newline at end of file diff --git a/Testers/EonaCat.Logger.Test.Web/Program.cs b/Testers/EonaCat.Logger.Test.Web/Program.cs index 357c66b..9a33f6c 100644 --- a/Testers/EonaCat.Logger.Test.Web/Program.cs +++ b/Testers/EonaCat.Logger.Test.Web/Program.cs @@ -174,7 +174,6 @@ void RunLoggingTests() loggerSettings.FileLoggerOptions.FileSizeLimit = 1024 * 1024 * 1; loggerSettings.FileLoggerOptions.FileNamePrefix = "AllTypes"; loggerSettings.FileLoggerOptions.MaxRolloverFiles = 5; - loggerSettings.MaxLogType = ELogType.TRACE; var logger = new LogManager(loggerSettings); for (int i = 0; i < 9000000; i++)