概述 -------- eLog is a Erlang logger. 基于lager3.9.2 rewrite TODO -------- trace相关代码整理 特点 -------- * 支持各种日志级别(debug、info、notice、warning、error、critical、alert、emergency) * 使用解析转换进行转换，以允许捕获 Module/Function/Line/Pid 等信息 * 当没有处理程序正在使用日志级别时(例如。没有事件被发送到日志处理器 * 支持多个后端(bkds), 包括控制台和文件 * 支持多个接收器(sinks) * 将常见的OTP错误消息改写为更易读的消息 * 在面对较大或较多的日志消息时，不会出现节点内存不足的情况 * 绕过日志大小截断的可选特性("unsafe") * 支持内部时间和日期旋转，以及外部旋转工具 * Syslog style日志级别比较标志 * 彩色的终端输出 * 可选负载削减设置高水位线杀死(并重新安装)后，可配置冷却定时器的接收器(sinks) * 重写日志的format函数，这样更有效率 接受器(Sinks) ----- eLog传统上支持名为`eLogEmm`的单一接收器(sink)(实现为`gen_emm`管理器)，所有后端都连接到该接收器。 eLog现在支持额外的接收器(sink);每个接收器(sink)可以有不同的 sync/async 消息阈值和不同的后端。 ### 接收器的配置 要使用多个接收器（超出eLog和eLog_event的内置接收器），您需要： 1. 设置rebar.config 2. 在app.config中配置后端 #### Runtime requirements ```erlang [{eLog, [ {logRoot, "/tmp"}, %% Default handlers for eLog {handlers, [ {lgBkdConsole, [{level, info}]}, {lgBkdFile, [{file, "error.log"}, {level, error}]}, {lgBkdFile, [{file, "console.log"}, {level, info}]} ]}, %% Any other sinks {extraSinks, [ {auditLgEvent, [{handlers, [{lgBkdFile, [{file, "sink1.log"}, {level, info}]}]}, {asyncThreshold, 500}, {asyncThrWindow, 50}]} ]} ]}]. ``` 自定义格式 ----------------- All loggers have a default formatting that can be overriden. A fmtTer is any module that exports `format(#lgMsg{}, Config#any())`. It is specified as part of the configuration for the backend: ```erlang {eLog, [ {handlers, [ {lgBkdConsole, [{level, info}, {fmtTer, lgFmtTer},{fmtCfg, [time, " [",severity, "] ", message, "\n"]}]}, {lgBkdFile, [{file, "error.log"}, {level, error}, {fmtTer, lgFmtTer}, {fmtCfg, [date, " ", time, " [", severity, "] ",pid, " ", message, "\n"]}]}, {lgBkdFile, [{file, "console.log"}, {level, info}]} ]} ]}. ``` 包括lgFmtTer。这使用类似于Erlang的iolist的结构（称为“ semi-iolist”）为日志消息提供了一种通用的默认格式 ： 配置中的任何传统iolist元素均按原样打印。 配置中的原子被视为较大元数据的占位符，并从日志消息中提取。 占位符date，time，message，sev并severity会一直存在。 sev是缩写的严重性，它被解释为严重性级别的大写单字母编码（例如'debug'-> $D） 占位符pid，file，line，module，function，和node 永远如果使用解析变换存在。 application如果使用解析转换，则占位符可能存在。它取决于查找应用程序app.src文件。 如果使用错误记录器集成，则占位符pid 将始终存在并且占位符name可能存在。 应用程序可以定义自己的元数据占位符。 元组{atom(), semi-iolist()}允许原子占位符的后备。如果找不到由原子表示的值，则将解释半iolist。 一个元组{atom(), semi-iolist(), semi-iolist() }代表一个条件运算符：如果可以找到原子占位符的值，则将输出第一个半iolist。否则，将使用第二个。 元组{pterm, atom()}将尝试从 OTP 21.2中添加的persistent_term功能中查找指定原子的值 。默认值为"" 。如果找不到密钥或在OTP 21之前的OTP版本中指定了此格式术语，则将使用默认值。 元组{pterm, atom(), semi-iolist()}将尝试从OTP 21.2中添加的persistent_term功能中查找指定原子的值。默认值为指定的semi-iolist（）。如果找不到密钥，或者在OTP 21之前的OTP版本中指定了此格式术语，则将使用默认值。 Examples: ``` ["Foo"] -> "Foo", regardless of message content. [message] -> The content of the logged message, alone. [{pid,"Unknown Pid"}] -> "" if pid is in the metadata, "Unknown Pid" if not. [{pid, ["My pid is ", pid], ["Unknown Pid"]}] -> if pid is in the metadata print "My pid is ", otherwise print "Unknown Pid" [{server,{pid, ["(", pid, ")"], ["(Unknown Server)"]}}] -> user provided server metadata, otherwise "()", otherwise "(Unknown Server)" [{pterm, pterm_key, <<"undef">>}] -> if a value for 'pterm_key' is found in OTP 21 (or later) persistent_term storage it is used, otherwise "undefined" ``` 错误记录器集成 ------------------------ error_logger eLog还提供了一个处理程序模块，该模块将传统的erlang错误消息转换为更友好的格式，并将其发送到eLog中，以像常规eLog日志调用一样对待。 要禁用此功能，请将更大的应用程序变量设置errLoggerRedirect为false。您也可以通过设置变量OTP和牛仔消息禁用重新格式化 errLoggerFmtRaw 为 true。 如果您将自己的处理程序安装到中error_logger，则可以通过使用errLoggerWhitelist环境变量和允许的处理程序列表来告诉eLog使其不被处理。 ``` {errLoggerWhitelist, [my_handler]} ``` 该error_logger处理器也将记录较完整的错误信息（使用的保护trunc_io）到“崩溃日志”，它可以被称为进一步的信息。崩溃日志的位置可以由crash_log 应用程序变量指定。如果设置为false完全不写入。 崩溃日志中的消息受最大消息大小的限制，可以通过crashLogMsgSize应用程序变量指定最大消息大小。 如果已定义来自的消息，error_logger则将其重定向到接收器lgErrLoggerH，以便可以将其重定向到另一个日志文件。 例如： ``` [{eLog, [ {extraSinks, [ {error_logger_event, [{handlers, [ {lgBkdFile, [{file, "error_logger.log"}, {level, info}]}]}] }] }] }]. ``` will send all `error_logger` messages to `error_logger.log` file. 过载保护 ------------------- ### 异步模式 在eLog 2.0之前，eLog的核心纯粹是在同步模式下运行。异步模式速度更快，但是无法防止消息队列过载。从更大的2.0开始，gen_event采用了一种混合方法。 它轮询自己的邮箱大小，并根据邮箱大小在同步和异步之间切换消息传递。 ```erlang {asyncThreshold, 20}, {asyncThrWindow, 5} ``` 这将使用异步消息传递，直到邮箱超过20条消息为止，此时将使用同步消息传递，并在大小减小为时切换回异步20 - 5 = 15。 如果您想禁用此行为，只需设置async_threshold为undefined。它默认为一个较小的数字，以防止邮箱迅速增长超过限制并引起问题。通常，较大的消息应尽可能快地处理它们，因此无论如何落后20条消息都是相对异常的。 如果要限制每秒允许的消息数error_logger，如果要在许多相关进程崩溃时应对大量消息，这是一个好主意，则可以设置一个限制： ```erlang {errLoggerHwm, 50} ``` 最好将此数字保持较小。 ### 事件队列刷新 超过高水位标记时，可以将eLog配置为刷新消息队列中的所有事件通知。这可能会对同一事件管理器（例如中的error_logger）中的其他处理程序产生意想不到的后果，因为它们所依赖的事件可能会被错误地丢弃。默认情况下，此行为已启用，但可以通过以下方式进行控制error_logger： ```erlang {errLoggerFlushQueue, true | false} ``` or for a specific sink, using the option: ```erlang {flushQueue, true | false} ``` 如果flushQueue为true，则可以设置消息队列长度阈值，在该阈值处将开始丢弃消息。默认阈值为0，这意味着如果flushQueue为true，则超过高水位标记时将丢弃消息，而不管消息队列的长度如何。用于控制阈值的选项是error_logger： ```erlang {errLoggerFlushThr, 1000} ``` and for sinks: ```erlang {flushThreshold, 1000} ``` ### 接收器(Sink) Killer 在某些高容量情况下，最好丢弃所有待处理的日志消息，而不是让它们随着时间流失。 如果您愿意，可以选择使用水槽杀手来减轻负载。在此操作模式下，如果gen_event邮箱超过可配置的高水位线，则在可配置的冷却时间后，水槽将被杀死并重新安装。 您可以使用以下配置指令来配置此行为： ```erlang {killerHwm, 1000}, {killerReTime, 5000} ``` 这意味着，如果接收器的邮箱大小超过1000条消息，请杀死整个接收器并在5000毫秒后重新加载它。如果需要，此行为也可以安装到其他水槽中。 默认情况下，管理器杀手未安装到任何接收器中。如果killerReTime未指定冷却时间，则默认为5000。 "不安全" -------- 不安全的代码路径会绕过普通的格式代码，并使用与OTP中的error_logger相同的代码。这可以稍微提高您的日志记录代码的速度（在基准测试期间，我们测得的改进幅度为0.5-1.3％；其他报告的改进则更好。） 这是一个危险的功能。它不会保护您免受大型日志消息的侵害-大型消息可能会杀死您的应用程序，甚至由于内存耗尽而导致Erlang VM死机，因为在故障级联中反复复制大量术语。我们强烈建议此代码路径仅用于上限大小约为500字节的有边界的日志消息。 如果日志消息有可能超过该限制，则应使用常规的更大的消息格式化代码，该代码将提供适当的大小限制并防止内存耗尽。 如果要格式化不安全的日志消息，则可以使用严重性级别（照常），然后使用_unsafe。这是一个例子： 运行时日志级别更改 ------------------------ 您可以通过执行以下操作在运行时更改任何大型后端的日志级别： ```erlang eLog:setLoglevel(lgBkdFileConsole, debug). ``` Or, for the backend with multiple handles (files, mainly): ```erlang eLog:setLoglevel(lgBkdFile, "console.log", debug). ``` eLog会跟踪任何后端使用的最低日志级别，并禁止生成低于该级别的消息。这意味着当没有后端使用调试消息时，调试日志消息实际上是免费的。一个简单的基准测试，它可以在不超过最小阈值的情况下完成一百万条调试日志消息，而所需时间不到半秒。 Syslog样式日志级别比较标志 -------------------------------------- 除了常规的日志级别名称，您还可以对要记录的内容进行更细粒度的屏蔽： ``` info - info and higher (>= is implicit) =debug - only the debug level !=info - everything but the info level <=notice - notice and below "}]) ``` ### 过滤表达式 从更大的3.3.1版本开始，您还可以在跟踪第二个元素是比较运算符的地方使用3元组。当前支持的比较运算符为： * `<` - less than * `=<` - less than or equal * `=` - equal to * `!=` - not equal to * `>` - greater than * `>=` - greater than or equal ```erlang eLog:trace_console([{request, '>', 117}, {request, '<', 120}]) ``` Using `=` is equivalent to the 2-tuple form. ### Filter composition 作为eLog3.3.1，你也可以使用的特殊滤光器构成键 all或any。例如，上面的过滤器示例可以表示为： ```erlang eLog:trace_console([{all, [{request, '>', 117}, {request, '<', 120}]}]) ``` any在过滤器之间具有“或样式”逻辑评估的效果；all 表示过滤器之间的“ AND样式”逻辑评估。这些合成过滤器期望附加过滤器表达式的列表作为它们的值。 ### 空过滤器 该null滤波器具有特殊的意义。过滤器{null, false}充当黑洞；什么都没有通过。筛选器{null, true}意味着 一切都会通过。null过滤器的其他任何值均无效，将被拒绝。 ### 支持多个接收器 如果使用多个接收器，则应注意跟踪的限制。 跟踪特定于接收器，可以通过跟踪过滤器进行指定： ```erlang eLog:trace_file("log/security.log", [{sink, audit_event}, {function, myfunction}], warning) ``` 如果未指定接收器，则将使用默认的更大接收器。 这有两个后果： 跟踪无法拦截发送到其他接收器的消息。 eLog:trace_file仅当指定了相同的接收器时，才能跟踪到已经通过打开的文件。 可以通过打开多条迹线来改善前者。后者可以通过重新配置更大的文件后端来解决，但尚未解决。 ### 配置跟踪 eLog支持从其配置文件启动跟踪。定义它们的关键字是traces，其后是一个元组属性列表，该元组定义了后端处理程序和必需列表中的零个或多个过滤器，后跟一个可选的消息严重性级别。 一个例子看起来像这样： ```erlang {eLog, [ {handlers, [...]}, {traces, [ %% handler, filter, message level (defaults to debug if not given) {lgBkdConsole, [{module, foo}], info}, {{lgBkdFile, "trace.log"}, [{request, '>', 120}], error}, {{lgBkdFile, "event.log"}, [{module, bar}]} %% implied debug level here ]} ]}. ``` 在这个例子中，我们有三个痕迹。一种使用控制台后端，另外两种使用文件后端。如果忽略了消息严重性级别，则默认debug为上一个文件后端示例中的级别。 该traces关键字也适用于其他接收器，但适用上述相同的限制和警告。 重要信息：您必须在3.1.0（含）以下的所有更大版本中定义严重性级别。直到3.2.0才添加2元组形式。 在编译时设置动态元数据 ---------------------------------------- eLog支持通过注册回调函数从外部源提供元数据。即使进程死亡，该元数据也将在整个进程中保持不变。 通常，您不需要使用此功能。但是，它在以下情况下很有用： seq_trace提供的跟踪信息 有关您的应用程序的上下文信息 默认占位符未提供的持久性信息 on_emit： 直到后端发出消息后，回调函数才能解析。 如果回调函数无法解析，未加载或产生未处理的错误，undefined则将返回该函数。 由于回调函数依赖于进程，因此有可能在依赖进程死亡导致undefined返回后发出消息。这个过程也可以是你自己的过程 on_log： 无论是否 发出消息，都将解析回调函数 如果无法解析或未加载回调函数，则eLog本身不会处理错误。 回调中的任何潜在错误都应在回调函数本身中处理。 由于该函数在日志记录时已解析，因此在解决该依赖进程之前，依赖进程死机的可能性应该较小，尤其是如果您正在从包含回调的应用程序进行日志记录时。 第三个元素是函数的回调，该函数由形式的元组组成{Module Function}。无论使用on_emit还是，回调都应如下所示on_log： 应该将其导出 它不应该接受任何参数，例如arity为0 它应该返回任何传统的iolist元素或原子 undefined 有关在回调中生成的错误，请参见上面的解析类型文档。 如果回调返回，undefined则它将遵循与“自定义格式”部分中记录的相同的后备和条件运算符规则 。 此示例可以使用，on_emit但与一起使用可能是不安全的 on_log。如果呼叫失败，on_emit则默认为undefined，但是on_log会出错。 ```erlang -export([my_callback/0]). my_callback() -> my_app_serv:call('some options'). ``` This example would be to safe to work with both `on_emit` and `on_log` ```erlang -export([my_callback/0]). my_callback() -> try my_app_serv:call('some options') of Result -> Result catch _ -> %% You could define any traditional iolist elements you wanted here undefined end. ``` 注意，回调可以是任何Module：Function / 0。它不是您的应用程序的一部分。例如，您可以 像这样将其cpu_sup:avg1/0用作 回调函数{cpu_avg1, on_emit, {cpu_sup, avg1}} 例子： ```erlang -export([reductions/0]). reductions() -> proplists:get_value(reductions, erlang:process_info(self())). ``` ```erlang -export([seq_trace/0]). seq_trace() -> case seq_trace:get_token(label) of {label, TraceLabel} -> TraceLabel; _ -> undefined end. ``` 重要信息：由于on_emit依赖于发出日志消息时注入的函数调用，因此您的日志记录性能（操作数/秒）将受到调用函数的作用以及它们可能引入多少延迟的影响。on_log由于呼叫是在记录消息的时刻注入的，因此这种影响将更大。 在编译时设置截断限制 -------------------------------------------- eLog默认将消息截断为4096字节，您可以使用该{eLog_truncation_size, X}选项进行更改。在钢筋中，您可以将其添加到 erl_opts： 禁止应用程序和主管启动/停止日志 ----------------------------------------------------- 如果您不想在应用程序的调试级别看到主管和应用程序启动/停止日志，则可以使用以下配置将其关闭： ```erlang {eLog, [{suppressAppStartStop, true}, {suppressSupStartStop, true}]} ``` 系统调试功能 -------------------- eLog提供了一种使用sys“调试功能”的集成方式。您可以通过执行以下操作在目标进程中安装调试功能： ```erlang eLog:install_trace(Pid, notice). ``` You can also customize the tracing somewhat: ```erlang eLog:install_trace(Pid, notice, [{count, 100}, {timeout, 5000}, {format_string, "my trace event ~p ~p"]}). ``` 跟踪选项当前为： 超时-跟踪保持安装的时间infinity：（默认）或毫秒超时 count-要记录的跟踪事件数：（infinity默认）或正数 format_string-用于记录事件的格式字符串。对于提供的2个参数，必须具有2个格式说明符。 这将在OTP进程的每个“系统事件”上（通常是入站消息，答复和状态更改）在指定的日志级别生成一个更大的消息。 完成以下操作后，您可以删除跟踪： ```erlang eLog:remove_trace(Pid). ``` If you want to start an OTP process with tracing enabled from the very beginning, you can do something like this: ```erlang gen_server:start_link(mymodule, [], [{debug, [{install, {fun eLog:trace_func/3, eLog:trace_state(undefined, notice, [])}}]}]). ``` trace_state函数的第三个参数是上面记录的“选项”列表。 控制台输出到另一个组长进程 ---------------------------------------------- 如果要将控制台输出发送到另一个group_leader（通常在另一个节点上），则可以为{group_leader, Pid}控制台后端提供一个参数。 可以将其与另一个控制台配置选项id和gen_event结合使用，{Module, ID}以允许通过nodetool远程跟踪节点以进行标准输出： ```erlang GL = erlang:group_leader(), Node = node(GL), eLog_app:start_handler(eLog_event, {eLog_console_backend, Node}, [{group_leader, GL}, {level, none}, {id, {eLog_console_backend, Node}}]), case eLog:trace({eLog_console_backend, Node}, Filter, Level) of ... ``` 在上面的示例中，假定代码正在通过nodetool rpc 调用运行，以便代码在Erlang节点上执行，但是group_leader是reltool节点的代码（例如appname_maint_12345@127.0.0.1）。 如果打算将此功能与跟踪配合使用，请确保start_handler的第二个参数与该id参数匹配。因此，当自定义group_leader进程退出时，eLog将删除该处理程序的所有关联跟踪。