這個項目叫作 TomatoLog,託管在 GitHub 項目上,使用的 License 是 MIT,請放心試用,目前該項目主要由我我的維護,還有兩位大神加入了協做者中。
** TomatoLog.Server 基於 .NETCore2.2
** TomatoLog.Client 基於 netstandard2.0git
https://github.com/lianggx/TomatoLoggithub
** 中文說明文檔:
https://github.com/lianggx/TomatoLog/blob/master/README_Zh-cn.mdmongodb
** 服務器版本:
https://github.com/lianggx/TomatoLog/releasesjson
** 客戶端組件 v1.0.2:
TomatoLog.Common(公共代碼庫)
TomatoLog.Client(客戶端基礎實現類)
TomatoLog.Client.Redis(Reids客戶端,基於 CSRedisCore 客戶端)
TomatoLog.Client.RabbitMQ(RabbitMQ客戶端)瀏覽器
** 存儲插件
TomatoLog.ToFile(寫入文件)
TomatoLog.ToMongoDB(寫入MongoDB)
TomatoLog.ToES(寫入ElasticSearch)緩存
演示代碼位於項目目錄 Examples 下。服務器
TomatoLog 來源於業務發展的實際須要,在項目中,咱們的作法是使用 NLog 將日誌寫入本地,而後經過 Kafka 將日誌發送到 ES,剩下的就是怎麼對日誌進行挖掘、展現的問題了。若是須要進行擴展,就須要自行安裝其它工具對日誌進行操做了;實際上,經過這一系列的操做,你須要用到的是 NLog+Kafka+ELK,這一系列高度靈活的框架都須要手動安裝和調試,這個過程讓小白窒息,讓老司機迷路。家裏的領導常說,能一行代碼解決的問題,就不要搞那麼複雜,高擴展性是很重要,可是易用性也是很是的重要的。架構
那麼,TomatoLog 就是來解決這個問題,TomatoLog 對日誌的處理不敢說強大,但多是 .NETCore 平臺上最簡單易用的日誌集成組件,具備高度靈活的使用方式,徹底可定義配置的可擴展性,使用異步寫入,業務徹底解耦,客戶端的一鍵安裝、一行代碼上傳日誌,目前 TomatoLog 沒有實現登陸驗證,須要注意使用環境訪問權限問題。下面就使用和功能進行展開介紹。app
千言萬語不如一張圖框架
從圖中能夠看出,TomatoLog 包含三個基礎組件,他們分別是:客戶端、數據流控制器、服務器;TomatoLog 自己不作存儲優化,其經過定義一個簡單的數據流協議實現日誌的收集到存儲,這個數據流協議在系統中被定義成爲一個實體對象模型 LogMessage,位於程序集 TomatoLog.Common.dll 中:
namespace TomatoLog.Common.Utilities { public class LogMessage { public int EventId { get; set; } public string ProjectName { get; set; } public string ProjectLabel { get; set; } public LogLevel LogLevel { get; set; } public string Version { get; set; } public string IP { get; set; } public string[] IPList { get; set; } public string MachineName { get; set; } public string ThreadId { get; set; } public string ProcessId { get; set; } public string ProcessName { get; set; } public DateTime Timestamp { get; set; } public string UserName { get; set; } public string ErrorMessage { get; set; } public string StackTrace { get; set; } public object Extra { get; set; } } }
上面的全部字段均可以使用配置進行跟蹤,可選擇將哪些信息寫入到日誌中,其中,關於服務器主機信息,客戶端會自動採集主機信息,無需手動傳入,若是這些信息仍是不能知足業務須要,不要緊,上面的實體類中還定義了擴展字段 "Extra" ,該字段接收一切對象,固然,最好就是使用 Json 對象,這也比較科學。
服務端在接收到日誌信息後,將會根據服務配置對日誌進行清洗、篩選、而後是存入指定存儲介質中,若是日誌觸發了服務配置的警報,服務器還將自動發送警報通知。下面,就從使用開始,體驗 TomatoLog 帶來的便利性和溫馨的日誌操做體驗。
TomatoLog 日誌服務器目前發佈的版本是:1.0.2(目前處於起步階段,版本迭代速度可能比較快),位於:https://github.com/lianggx/TomatoLog/releases,直接下載 TomatoLog-1.0.2.zip,解壓,獲得文件以下:
此壓縮包僅包含程序運行所必須文件,因此必需要在目標機器上安裝 .NETCore SDK 2.2+,你能夠簡單的使用命令行或者其它你熟悉的託管程序去啓動 TomatoLog.Server ,好比可使用 IIS、Supervisord、Docker(須要自行打包); 在本示例中,我選擇使用命令行啓動它。
在上面文件夾中,咱們在第一次使用的使用,只須要關注兩個文件便可,他們分別是 appsettings.(Development/Production).json (服務配置文件)和 TomatoLog.Server.dll (服務主程序文件),首先,看看服務配置文件
{ "Logging": { "IncludeScopes": false, "LogLevel": { "Default": "Debug", "System": "Information", "Microsoft": "Information" } }, "TomatoLog": { "Cache-Redis": null, "Config": { "SysConfig": "Config/SysConfig.json", "ProConfig": "Config/ProConfig.json" }, "Storage": { "Type": "ToFile", //ToFile/ToES/ToMongoDB "File": "D:\\TomatoLog\\Storage", "ES": "http://127.0.0.1:9200/", "MongoDB": "mongodb://root:root@127.0.0.1:27017/admin", "Others":null }, "Flow": { "Type": "RabbitMQ", // Redis/RabbitMQ/Kafaka "Redis": { "Connection": null, "Channel": "TomatoLogChannel" }, "RabbitMQ": { "Host": "127.0.0.1", "Port": 5672, "UserName": "root", "Password": "123456", "vHost": "TomatoLog", "Exchange": "TomatoLog-Exchange", "ExchangeType": "direct", "QueueName": "TomatoLog-Queue", "RouteKey": "All", "Channels": 1 // RabbitMQ client instance quantity }, "Kafka": null } } }
服務配置文件包含一個主節點 TomatoLog,下面內置 4 個子節點,分別是:
** Cache-Redis
該節點指示在服務對日誌進行篩選、清洗的過程當中,會將策略寫入緩存,默認狀況下,策略被寫入本地緩存,若是指定分佈式緩存,則使用分佈式緩存,強烈推薦配置分佈式緩存,在服務進行重啓或者更新的時候,策略將能夠被持續計數。
** Config
此節點下配置了兩個系統配置文件,分別是 SysConfig 和 ProConfig,這表明着服務對日誌的清洗、過濾、警報的配置,無需改動這兩個文件,由於咱們提供了更友好的 Web 控制檯進行配置,後面會有介紹。
** Storage
此節點很是重要,決定了日誌的存儲介質,首先是 Type ,能夠指定 //ToFile/ToES/ToMongoDB 中的任意一種,目前,TomatoLog 的存儲是經過接口實現的插件進行反射調用,全部的存儲插件都存放在程序目錄下的 Plugins 目錄下
若是你認爲有必要重寫插件,在存儲前作一些其它的工做的話,你還能夠經過實現 TomatoLog.Common 程序集中定義的 ILogWriter 接口,而後將插件放入 Plugins 目錄下,覆蓋 //ToFile/ToES/ToMongoDB 中的一種插件,設置 Type 指定爲你實現的插件名稱便可。或者,你還能夠本身實現一個全新的插件,如實現了一個將日誌存儲到 Redis 的插件 ToRedis,則將設置 "Type":"ToRedis",而且將 ToRedis 須要的配置寫入到節點 Others 中自行讀取實現,由於 ILogWriter 的默認實現 LogWriter 抽象類的構造參數接收了一個實體對象
public class StorageOptions { public StorageType Type { get; set; } public string File { get; set; } public string ES { get; set; } public string MongoDB { get; set; } public string Others { get; set; } }
ToRedis 插件能夠經過繼承 LogWriter 得到該配置節點。
** Flow
Flow 節點表示數據流的選擇,準備支持 3 中數據流,可是由於精力有限,特別是對 Kafka 也不是很熟悉,目前只實現了 Redis/RabbitMQ 兩種方式,目前來看,基本夠用,Flow 節點下面的子節點就是對數據流節點的配置,選擇 Redis 就配置 Flow.Redis ,若是使用 RabbitMQ,則配置 Flow.RabbitMQ 節點。
在服務配置完成後,就可使用 dotnet TomatoLog.Server.dll 啓動服務程序,能夠看到, TomatoLog 偵聽的端口爲:20272.
在瀏覽器中輸入網址:http://localhost:20272/,查看 Web 控制檯
目前能夠看到,由於沒有產生日誌,因此首頁是一片空白,可是沒有關係,下面介紹另外一個強大的功能:配置
控制檯上還有兩個導航按鈕 「Config」、「Project」,點擊查看 Config
** 警報配置
Enable:是否啓用警報通知,值爲:true/false
Report stage(Seconds):警報週期,時間:秒
Trigger threshold:觸發閾值,和 Report stage(Seconds) 配合使用,即 xx 秒內發生 x 次後 發送通知,並重置計數器
Monitor Levels:警報級別,支持 Trace;Debug;Information;Warning;Error;Critical;None,多個 Level 以 分號進行分隔。
** 短信通知配置
此通知配置很是強大,基於 Http 請求,不僅侷限於 SMS,全部能夠被 Http 請求的網關地址均可以配置到這裏,通知內容支持系統變量(見下面附錄)
** 郵件通知配置
能夠配置郵件通知(推薦測試服啓用,跟蹤BUG),郵件主題和內容支持系統變量(見下面附錄),支持 Html 郵件內容
** 附錄:系統變量
上面列出了系統支持的全部內置變量,可在 SMS 和 Email 通知中配置使用,系統變量的使用如上圖,必須使用大括號進行包圍。
除了系統全局配置,TomatoLog 還支持針對每一個項目進行獨立通知設置,方便項目管理和跟蹤,項目通知配置和全局配置一致,
項目通知配置將覆蓋全局配置(若是有配置的話)
首先,創建一個演示項目 Example ,該項目爲 Asp.NETCore WebApi 項目。
接下來在 Nuget 上搜索包 TomatoLog ,因爲服務器配置了使用數據流類型爲 RabbitMQ,這裏選擇安裝 TomatoLog.Client.RabbitMQ-1.0.2
public void ConfigureServices(IServiceCollection services) { services.AddSingleton<ITomatoLogClient, TomatoLogClientRabbitMQ>(factory => { var options = this.Configuration.GetSection("TomatoLog").Get<EventRabbitMQOptions>(); var client = new TomatoLogClientRabbitMQ(options); return client; }); services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); }
上面的代碼中,讀取了客戶端配置文件節點 TomatoLog 並反序列化爲 EventRabbitMQOptions 配置對象,而後使用該配置對 TomatoLogClientRabbitMQ 進行了初始化,關於 EventRabbitMQOptions 在配置文件中的配置以下:
"TomatoLog": { "LogLevel": "Information", // 寫入日誌級別,大於此級別的日誌都將被吸入數據流中 "ProjectLabel": "Example", // 項目標籤,可爲 null "ProjectName": "Example", // 項目名稱,必須 "SysOptions": { // 是否自動採集主機信息,可配置 "EventId": true, "IP": true, "IPList": true, "MachineName": true, "ProcessId": true, "ProcessName": true, "ThreadId": true, "Timestamp": true, "UserName": true }, "Tags": null, // 項目 Tag ,可 null "Version": "1.0.0", // 當前項目版本號,可爲 null "Exchange": "TomatoLog-Exchange", // RabbitMQ 中配置的交換機名稱 "ExchangeType": "direct", // RabbitMQ 交換機類型 "Host": "RabbitMQ Host ", // RabbitMQ 主機地址 "Password": "RabbitMQ Passworrd", // RabbitMQ 鏈接密碼 "Port": 5672, // RabbitMQ 鏈接端口 "QueueName": "RabbitMQ Queue", // RabbitMQ 日誌隊列名稱 "RouteKey": "Route Key", // RabbitMQ Route Key,根據 ExchangeType 動態設置 "UserName": "RabbitMQ UserName", // RabbitMQ 鏈接用戶名 "vHost": "RabbitMQ vHost" // RabbitMQ 鏈接的 vHost }
這段配置看似複雜,其實很是簡單,全部的一切均可以自由配置,在程序中,只須要一行代碼初始化即,很是方便。
在異常發生的時候,將異常寫入數據流的操做很是簡單,就像下面的代碼
** 首先引入命名空間
using TomatoLog.Client.Extensions;
** 處理異常:
public ActionResult<IEnumerable<string>> Get() { try { throw new NotSupportedException("Media Type"); } catch (Exception ex) { ex.AddTomatoLogAsync(); } return new string[] { "value1", "value2" }; }
咱們上面說過,能一行代碼作完的事情就不要搞複雜了,使用 ex.AddTomatoLogAsync(); 就能夠將日誌寫入到數據流中了,很是的簡潔高效。若是須要寫入自定義的日誌信息,能夠經過依賴注入得到日誌客戶端對象,而後寫入自定義日誌,好比
public async Task<ActionResult<IEnumerable<string>>> Get() { await logClient.WriteLogAsync(1029, LogLevel.Warning, "Warning Infomation", "Warning Content", new { LastTime = DateTime.Now, Tips = "Warning" }); return new string[] { "value1", "value2" }; }
能夠看到,上面咱們一共寫入了兩條日誌,分類爲 Error 和 Warning,查看文件系統上,在項目 Example 目錄下,有兩個文件
點擊列表進入查看,點擊單行日誌的任意位置,還能夠查看詳細信息
還支持對日誌的搜索和分頁,搜索語法支持如下三種類型:
** ToFile 存儲時:支持直接搜索字符串
** ToMongoDB 存儲時: 支持 MongoDB 搜索語法
** ToES 存儲時:支持 ElasticSearch 語法
分頁支持:當前日誌超過 100 行時(默認顯示最新 100 條日誌),自動出現 Previous/Next 分頁導航按鈕
TomatoLog 設計的基本原則是開放、高可擴展、自由、易用,經過簡單的封裝,讓任何一個開發人員都能在 3 分鐘內投入使用,享受 TomatoLog 帶來的便利性,TomatoLog 只作簡單的存儲,能夠看到,若是選擇存儲到 MongoDB 或者 ES 中的時候,你們還能夠經過其它的日誌挖掘工具對日誌進一步的搜索和處理。
若是您以爲這個項目還不錯,請點擊 star ,若是但願加入此項目,成爲貢獻者,請留下您的 GitHub 帳號,經過開源,讓 .NETCore 生態愈來愈好。
喔~對了,歡迎報告BUG!
最後,推廣一下廣州.NET微軟技術俱樂部,歡迎更多的朋友加入咱們 .NETCore 這個你們庭、一塊兒學習交流。QQ羣:651477282。