跳转到主要内容
Arupa 通过一个结构化的日志记录器写入内核和插件日志。 默认输出格式为 JSON,因此可以按字段收集和搜索记录。 您可以在直接在终端中读取日志时切换到文本输出。

配置日志记录

[Log] 部分设置进程级日志记录选项:
默认值为 Format = "json"Level = "info"。级别过滤是包含性的:warn 会发出警告和错误,而 debug 会发出所有级别的日志。 这些值不区分大小写。 配置加载时会报告配置错误。 启动时,无效的日志记录设置会导致内核使用其默认值。 重新加载期间,无效的配置会使当前配置生效。 对 [Log] 的更改会在内核启动时创建其日志记录器时生效; 重新加载配置会更新运行时设置(例如插件),但不会替换已在运行的日志记录器。

常用字段

每个内核日志都使用两个字段标识其来源:
component 标识生成记录的信任边界。from 标识内核子系统。常用值包括:
  • http 用于 HTTP 访问记录;
  • socketio 用于记录 Socket.IO 连接和事件;
  • plugin_manager 用于记录插件发现和生命周期;以及
  • configservercli 用于记录配置、服务器和命令行活动。
插件通过已认证主机边界发出的日志使用以下格式:
内核从已认证的 gRPC 回调或WASM 绑定上下文中获取插件名称。 插件无法通过提供不同的源名称来更改此归属。 插件协议本身保持不变;归属由内核的主机日志层添加。

调试源位置

Level = "debug" 时,日志记录器会自动添加包含应用程序调用位置的 source。这有助于定位发出诊断记录的代码, 但会增加每条记录的大小,并且通常也会增加日志量。 请勿将 sourcefrom 混淆:
  • source 是仅用于调试的日志记录器调用位置;
  • from 是稳定的内核子系统或插件标识。
infowarnerror 级别,调用位置的 source 字段将被省略。

HTTP 访问日志

内核在每次 HTTP 请求后都会发出一条访问记录, 包括由内核路由、插件 HTTP 处理程序、静态挂载点和Socket.IO HTTP 端点处理的请求。 每条记录包含: 访问记录使用 component=kernelfrom=http。其日志级别根据最终状态选择:
  • 4xx 响应记录为 WARN
  • 5xx 响应记录为 ERROR;以及
  • 所有其他响应记录为 INFO
请求体、标头和查询字符串不包含在此访问记录中。 如果应用程序在路径段中放置敏感值,则路径可能仍然包含敏感信息。

Socket.IO 日志

Socket.IO 记录使用 component=kernelfrom=socketio。内核日志:
  • 成功的连接和断开连接记录为 INFO,包括命名空间和套接字 ID;
  • 不可用的命名空间和被拒绝的连接记录为 WARN
  • 格式错误或未声明的事件记录为 DEBUG
  • 成功的事件处理记录为 DEBUG,包括命名空间、事件、插件和 duration_ms;以及
  • 插件处理程序、有效负载处理,或在内核无法完成操作时发出 ERROR 错误。
成功的事件日志永远不会包含事件有效负载。错误记录也会避免记录有效负载数据。当您需要进行精心设计的、经过清理的应用级诊断时,请使用插件自身的结构化日志记录。

选择日志级别

对于正常操作,请使用 info 级别。它包含 HTTP 访问记录、插件生命周期记录和 Socket.IO 连接状态,但不记录成功的 Socket.IO 事件。 当您需要调查被拒绝的请求、不可用的命名空间或其他可恢复的情况时,请使用 warn 级别。当您需要调查失败的请求或操作时,请使用 error 级别。 当您需要诊断路由选择、被忽略的 Socket.IO 事件、成功的事件处理或日志记录的确切调用位置时,请暂时使用 debug 级别。 诊断完成后,请恢复到 info 级别,以减少日志量并避免收集不必要的诊断细节。