> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 日志记录

> 通过内核的统一日志记录器写入插件诊断信息。

插件应通过内核提供的日志记录功能写入诊断信息。

这样，无论插件是以 WASM 还是 gRPC 方式运行，它都会将插件日志记录发送到与内核消息相同的结构化日志流中。
插件日志记录边界接受级别和消息类型。插件不会选择输出格式、配置全局日志级别或自行写入 `component` 和 `from` 字段。

## 日志级别

使用能够描述消息操作含义的级别：

| 级别      | 用途                |
| ------- | ----------------- |
| `debug` | 用于调查行为的诊断详细信息。    |
| `info`  | 正常的生命周期和有意义的状态变化。 |
| `warn`  | 可恢复的问题或需要注意的情况。   |
| `error` | 失败的操作或阻止预期工作的情况。  |

内核使用全局 `[Log].Level` 设置来过滤插件记录。

例如，当内核以 `info` 级别运行时，插件的 `debug` 记录不会被输出。

有关全局格式、级别和输出行为，请参阅 [日志配置](../kernel/config-log)。

对于操作员在正常操作期间需要的事件，请谨慎使用 `info` 级别。

如果内核已经为该活动提供了访问日志或传输日志，则不要为每个内部步骤或请求都输出一条信息性记录。

## 日志中的插件标识

内核会将以下字段添加到每个插件日志记录中：

```text theme={null}
component=plugin from=<插件名称>
```

`from` 是已注册的插件标识。对于 gRPC 插件，
内核从经过身份验证的主机回调中获取此标识。对于 WASM 插件，
此标识来自内核建立的插件上下文。插件不能将此值替换为任意源名称。

JSON 和文本输出使用相同的标识。例如，一条 JSON 记录可能如下所示：

```json theme={null}
{
    "level": "INFO",
    "msg": "plugin initialized",
    "component": "plugin",
    "from": "my-plugin"
}
```

## 消息和结构化上下文

当前的插件日志记录规范包含日志级别和一条消息字符串。它不为插件记录提供任意的键值对属性映射。请保持消息简洁，并在需要时包含稳定的上下文以理解事件：

```text theme={null}
缓存刷新完成：items=24 source=remote
```

请勿在消息中包含密码、令牌、请求体、Socket.IO 有效负载、密钥或其他敏感数据。日志集中存储在
内核中，并且可以在插件进程之外收集。

## 调试源位置

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

## 记录失败

日志记录不应取代错误处理。当操作失败时，返回或传播错误，并在操作需要操作员可见时添加日志记录。
包含足够的上下文来识别操作，但不要暴露其输入数据。
当插件可以使用回退继续运行时，使用 `warn`。当操作失败且插件无法提供预期结果时，使用 `error`。
对于在 `info` 下会过于嘈杂的成功诊断路径，使用 `debug`。

内核为所有受支持的插件后端提供相同的日志记录行为。
您的插件日志记录代码应使用为其所选后端生成的宿主绑定，
而不是直接写入特定于后端的输出流。