跳转到主要内容
插件应通过内核提供的日志记录功能写入诊断信息。 这样,无论插件是以 WASM 还是 gRPC 方式运行,它都会将插件日志记录发送到与内核消息相同的结构化日志流中。 插件日志记录边界接受级别和消息类型。插件不会选择输出格式、配置全局日志级别或自行写入 componentfrom 字段。

日志级别

使用能够描述消息操作含义的级别: 内核使用全局 [Log].Level 设置来过滤插件记录。 例如,当内核以 info 级别运行时,插件的 debug 记录不会被输出。 有关全局格式、级别和输出行为,请参阅 日志配置 对于操作员在正常操作期间需要的事件,请谨慎使用 info 级别。 如果内核已经为该活动提供了访问日志或传输日志,则不要为每个内部步骤或请求都输出一条信息性记录。

日志中的插件标识

内核会将以下字段添加到每个插件日志记录中:
from 是已注册的插件标识。对于 gRPC 插件, 内核从经过身份验证的主机回调中获取此标识。对于 WASM 插件, 此标识来自内核建立的插件上下文。插件不能将此值替换为任意源名称。 JSON 和文本输出使用相同的标识。例如,一条 JSON 记录可能如下所示:

消息和结构化上下文

当前的插件日志记录规范包含日志级别和一条消息字符串。它不为插件记录提供任意的键值对属性映射。请保持消息简洁,并在需要时包含稳定的上下文以理解事件:
请勿在消息中包含密码、令牌、请求体、Socket.IO 有效负载、密钥或其他敏感数据。日志集中存储在 内核中,并且可以在插件进程之外收集。

调试源位置

当内核使用 Level = "debug" 时,其日志记录器会在记录中添加 source 字段。 这是内核宿主层中日志记录器的调用位置。 它可以帮助诊断宿主边界,但它并非插件自身源代码中可靠的文件和行位置。 使用消息上下文来识别您正在诊断的插件操作。 不要依赖调试的 source 字段作为插件堆栈跟踪。

记录失败

日志记录不应取代错误处理。当操作失败时,返回或传播错误,并在操作需要操作员可见时添加日志记录。 包含足够的上下文来识别操作,但不要暴露其输入数据。 当插件可以使用回退继续运行时,使用 warn。当操作失败且插件无法提供预期结果时,使用 error。 对于在 info 下会过于嘈杂的成功诊断路径,使用 debug 内核为所有受支持的插件后端提供相同的日志记录行为。 您的插件日志记录代码应使用为其所选后端生成的宿主绑定, 而不是直接写入特定于后端的输出流。