深度長文-我花了10天時間造了個輪子,大家可能會有興趣

介紹

這個項目叫作 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 下。服務器

1. TomatoLog 是幹什麼的

TomatoLog 來源於業務發展的實際須要,在項目中,咱們的作法是使用 NLog 將日誌寫入本地,而後經過 Kafka 將日誌發送到 ES,剩下的就是怎麼對日誌進行挖掘、展現的問題了。若是須要進行擴展,就須要自行安裝其它工具對日誌進行操做了;實際上,經過這一系列的操做,你須要用到的是 NLog+Kafka+ELK,這一系列高度靈活的框架都須要手動安裝和調試,這個過程讓小白窒息,讓老司機迷路。家裏的領導常說,能一行代碼解決的問題,就不要搞那麼複雜,高擴展性是很重要,可是易用性也是很是的重要的。架構

那麼,TomatoLog 就是來解決這個問題,TomatoLog 對日誌的處理不敢說強大,但多是 .NETCore 平臺上最簡單易用的日誌集成組件,具備高度靈活的使用方式,徹底可定義配置的可擴展性,使用異步寫入,業務徹底解耦,客戶端的一鍵安裝、一行代碼上傳日誌,目前 TomatoLog 沒有實現登陸驗證,須要注意使用環境訪問權限問題。下面就使用和功能進行展開介紹。app

1.1 TomatoLog 的系統架構

千言萬語不如一張圖框架

從圖中能夠看出,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 帶來的便利性和溫馨的日誌操做體驗。

2. 部署日誌採集服務器

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 (服務主程序文件),首先,看看服務配置文件

2.1 服務器配置
{
  "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 節點。

2.2 啓動服務

在服務配置完成後,就可使用 dotnet TomatoLog.Server.dll 啓動服務程序,能夠看到, TomatoLog 偵聽的端口爲:20272.

在瀏覽器中輸入網址:http://localhost:20272/,查看 Web 控制檯

目前能夠看到,由於沒有產生日誌,因此首頁是一片空白,可是沒有關係,下面介紹另外一個強大的功能:配置

2.3 系統全局配置

控制檯上還有兩個導航按鈕 「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 通知中配置使用,系統變量的使用如上圖,必須使用大括號進行包圍。

2.4 針對項目的單獨配置

除了系統全局配置,TomatoLog 還支持針對每一個項目進行獨立通知設置,方便項目管理和跟蹤,項目通知配置和全局配置一致,

項目通知配置將覆蓋全局配置(若是有配置的話)

3. 客戶端的使用演示

首先,創建一個演示項目 Example ,該項目爲 Asp.NETCore WebApi 項目。

3.1 安裝客戶端組件

接下來在 Nuget 上搜索包 TomatoLog ,因爲服務器配置了使用數據流類型爲 RabbitMQ,這裏選擇安裝 TomatoLog.Client.RabbitMQ-1.0.2

3.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
  }

這段配置看似複雜,其實很是簡單,全部的一切均可以自由配置,在程序中,只須要一行代碼初始化即,很是方便。

3.3 將異常寫入數據流

在異常發生的時候,將異常寫入數據流的操做很是簡單,就像下面的代碼

** 首先引入命名空間

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" };
        }
3.4 查看服務端收集日誌

能夠看到,上面咱們一共寫入了兩條日誌,分類爲 Error 和 Warning,查看文件系統上,在項目 Example 目錄下,有兩個文件

點擊列表進入查看,點擊單行日誌的任意位置,還能夠查看詳細信息

3.5 自定義日誌查看列

還支持對日誌的搜索和分頁,搜索語法支持如下三種類型:

** ToFile 存儲時:支持直接搜索字符串
** ToMongoDB 存儲時: 支持 MongoDB 搜索語法
** ToES 存儲時:支持 ElasticSearch 語法

分頁支持:當前日誌超過 100 行時(默認顯示最新 100 條日誌),自動出現 Previous/Next 分頁導航按鈕

結束語

TomatoLog 設計的基本原則是開放、高可擴展、自由、易用,經過簡單的封裝,讓任何一個開發人員都能在 3 分鐘內投入使用,享受 TomatoLog 帶來的便利性,TomatoLog 只作簡單的存儲,能夠看到,若是選擇存儲到 MongoDB 或者 ES 中的時候,你們還能夠經過其它的日誌挖掘工具對日誌進一步的搜索和處理。

若是您以爲這個項目還不錯,請點擊 star ,若是但願加入此項目,成爲貢獻者,請留下您的 GitHub 帳號,經過開源,讓 .NETCore 生態愈來愈好。

喔~對了,歡迎報告BUG!

廣州.NET微軟技術俱樂部

最後,推廣一下廣州.NET微軟技術俱樂部,歡迎更多的朋友加入咱們 .NETCore 這個你們庭、一塊兒學習交流。QQ羣:651477282。

相關文章
相關標籤/搜索