ExceptionLess的安裝、配置、使用教程

更新時(shí)間：2022年07月23日 08:36:38 作者：程序設(shè)計(jì)實(shí)驗(yàn)室

Exceptionless?是一個(gè)開源的實(shí)時(shí)的日志收集框架，它可以應(yīng)用在基于?ASP.NET，ASP.NET?Core，Web?API，Web?Forms，WPF，Console，ASP.NET?MVC?等技術(shù)開發(fā)的應(yīng)用程序中，這篇文章給大家介紹ExceptionLess安裝使用，感興趣的朋友一起看看吧

前言

Exceptionless 是一個(gè)開源的實(shí)時(shí)的日志收集框架，它可以應(yīng)用在基于 ASP.NET，ASP.NET Core，Web API，Web Forms，WPF，Console，ASP.NET MVC 等技術(shù)開發(fā)的應(yīng)用程序中，并且提供了REST接口可以應(yīng)用在 Javascript，Node.js 中。（基本就是.Net技術(shù)棧的一套東西）

項(xiàng)目地址：https://github.com/exceptionless/Exceptionless

它將日志收集變得簡(jiǎn)單易用并且不需要了解太多的相關(guān)技術(shù)細(xì)節(jié)及配置，對(duì)于微服務(wù)架構(gòu)的應(yīng)用程序來(lái)說(shuō)，統(tǒng)一的日志收集系統(tǒng)的建立更是有必要。

要使用的話只需要在其官網(wǎng)上注冊(cè)個(gè)賬號(hào)，然后在代碼中配置一下APIKey就可以了，不過(guò)免費(fèi)版額度有限，當(dāng)然還是自己部署一套比較好，這次依然使用docker部署

安裝

docker部署可以在GitHub下載代碼自己構(gòu)建，也可以用官方打包好的鏡像，為了方便這里我直接使用官方打包的鏡像

docker-compose.yml 內(nèi)容如下

可以看到其中包含5個(gè)容器：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
      # 官方配置默認(rèn)包含HTTPS，我把它關(guān)了
      #ASPNETCORE_URLS: http://+;https://+
      ASPNETCORE_URLS: http://+
      # 關(guān)了HTTPS，這個(gè)端口也不用配置了
      #ASPNETCORE_HTTPS_PORT: 5001
      # 關(guān)了HTTPS，證書也不用配置
      #ASPNETCORE_Kestrel__Certificates__Default__Password: password
      #ASPNETCORE_Kestrel__Certificates__Default__Path: /https/aspnetapp.pfx
      EX_RunJobsInProcess: 'false'
    ports:
      - 5000:80
      # 關(guān)了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地址為你的服務(wù)器IP地址
      EX_BaseURL: http://你的IP:5000
      EX_ConnectionStrings__Cache: provider=redis
      EX_ConnectionStrings__Elasticsearch: server=http://elasticsearch:9200
      # 郵件配置
      EX_ConnectionStrings__Email: smtps://郵箱地址:密碼@SMTP服務(wù)器:端口
      EX_SmtpFrom: 發(fā)件郵箱地址
      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容器中的這兩個(gè)環(huán)境變量里配置

EX_ConnectionStrings__Email: smtps://郵箱地址:密碼@SMTP服務(wù)器:端口
EX_SmtpFrom: 發(fā)件郵箱地址

有坑的地方就是EX_ConnectionStrings__Email變量的郵箱地址需要對(duì)@符號(hào)進(jìn)行轉(zhuǎn)義，用%40代替@符號(hào)

以我的自建郵箱為例，郵箱地址是：test@dealiaxy.com，那么配置就是這樣

EX_ConnectionStrings__Email: smtps://test%40dealiaxy.com:密碼@SMTP服務(wù)器:端口
EX_SmtpFrom: test@dealiaxy.com

這樣配置完成就可以正常發(fā)郵件了~

PS：還可以配置Webhook實(shí)現(xiàn)報(bào)錯(cuò)自動(dòng)推送到微信、釘釘之類的平臺(tái)，不細(xì)說(shuō)了

AspNetCore集成

我主要使用的.Net技術(shù)棧是AspNetCore，其他項(xiàng)目可以參考官方文檔的集成教程

首先在ExceptionLess中創(chuàng)建一個(gè)項(xiàng)目，把APIKey復(fù)制下來(lái)

編輯AspNetCore項(xiàng)目的appsettings.json文件，增加配置

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

然后編輯Program.cs，添加服務(wù)和中間件

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

集成這一步就搞定了

記錄事件

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

日志消息：記錄的日志，可以是任何文本內(nèi)容
特性使用：功能使用量的記錄，例如接口調(diào)用情況等
異常情況：記錄異常的信息
失效鏈接：當(dāng)被訪問(wèn)的頁(yè)面不存在時(shí)進(jìn)行記錄

除此之外，每個(gè)事件還可以附加tags、object、UserIdentity、Description之類的信息，有這些信息的輔助可以方便后續(xù)排查問(wèn)題。

最簡(jiǎn)單的使用

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

CreateLog方法會(huì)放回一個(gè)EventBuilder類型的對(duì)象，之后在這個(gè)對(duì)象上進(jìn)行大部分操作支持鏈?zhǔn)秸{(diào)用

可以像上面那樣一行代碼鏈?zhǔn)秸{(diào)用，也可以這樣

// 先創(chuàng)建
var eventBuilder = ExceptionlessClient.Default.CreateLog("message");
// 再來(lái)慢慢添加
eventBuilder.AddObject(...);
eventBuilder.AddTags(...);
// 最后提交
eventBuilder.Submit();

可以附加到事件中的信息有很多，下面是官網(wǎng)提供的一些例子

// 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設(shè)置了用戶信息，在異常列表就可以看到用戶名，如圖

用AddTags添加標(biāo)簽，在頁(yè)面中以badge的形式顯示

還有AddObject，很方便，可以直接把對(duì)象傳進(jìn)去，由于C#語(yǔ)言有匿名對(duì)象，那就更方便了，在頁(yè)面上的“擴(kuò)展數(shù)據(jù)”標(biāo)簽頁(yè)上可以看到，ExceptionLess會(huì)把對(duì)象處理成表格形式，更加直觀

提交錯(cuò)誤信息

ExceptionLess提供了Exception對(duì)象的擴(kuò)展方法

可以catch到錯(cuò)誤后直接Submit

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

當(dāng)然也可以附加一些信息進(jìn)去

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

集成日志框架

除了手動(dòng)提交事件，它還提供了與現(xiàn)有日志框架集成的方法

安裝對(duì)應(yīng)的nuget包就行（簡(jiǎn)單搜了一下，至少對(duì)Log4net和NLog的支持應(yīng)該是沒啥問(wèn)題的）

以與Log4net集成為例，首先安裝nuget包：Exceptionless.Log4net

附上一個(gè)簡(jiǎn)單的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>