使用 JSNLog 配置您的 JavaScript 日志记录器

• 通过 Nuget 安装 JSNLog（推荐）
• 源文件和示例代码

介绍如何使用 JSNLog 配置 JavaScript 日志记录器，JSNLog 是一个与 .Net 集成良好的 JavaScript 日志记录库。它允许您在 web.config 中配置日志记录器，并允许您在不编写任何代码的情况下接收来自客户端的日志消息并将其存储在服务器上。

本系列内容

• JavaScript 日志记录的原理和方法
• 在 JavaScript 中插入日志记录器
• 在 web.config 中配置日志记录器

在 web.config 中配置日志记录器

• <jsnlog> 元素
• <logger> 元素
• <ajaxAppender> 元素
• <consoleAppender> 元素

如果您有 ASP.NET MVC 或 WebForms 网站，您可以从服务器端的 web.config 配置您的客户端日志记录器。

请注意，安装后，JSNLog 不需要任何额外的配置。您需要做的就是 在您的 JavaScript 代码中添加日志记录器 即可开始记录。.只有当您想更改默认配置时，才需要更新您的 web.config。

在 安装 过程中，一个 <jsnlog> 元素将被添加到您的 web.config 中。这是其他元素的容器。

<jsnlog> 元素

所有 JSNLog 配置元素的根元素。

定义

<configuration> 
    <jsnlog
        enabled="true|false"
        maxMessages="number"
        serverSideLogger="string"
        serverSideLevel="number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL" 
        serverSideMessageFormat="string"
        productionLibraryPath="string" >
    </jsnlog>
</configuration> 

备注

<jsnlog> 元素可以具有以下属性

Attribute	默认值	描述
enabled optional	true	如果设置为 false，则所有日志记录器都将被禁用。
maxMessages optional	无最大值	限制发送到服务器的消息总数。请参阅下面的说明。
serverSideLogger optional	（空）	默认情况下，您 JavaScript 代码中的所有日志消息都将以 JavaScript 日志记录器的名称传递给您的服务器端日志记录包。 但是，如果您想为所有 JavaScript 日志消息使用特定的日志记录器名称，您可以使用此属性进行指定。
serverSideLevel optional	（空）	默认情况下，您 JavaScript 代码中的所有日志消息都将以与原始 JavaScript 日志消息相同的级别传递给您的服务器端日志记录包。 但是，如果您想使用特定的级别，您可以使用此属性进行指定。
serverSideMessageFormat optional	%message	请参阅说明。
productionLibraryPath optional	（空）	jsnlog.js 文件的路径。JSNLog 会生成一个带有此 URL 的 <script> 标签。 如果您不指定此项，JSNLog 将不会生成 <script> 标签。例如，如果您将 jsnlog.js 与其他 JavaScript 文件合并，并使用自己的 <script> 标签加载此合并文件，那么这样做是有意义的。

maxMessages 和缓冲

您使用 maxMessages 来限制每页加载发送到服务器的消息数量。当客户端加载页面时，计数器被设置为 maxMessages。每次将消息发送到服务器时，该计数器都会减去发送的消息数量。当计数器达到零或更低时，将不再发送任何消息。

但是，这会受到 批量处理和缓冲 的影响。

设想一种情况，maxMessages 设置为 5，并且已经发送了 2 条消息 - 因此消息计数器现在是 3。如果 8 条消息已存储在缓冲区中，并且这些消息现在被发送，那么它们将被全部发送。这意味着服务器将总共收到 2 + 8 = 10 条消息。之后，将不再发送任何消息，因为发送的消息数量 (10) 超过了 maxMessages (5)。

这意味着 maxMessages 不是发送到服务器的消息数量的精确限制。另一方面，缓冲的消息会一起发送到一个请求中，从而最大限度地减少带宽。并且缓冲的消息通常对于解决异常很有用，因此接收它们是有价值的。

serverSideMessageFormat

您的服务器不仅会收到传递给 JavaScript 日志记录器的原始消息，还会收到日志记录器、级别、时间戳等信息。

