开源日志框架Exceptionless使用教程

exceptionless是一款日志记录框架，它开源、免费、提供管理界面、易于安装和使用。exceptionless底层采用elasticsearch作为日志存储，提供了快速、丰富的查询api，方便我们进行系统集成。本文将介绍exceptionless的常见用法。

安装exceptionless

在exceptionless官网提供了基于docker的私有化部署方式，我们可以按照官网的方式进行测试环境的安装。

1. 在官网github中下载最新的release包，地址：https://github.com/exceptionless/exceptionless/releases
2. 解压缩，然后进入解压缩的目录，执行 docker-compose up -d命令在后台启动多个容器，当执行完成后，exceptionless已经在本地运行起来了。我们可以在kitematic中查看运行中的容器
3. 按照官网的说明，5000端口是登陆页面，但实际情况是5000是api，5100才是登陆页面，因此我们打开进入登陆页面。注意：此处可能跟版本有关，在使用时查看docker的端口映射。

通过以上步骤，就在本地搭建好了测试环境。我们可以看到启动的总共启动了6个容器，分别是redis、elasticsearch、kibana、exceptionless job、exceptionless api、excetpionless ui。

快速上手

搭建好测试环境后，首先访问exceptionless ui来创建用户、组织和项目。然后，当项目创建完成之后，exceptionless 会跳转到客户端配置页面，来指引我们如何使用exceptionless客户端。我们可以选择自己需要用到的客户端，通过页面的指引完成客户端配置。

引导页面如下：

按照这种方式我们可以完成.net平台项目、js项目的配置。

客户端api：https://github.com/exceptionless/exceptionless.net/wiki

配置好以后，我们就可以记录日志了，例如（代码来源于官网）：

// import the exceptionless namespace.
using exceptionless;

// submit logs
exceptionlessclient.default.submitlog("logging made easy");

// you can also specify the log source and log level.
// we recommend specifying one of the following log levels: trace, debug, info, warn, error
exceptionlessclient.default.submitlog(typeof(program).fullname, "this is so easy", "info");
exceptionlessclient.default.createlog(typeof(program).fullname, "this is so easy", "info").addtags("exceptionless").submit();

// submit feature usages
exceptionlessclient.default.submitfeatureusage("myfeature");
exceptionlessclient.default.createfeatureusage("myfeature").addtags("exceptionless").submit();

// submit a 404
exceptionlessclient.default.submitnotfound("/somepage");
exceptionlessclient.default.createnotfound("/somepage").addtags("exceptionless").submit();

// submit a custom event type
exceptionlessclient.default.submitevent(new event { message = "low fuel", type = "racecar", source = "fuel system" });

功能介绍

exceptionless中的事件有以下几种类型：

• 日志消息：记录的日志，可以是任何文本内容
• 特性使用：功能使用量的记录，例如接口调用情况等
• 异常情况：记录异常的信息
• 失效链接：当被访问的页面不存在时进行记录

除了记录内容外，exceptionless还支持对事件添加标签、附加数据、用户描述等操作，例如（代码来源于官网）：

try {
    throw new applicationexception("unable to create order from quote.");
} catch (exception ex) {
    ex.toexceptionless()
        // 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.")
        // submit the event.
        .submit();
}

nlog、log4net集成

官方支持nlog、log4net集成的支持，只需要添加相应的日志组件的配置文件即可。以log4net为例：

首先添加程序集的支持：

install-package 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>

api接口

除了丰富的客户端功能外，exceptionless还提供了大量api的支持，这些api可以在5000端口访问到。地址为：：

通过这些接口，我们可以实现更多自定义的操作，例如用户授权、项目管理、日志查询等操作。

参考资料

• 官网：
• 源码：https://github.com/exceptionless/exceptionless