> ## 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.

# 日志记录

> 配置结构化的内核和插件日志。

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

## 配置日志记录

在 `[Log]` 部分设置进程级日志记录选项：

```toml theme={null}
[Log]
Format = "json"
Level = "info"
```

| 设置       | 值                                | 描述                         |
| -------- | -------------------------------- | -------------------------- |
| `Format` | `json`, `text`                   | 选择结构化的 JSON 记录或人类可读的键值对文本。 |
| `Level`  | `debug`, `info`, `warn`, `error` | 设置日志记录器发出的最低级别。            |

默认值为 `Format = "json"` 和 `Level = "info"`。级别过滤是包含性的：`warn` 会发出警告和错误，而 `debug` 会发出所有级别的日志。

这些值不区分大小写。
配置加载时会报告配置错误。
启动时，无效的日志记录设置会导致内核使用其默认值。
重新加载期间，无效的配置会使当前配置生效。
对 `[Log]` 的更改会在内核启动时创建其日志记录器时生效；
重新加载配置会更新运行时设置（例如插件），但不会替换已在运行的日志记录器。

## 常用字段

每个内核日志都使用两个字段标识其来源：

```text theme={null}
component=kernel from=http
```

`component` 标识生成记录的信任边界。`from` 标识内核子系统。常用值包括：

* `http` 用于 HTTP 访问记录；
* `socketio` 用于记录 Socket.IO 连接和事件；
* `plugin_manager` 用于记录插件发现和生命周期；以及
* `config`、`server` 和 `cli` 用于记录配置、服务器和命令行活动。

插件通过已认证主机边界发出的日志使用以下格式：

```text theme={null}
component=plugin from=<plugin-name>
```

内核从已认证的 gRPC 回调或WASM 绑定上下文中获取插件名称。
插件无法通过提供不同的源名称来更改此归属。
插件协议本身保持不变；归属由内核的主机日志层添加。

## 调试源位置

当 `Level = "debug"` 时，日志记录器会自动添加包含应用程序调用位置的 `source`。这有助于定位发出诊断记录的代码，
但会增加每条记录的大小，并且通常也会增加日志量。

请勿将 `source` 与 `from` 混淆：

* `source` 是仅用于调试的日志记录器调用位置；
* `from` 是稳定的内核子系统或插件标识。

在 `info`、`warn` 和 `error` 级别，调用位置的 `source` 字段将被省略。

## HTTP 访问日志

内核在每次 HTTP 请求后都会发出一条访问记录，
包括由内核路由、插件 HTTP 处理程序、静态挂载点和Socket.IO HTTP 端点处理的请求。

每条记录包含：

| 字段              | 含义             |
| --------------- | -------------- |
| `method`        | HTTP 方法。       |
| `path`          | 请求路径，不包含查询字符串。 |
| `status`        | 最终 HTTP 状态码。   |
| `duration_ms`   | 请求持续时间（毫秒）。    |
| `bytes_written` | 写入的响应体字节数。     |

访问记录使用 `component=kernel` 和 `from=http`。其日志级别根据最终状态选择：

* `4xx` 响应记录为 `WARN`；
* `5xx` 响应记录为 `ERROR`；以及
* 所有其他响应记录为 `INFO`。

请求体、标头和查询字符串不包含在此访问记录中。
如果应用程序在路径段中放置敏感值，则路径可能仍然包含敏感信息。

## Socket.IO 日志

Socket.IO 记录使用 `component=kernel` 和 `from=socketio`。内核日志：

* 成功的连接和断开连接记录为 `INFO`，包括命名空间和套接字 ID；
* 不可用的命名空间和被拒绝的连接记录为 `WARN`；
* 格式错误或未声明的事件记录为 `DEBUG`；
* 成功的事件处理记录为 `DEBUG`，包括命名空间、事件、插件和 `duration_ms`；以及
* 插件处理程序、有效负载处理，或在内核无法完成操作时发出 `ERROR` 错误。

成功的事件日志永远不会包含事件有效负载。错误记录也会避免记录有效负载数据。当您需要进行精心设计的、经过清理的应用级诊断时，请使用插件自身的结构化日志记录。

## 选择日志级别

对于正常操作，请使用 `info` 级别。它包含 HTTP 访问记录、插件生命周期记录和 Socket.IO 连接状态，但不记录成功的 Socket.IO 事件。

当您需要调查被拒绝的请求、不可用的命名空间或其他可恢复的情况时，请使用 `warn` 级别。当您需要调查失败的请求或操作时，请使用 `error` 级别。

当您需要诊断路由选择、被忽略的 Socket.IO 事件、成功的事件处理或日志记录的确切调用位置时，请暂时使用 `debug` 级别。

诊断完成后，请恢复到 `info` 级别，以减少日志量并避免收集不必要的诊断细节。