您可以通过将 serverSideMessageFormat 设置为包含一个或多个占位符的格式字符串，来选择是否将此额外信息与原始消息一起记录在服务器上。

占位符	被替换为
%message	传递给 JavaScript 日志记录器的原始消息
%utcDate	根据客户端时钟生成的 UTC 日期和时间
%utcDateServer	根据服务器时钟服务器接收消息的 UTC 日期和时间
%date	根据客户端时钟生成的日期和时间。这等于 %utcDate 转换为服务器本地时间。
%dateServer	根据服务器时钟服务器接收消息的服务器本地日期和时间
%level	JavaScript 代码提供的消息级别
%userAgent	标识浏览器型号
%userHostAddress	发送者的 IP 地址
%url	生成消息的页面 URL
%logger	生成消息的 JavaScript 日志记录器
%requestId	标识创建日志消息的请求。此请求 ID 将为您自动生成。
%newline	换行符

示例

这会在每条日志消息中显示日志消息在客户端创建的日期和时间以及用户代理。

<jsnlog 
    serverSideMessageFormat="Sent: %date, Brower: %userAgent - %message" >

这会将所有客户端日志消息通过服务器端日志记录器 "jslogger" 进行处理。

<jsnlog serverSideLogger="jslogger">

这会禁用所有客户端日志记录器。

<jsnlog enabled="false">

<logger> 元素

配置一个日志记录器。

定义

<configuration> 
    <jsnlog>
        <logger 
            name="string" 
            level="number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            userAgentRegex="regular expression"
            ipRegex="regular expression"
            disallow="regular expression" 
            appenders="Appender Name(s)" >
            <onceOnly regex="regular expression" />
        </logger> 
    </jsnlog>
</configuration> 

备注

<logger> 元素可以具有以下属性

Attribute	默认值	描述
名称 optional	（空）	您要配置的日志记录器的名称。要配置根日志记录器，只需省略 name 属性。 在您的服务器端日志中，根日志记录器称为 ClientRoot。
level optional	(从父日志记录器继承)	只有严重性等于或高于此级别的消息才能发送到服务器。
userAgentRegex optional	(从父日志记录器继承)	如果不为空，则仅当此正则表达式与浏览器的 用户代理字符串 匹配时，才会处理日志消息。
ipRegex optional	(从父日志记录器继承)	如果不为空，则仅当此正则表达式与浏览器的 IP 地址匹配时，才会处理日志消息。
disallow optional	(从父日志记录器继承)	如果不为空，则当日志消息匹配此正则表达式时，将抑制这些消息。如果正在记录一个对象，它将被转换为 JSON 字符串，然后与正则表达式进行匹配。
appenders optional	(从父日志记录器继承)	一个或多个附加器，供日志记录器将日志消息发送到。请参阅示例。
onceOnly optional	(从父日志记录器继承)	一个或多个正则表达式。当消息匹配某个正则表达式时，任何随后匹配相同正则表达式的消息都将被抑制。请参阅说明和示例。

日志记录器的名称和选项继承

日志记录器不仅通过 <logger> 元素获取其选项，还可以通过继承获取。这基于每个日志记录器的名称。

假设您有一个命名空间 "namespace1" 中的方法 "method1"。那么，为您的日志记录器使用类似以下的命名方案是有意义的："namespace1.method1.logger1"、"namespace1.method1.logger2" 等。这样，就不会有名称冲突，并且可以轻松地跟踪您的日志记录器。

正如一个命名空间可能包含方法，一个方法可能包含日志记录器一样，您可以将这些日志记录器名称视为构成一个层次结构。

• "namespace1.method1.logger1" 的父级是 "namespace1.method1"；
• "namespace1.method1" 的父级是 "namespace1"；
• "namespace1" 的父级是根日志记录器（没有名称的日志记录器）。

您不限于只有 3 个级别，您可以拥有任意多个级别。

如果您没有使用 <logger> 元素设置选项,则日志记录器从其父级继承该选项。如果您根本不使用 <logger> 元素，则每个日志记录器都将具有与根日志记录器相同的选项。

根日志记录器和默认附加器

