技術文章 » ExceptionLess的安裝、設定、使用

ExceptionLess的安裝、設定、使用

2022-07-22 06:00:15

前言

Exceptionless 是一個開源的實時的紀錄檔收集框架，它可以應用在基於 ASP.NET，ASP.NET Core，Web API，Web Forms，WPF，Console，ASP.NET MVC 等技術開發的應用程式中，並且提供了REST介面可以應用在 Javascript，Node.js 中。（基本就是.Net技術棧的一套東西）

專案地址：https://github.com/exceptionless/Exceptionless

它將紀錄檔收集變得簡單易用並且不需要了解太多的相關技術細節及設定，對於微服務架構的應用程式來說，統一的紀錄檔收集系統的建立更是有必要。

要使用的話只需要在其官網上註冊個賬號，然後在程式碼中設定一下APIKey就可以了，不過免費版額度有限，當然還是自己部署一套比較好，這次依然使用docker部署

安裝

docker部署可以在GitHub下載程式碼自己構建，也可以用官方打包好的映象，為了方便這裡我直接使用官方打包的映象

docker-compose.yml 內容如下

可以看到其中包含5個容器：ExceptionLess App、ExceptionLess Job、elasticsearch、kibana、Redis

version: '3.7'

services:
  app:
    depends_on:
      - elasticsearch
      - redis
    image: exceptionless/app:latest
    environment:
      EX_AppMode: Production
      EX_ConnectionStrings__Cache: provider=redis
      EX_ConnectionStrings__Elasticsearch: server=http://elasticsearch:9200
      EX_ConnectionStrings__MessageBus: provider=redis
      #EX_ConnectionStrings__Metrics: provider=statsd;server=statsd;
      EX_ConnectionStrings__Queue: provider=redis
      EX_ConnectionStrings__Redis: server=redis,abortConnect=false
      EX_ConnectionStrings__Storage: provider=folder;path=/app/storage
      # 官方設定預設包含HTTPS，我把它關了
      #ASPNETCORE_URLS: http://+;https://+
      ASPNETCORE_URLS: http://+
      # 關了HTTPS，這個埠也不用設定了
      #ASPNETCORE_HTTPS_PORT: 5001
      # 關了HTTPS，證書也不用設定
      #ASPNETCORE_Kestrel__Certificates__Default__Password: password
      #ASPNETCORE_Kestrel__Certificates__Default__Path: /https/aspnetapp.pfx
      EX_RunJobsInProcess: 'false'
    ports:
      - 5000:80
      # 關了HTTPS，不需要對映443埠
      #- 5001:443
    volumes:
      - ex_appdata:/app/storage
      - ex_ssldata:/https

  jobs:
    depends_on:
      - app
    image: exceptionless/job:latest
    environment:
      EX_AppMode: Production
      # UI地址，修改這裡的IP地址為你的伺服器IP地址
      EX_BaseURL: http://你的IP:5000
      EX_ConnectionStrings__Cache: provider=redis
      EX_ConnectionStrings__Elasticsearch: server=http://elasticsearch:9200
      # 郵件設定
      EX_ConnectionStrings__Email: smtps://郵箱地址:密碼@SMTP伺服器:埠
      EX_SmtpFrom: 發件郵箱地址
      EX_ConnectionStrings__MessageBus: provider=redis
      #EX_ConnectionStrings__Metrics: provider=statsd;server=statsd;
      EX_ConnectionStrings__Queue: provider=redis
      EX_ConnectionStrings__Redis: server=redis,abortConnect=false
      EX_ConnectionStrings__Storage: provider=folder;path=/app/storage
    volumes:
      - ex_appdata:/app/storage

  elasticsearch:
    image: exceptionless/elasticsearch:7.15.2
    environment:
      discovery.type: single-node
      xpack.security.enabled: 'false'
      ES_JAVA_OPTS: -Xms1g -Xmx1g
    ports:
      - 9200:9200
      - 9300:9300
    volumes:
      - ex_esdata:/usr/share/elasticsearch/data

  kibana:
    depends_on:
      - elasticsearch
    image: docker.elastic.co/kibana/kibana:7.15.2
    ports:
      - 5601:5601

  redis:
    image: redis:6.0-alpine
    ports:
      - 6379:6379

volumes:
  ex_esdata:
    driver: local
  ex_appdata:
    driver: local
  ex_ssldata:
    driver: local

郵件設定

郵件設定是比較麻煩的地方，我查了一些資料才解決

在jobs容器中的這兩個環境變數裡設定

EX_ConnectionStrings__Email: smtps://郵箱地址:密碼@SMTP伺服器:埠
EX_SmtpFrom: 發件郵箱地址

有坑的地方就是EX_ConnectionStrings__Email變數的郵箱地址需要對@符號進行跳脫，用%40代替@符號

以我的自建郵箱為例，郵箱地址是：[email protected]，那麼設定就是這樣