当库加载时，它会创建根日志记录器。它还会创建一个默认附加器供根日志记录器使用。

因为每个日志记录器都继承自根日志记录器（除非您使用 <logger> 元素覆盖此设置），所以您可以立即开始记录，而无需创建附加器。

根日志记录器使用以下选项创建

选项	默认值
level	DEBUG
userAgentRegex	（空）
ipRegex	（空）
disallow	（空）
appenders	(默认附加器)

请注意，由于根日志记录器的默认 level 是 DEBUG，因此默认情况下，只有严重性为 DEBUG 或更高的日志消息才会被处理。

您可以使用 <logger> 元素以与其他日志记录器相同的方式更改与根日志记录器关联的选项。请参阅下面的示例。

默认附加器使用以下选项创建（选项说明）

选项	默认值
level	TRACE
userAgentRegex	（空）
ipRegex	（空）
disallow	（空）
storeInBufferLevel	ALL
sendWithBufferLevel	关
bufferSize	0
batchSize	1
url	jsnlog.logger

使用 onceOnly 抑制重复消息

您可能会在被多次调用的代码中有日志记录器。因此，您可能会收到一系列本质上相同的消息。使用 onceOnly，您可以抑制重复的消息，只发送第一条消息到服务器。

这通过设置一个或多个正则表达式来工作。当一条日志消息匹配某个正则表达式时，日志记录器会记住曾经有一条消息匹配该正则表达式。然后，当另一条消息到达并匹配相同的正则表达式时，它将被抑制。

例如，如果您收到这些消息

    Parameter x too high - x = 5
    Parameter x too high - x = 6
    Parameter x too high - x = 7
    ...
    Parameter x too high - x = 49
    Parameter x too high - x = 50

那么您可以使用正则表达式

    Parameter x too high - x = 

以便只接收第一条消息

    Parameter x too high - x = 5

有关如何设置正则表达式的示例，请参阅示例。

您可以设置多个正则表达式。它们独立工作。因此，如果一条消息匹配第一个正则表达式，然后第二条消息匹配第二个正则表达式但不是第一个，那么第二条消息就会通过，因为它不是第一条消息的重复。

您可以记录不仅是字符串，还可以记录对象。如果您记录一个对象，该对象将被转换为 JSON 字符串。然后将该字符串与正则表达式进行匹配。

与其他属性类似，日志记录器会从其父级继承 onceOnly。但是，这是全有或全无的。如果您为日志记录器设置了 onceOnly 正则表达式，那么其父级可能拥有的任何 onceOnly 正则表达式都将被忽略。

示例

这将记录器 "a.b" 的级别设置为 3000。

<logger name="a.b" level="3000" />

这将设置根日志记录器的级别。

<logger level="3000" />

这会将记录器 "a.b" 的级别设置为 INFO（这与设置为 3000 相同）。

<logger name="a.b" level="INFO" />

这会将级别设置为 4000。它还会禁用所有浏览器的日志记录器，除了那些用户代理字符串包含 MSIE 7|MSIE 8（即 Internet Explorer 的 7 或 8 版本）的浏览器。

<logger name="a.b" userAgentRegex="MSIE 7|MSIE 8" level="4000" />

这会创建一个名为 "appender" 的附加器，然后告诉日志记录器 "a.b" 将所有日志消息发送到它。

<ajaxAppender name="appender" />
<logger name="a.b" appenders="appender" />

这会创建两个附加器，然后告诉日志记录器 "a.b" 将所有日志消息发送到它们。

<ajaxAppender name="appender1" />
<ajaxAppender name="appender2" />
<logger name="a.b" appenders="appender1;appender2" />

抑制与正则表达式 "Parameter x too high - x =" 匹配的重复消息。

<logger name="a">
    <onceOnly regex="Parameter x too high - x =" />
</logger>

抑制与正则表达式 "Parameter x too high - x =" 匹配的重复消息。同时抑制与 "x = \d+ and y = \d+" 匹配的重复消息。

<logger name="a">
    <onceOnly regex="Parameter x too high - x =" />
    <onceOnly regex="x = \d+ and y = \d+" />
</logger>

日志记录器从其父级继承 onceOnly。假设您有一个日志记录器 "a.b"，其父级 "a" 会抑制重复项，但您希望日志记录器 "a.b" 不抑制重复项。要实现这一点，请为其提供一个不带任何正则表达式的 onceOnly 集合。

<logger name="a.b">
    <onceOnly  />
</logger>

<ajaxAppender> 元素

配置一个 Ajax 附加器。

定义

<configuration> 
    <jsnlog>
        <ajaxAppender 
            name="string" 
            level="number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            userAgentRegex="regular expression"
            ipRegex="regular expression"
            disallow="regular expression"
            storeInBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            sendWithBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL" 
            bufferSize="number" 
            batchSize="number" 
            url="string" />
     </jsnlog>
</configuration> 

备注

日志记录器本身不处理日志消息。相反，它们将消息传递给附加器。这样，与发送日志消息到服务器相关的属性就集中起来了，更容易管理。

JSNLog 会创建一个默认附加器，因此您无需自己创建一个就可以开始记录。有关此默认附加器的详细信息，以及如何将日志记录器与附加器关联，请在此处 查看。.

<ajaxAppender> 元素可以具有以下属性

Attribute	默认值	描述
名称 required		您要配置的 AjaxAppender 的名称。
level optional	TRACE	只有严重性等于或高于此级别的消息才能发送到服务器。
userAgentRegex optional	（空）	如果不为空，则仅当此正则表达式与浏览器的 用户代理字符串 匹配时，才会处理日志消息。
ipRegex optional	（空）	如果不为空，则仅当此正则表达式与浏览器的 IP 地址匹配时，才会处理日志消息。
disallow optional	（空）	如果不为空，则当日志消息匹配此正则表达式时，将抑制这些消息。如果正在记录一个对象，它将被转换为 JSON 字符串，然后与正则表达式进行匹配。
storeInBufferLevel optional	ALL	如果日志消息的严重性等于或大于此值，但小于 level，则该日志消息将不会发送到服务器，而是存储在内部缓冲区中。 如果 bufferSize 为 0 或更小，则日志消息将被忽略。
sendWithBufferLevel optional	关	如果日志消息的严重性等于或大于此值，则不仅该日志消息，而且存储在内部缓冲区中的所有日志消息都将被发送到服务器。 这允许您将低优先级的跟踪消息存储在内部缓冲区中，并在发送高优先级的致命消息时才将它们发送出去。
bufferSize optional	0	设置与 sendWithBufferLevel 和 storeInBufferLevel 一起使用的缓冲区大小。
batchSize optional	1	允许您通过一次发送多个日志消息来提高性能，而不是一次一条。
url optional	jsnlog.logger	所有日志消息都将发送到此 URL。默认 URL 与 JSNLog 的服务器端代码所期望的 URL 相同。

日志记录器级别和附加器级别

请注意，日志记录器 和附加器都有一个级别。这意味着日志消息的严重性必须同时等于或高于这两个级别才能被处理。

示例

这会创建一个具有以下行为的附加器，然后将其附加到根日志记录器。

• 它有一个内部缓冲区，最多存储 20 条日志消息；
• 严重性小于 TRACE 的日志消息将被忽略。
• 严重性等于或大于 TRACE 但小于 WARN 的日志消息将存储在内部缓冲区中，但不会发送到服务器；
• 严重性等于或大于 WARN 但小于 FATAL 的日志消息将单独发送到服务器；
• 严重性等于或大于 FATAL 的日志消息将与内部缓冲区中的所有消息一起发送到服务器。

<ajaxAppender 
    name="appender1" 
    storeInBufferLevel="TRACE" 
    level="WARN" 
    sendWithBufferLevel="FATAL" 
    bufferSize="20"/>
<logger appenders="appender1"/>

<consoleAppender> 元素

配置一个控制台附加器。

定义

<configuration> 
    <jsnlog>
        <consoleAppender 
            name="string" 
            level="number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            userAgentRegex="regular expression"
            ipRegex="regular expression"
            disallow="regular expression"
            storeInBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            sendWithBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL" 
            bufferSize="number" 
            batchSize="number" 
        />
    </jsnlog>