EX_ConnectionStrings__Email: smtps://test%40dealiaxy.com:密碼@SMTP伺服器:埠
EX_SmtpFrom: [email protected]

這樣設定完成就可以正常發郵件了~

PS：還可以設定Webhook實現報錯自動推播到微信、釘釘之類的平臺，不細說了

AspNetCore整合

我主要使用的.Net技術棧是AspNetCore，其他專案可以參考官方檔案的整合教學

首先在ExceptionLess中建立一個專案，把APIKey複製下來

編輯AspNetCore專案的appsettings.json檔案，增加設定

"Exceptionless": {
    "ServerUrl": "http://12.0.0.1:5000",
    "ApiKey": "Rajo99MksQTS6zZK81238jTkNHNOQP33A3iW45JC"
}

然後編輯Program.cs，新增服務和中介軟體

builder.Services.AddExceptionless(builder.Configuration);
app.UseExceptionless();

整合這一步就搞定了

記錄事件

Exceptionless中的事件有以下幾種型別：

  • 紀錄檔訊息：記錄的紀錄檔，可以是任何文字內容
  • 特性使用：功能使用量的記錄，例如介面呼叫情況等
  • 異常情況：記錄異常的資訊
  • 失效連結：當被存取的頁面不存在時進行記錄

除此之外，每個事件還可以附加tags、object、UserIdentity、Description之類的資訊，有這些資訊的輔助可以方便後續排查問題。

最簡單的使用

ExceptionlessClient.Default.CreateLog("message").Submit();

CreateLog方法會放回一個EventBuilder型別的物件，之後在這個物件上進行大部分操作支援鏈式呼叫

可以像上面那樣一行程式碼鏈式呼叫，也可以這樣

// 先建立
var eventBuilder = ExceptionlessClient.Default.CreateLog("message");
// 再來慢慢新增
eventBuilder.AddObject(...);
eventBuilder.AddTags(...);
// 最後提交
eventBuilder.Submit();

可以附加到事件中的資訊有很多，下面是官網提供的一些例子

// Set the reference id of the event so we can search for it later (reference:id).
// This will automatically be populated if you call ExceptionlessClient.Default.Configuration.UseReferenceIds();
.SetReferenceId(Guid.NewGuid().ToString("N"))
// Add the order object but exclude the credit number property.
.AddObject(order, "Order", excludedPropertyNames: new [] { "CreditCardNumber" }, maxDepth: 2)
// Set the quote number.
.SetProperty("Quote", 123)
// Add an order tag.
.AddTags("Order")
// Mark critical.
.MarkAsCritical()
// Set the coordinates of the end user.
.SetGeo(43.595089, -88.444602)
// Set the user id that is in our system and provide a friendly name.
.SetUserIdentity(user.Id, user.FullName)
// Set the users description of the error.
.SetUserDescription(user.EmailAddress, "I tried creating an order from my saved quote.")

例如，使用SetUserIdentity設定了使用者資訊，在異常列表就可以看到使用者名稱，如圖

用AddTags新增標籤，在頁面中以badge的形式顯示

還有AddObject，很方便，可以直接把物件傳進去，由於C#語言有匿名物件，那就更方便了，在頁面上的「擴充套件資料」分頁上可以看到，ExceptionLess會把物件處理成表格形式，更加直觀

提交錯誤資訊

ExceptionLess提供了Exception物件的擴充套件方法

可以catch到錯誤後直接Submit

try {}
catch (Exception ex) {
    ex.ToExceptionless().Submit();
}

當然也可以附加一些資訊進去

ex.ToExceptionless().AddObject(...).Submit();

整合紀錄檔框架

除了手動提交事件，它還提供了與現有紀錄檔框架整合的方法

安裝對應的nuget包就行（簡單搜了一下，至少對Log4net和NLog的支援應該是沒啥問題的）

以與Log4net整合為例，首先安裝nuget包：Exceptionless.Log4net

附上一個簡單的Log4net設定

<log4net>
<appender name="exceptionless" type="Exceptionless.Log4net.ExceptionlessAppender,Exceptionless.Log4net">
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline"/>
  </layout>
</appender>

<root>
  <level value="DEBUG"/>
  <appender-ref ref="exceptionless"/>
</root>
</log4net>

其他語言能用嗎？

雖然官方只支援.Net平臺和前端（js呼叫、vue3），不過ExceptionLess提供了大量的HTTP介面，想要在其他語言的專案中使用，只需要呼叫對應的介面就行了，甚至可以自己封裝一個

不過在其他語言的專案中，我推薦使用Sentry（下一篇文章要介紹的），支援的語言/框架更多，ExceptionLess的優勢在於和AspNetCore這類.Net平臺的結合更好，結果頁面更直觀~

話說回來，ExceptionLess的介面檔案（Swagger）在/docs/index.html，根據部署地址存取就能看到，裡面你要的功能基本都有。

參考資料