</configuration> 

备注

JSNLog 基于集成客户端和服务器端日志记录的理念 - 使用 <ajaxAppender> 元素 将日志项发送到服务器。

然而，在开发过程中，将日志项简单地发送到 F12 开发者工具提供的控制台中可能很有用，这些工具在 Chrome、Firefox 和 Internet Explorer 中可用。

这样，日志项就会立即出现在主浏览器窗口下方，您不必检查服务器端日志。

将日志项从日志记录器发送到控制台

要查看由日志记录器生成的日志项在控制台中，您首先需要创建一个 ConsoleAppender，然后使用日志记录器的 <logger> 元素 将所有日志项发送到该 ConsoleAppender。

<!-- "mylogger" logs to just the console -->
<consoleAppender name="consoleAppender" />
<logger name="mylogger" appenders="consoleAppender" />

但是，这意味着所有日志项将只发送到控制台，而不再发送到服务器。如果您希望日志项同时发送到控制台和服务器，那么请将它们发送到 AjaxAppender 以及 ConsoleAppender。

<!-- "mylogger" logs to both the server and the console -->
<consoleAppender name="consoleAppender" />
<ajaxAppender name="ajaxAppender" />
<logger name="mylogger" appenders="ajaxAppender;consoleAppender" />

将每个日志记录器的日志项发送到控制台和服务器

最简单的方法可能是让所有日志记录器同时记录到控制台和服务器。您可以通过使用根日志记录器的 <logger> 元素 来实现这一点。通过 继承，其他所有日志记录器也将开始同时记录到控制台和服务器。

<!-- Debugging: all loggers log to both the server and the console -->
<consoleAppender name="consoleAppender" />
<ajaxAppender name="ajaxAppender" />
<logger appenders="ajaxAppender;consoleAppender" />

关闭到控制台的日志记录

生产环境运行时，您可能希望停止向控制台进行日志记录。您可以通过移除 ConsoleAppender 来实现这一点。

<!-- Production: loggers log to the server only -->
<ajaxAppender name="ajaxAppender" />
<logger appenders="ajaxAppender" />

这意味着您不必遍历代码来删除日志记录代码 - 仅更改 web.config 就足够了。请记住，如果您将单个日志记录器与 ConsoleAppender 关联，您也需要删除它才能停止所有到控制台的日志记录。

属性

<consoleAppender> 元素可以具有以下属性

Attribute	默认值	描述
名称 required		您要配置的 ConsoleAppender 的名称。
level optional	TRACE	只有严重性等于或高于此级别的消息才能发送到服务器。
userAgentRegex optional	（空）	如果不为空，则仅当此正则表达式与浏览器的 用户代理字符串 匹配时，才会处理日志消息。
ipRegex optional	（空）	如果不为空，则仅当此正则表达式与浏览器的 IP 地址匹配时，才会处理日志消息。
disallow optional	（空）	如果不为空，则当日志消息匹配此正则表达式时，将抑制这些消息。如果正在记录一个对象，它将被转换为 JSON 字符串，然后与正则表达式进行匹配。
storeInBufferLevel optional	ALL	如果日志消息的严重性等于或大于此值，但小于 level，则该日志消息将不会发送到服务器，而是存储在内部缓冲区中。 如果 bufferSize 为 0 或更小，则日志消息将被忽略。
sendWithBufferLevel optional	关	如果日志消息的严重性等于或大于此值，则不仅该日志消息，而且存储在内部缓冲区中的所有日志消息都将被发送到服务器。 这允许您将低优先级的跟踪消息存储在内部缓冲区中，并在发送高优先级的致命消息时才将它们发送出去。
bufferSize optional	0	设置与 sendWithBufferLevel 和 storeInBufferLevel 一起使用的缓冲区大小。
batchSize optional	1	允许您通过一次发送多个日志消息来提高性能，而不是一次一条。

日志记录器级别和附加器级别

请注意，日志记录器 和附加器都有一个级别。这意味着日志消息的严重性必须同时等于或高于这两个级别才能被处理。