diff --git a/docs/technical/how-to-use-logger-en.md b/docs/technical/how-to-use-logger-en.md
index b07985f5d2..60e4f5e198 100644
--- a/docs/technical/how-to-use-logger-en.md
+++ b/docs/technical/how-to-use-logger-en.md
@@ -2,7 +2,7 @@
This is a developer document on how to use the logger.
-CherryStudio uses a unified logging service to print and record logs. **Unless there is a special reason, do not use `console.xxx` to print logs**
+CherryStudio uses a unified logging service to print and record logs. **Unless there is a special reason, do not use `console.xxx` to print logs**.
The following are detailed instructions.
@@ -50,7 +50,7 @@ logger.LEVEL(message, error)
logger.LEVEL(message, error, CONTEXT)
```
-**Only the four calling methods above are supported**:
+**Only the four calling methods above are supported**.
| Parameter | Type | Description |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -58,6 +58,13 @@ logger.LEVEL(message, error, CONTEXT)
| `CONTEXT` | `object` | Optional. Additional information to be recorded in the log file. It is recommended to use the `{ key: value, ...}` format. |
| `error` | `Error` | Optional. The error stack trace will also be printed.
Note that the `error` caught by `catch(error)` is of the `unknown` type. According to TypeScript best practices, you should first use `instanceof` for type checking. If you are certain it is an `Error` type, you can also use a type assertion like `as Error`. |
+#### Recording non-`object` type context information
+
+```typescript
+const foo = getFoo()
+logger.debug(`foo ${foo}`)
+```
+
### Log Levels
- In the development environment, all log levels are printed to the terminal and recorded in the file log.
@@ -89,7 +96,7 @@ As a rule, we will set this in the `window`'s `entryPoint.tsx`. This ensures tha
- An error will be thrown if `windowName` is not set, and the `logger` will not work.
- `windowName` can only be set once; subsequent attempts to set it will have no effect.
- `windowName` will not be printed in the `devTool`'s `console`, but it will be recorded in the `main` process terminal and the file log.
-- `initWindowSource` returns the LoggerService instance, allowing for method chaining
+- `initWindowSource` returns the LoggerService instance, allowing for method chaining.
### Log Levels
@@ -150,12 +157,12 @@ In a development environment, you can define environment variables to filter dis
Environment variables can be set in the terminal or defined in the `.env` file in the project's root directory. The available variables are as follows:
-| Variable Name | Description |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CSLOGGER_MAIN_LEVEL | Log level for the `main` process. Logs below this level will not be displayed. |
-| CSLOGGER_MAIN_SHOW_MODULES | Filters log modules for the `main` process. Use a comma (`,`) to separate modules. The filter is case-sensitive. Only logs from modules in this list will be displayed. |
-| CSLOGGER_RENDERER_LEVEL | Log level for the `renderer` process. Logs below this level will not be displayed. |
-| CSLOGGER_RENDERER_SHOW_MODULES | Filters log modules for the `renderer` process. Use a comma (`,`) to separate modules. The filter is case-sensitive. Only logs from modules in this list will be displayed. |
+| Variable Name | Description |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CSLOGGER_MAIN_LEVEL` | Log level for the `main` process. Logs below this level will not be displayed. |
+| `CSLOGGER_MAIN_SHOW_MODULES` | Filters log modules for the `main` process. Use a comma (`,`) to separate modules. The filter is case-sensitive. Only logs from modules in this list will be displayed. |
+| `CSLOGGER_RENDERER_LEVEL` | Log level for the `renderer` process. Logs below this level will not be displayed. |
+| `CSLOGGER_RENDERER_SHOW_MODULES` | Filters log modules for the `renderer` process. Use a comma (`,`) to separate modules. The filter is case-sensitive. Only logs from modules in this list will be displayed. |
Example:
diff --git a/docs/technical/how-to-use-logger-zh.md b/docs/technical/how-to-use-logger-zh.md
index d9a0861ee3..f10f2149c9 100644
--- a/docs/technical/how-to-use-logger-zh.md
+++ b/docs/technical/how-to-use-logger-zh.md
@@ -2,9 +2,9 @@
这是关于如何使用日志的开发者文档。
-CherryStudio使用统一的日志服务来打印和记录日志,**若无特殊原因,请勿使用`console.xxx`来打印日志**
+CherryStudio使用统一的日志服务来打印和记录日志,**若无特殊原因,请勿使用`console.xxx`来打印日志**。
-以下是详细说明
+以下是详细说明。
## 在`main`进程中使用
@@ -23,7 +23,7 @@ const logger = loggerService.withContext('moduleName')
```
- `moduleName`是当前文件模块的名称,命名可以以文件名、主类名、主函数名等,原则是清晰明了
-- `moduleName`会在终端中打印出来,也会在文件日志中提现,方便筛选
+- `moduleName`会在终端中打印出来,也会在文件日志中体现,方便筛选
### 设置`CONTEXT`信息(可选)
@@ -38,7 +38,8 @@ const logger = loggerService.withContext('moduleName', CONTEXT)
### 记录日志
-在代码中,可以随时调用 `logger` 来记录日志,支持的级别有:`error`, `warn`, `info`, `verbose`, `debug`, `silly`
+在代码中,可以随时调用 `logger` 来记录日志,支持的级别有:`error`, `warn`, `info`, `verbose`, `debug`, `silly`。
+
各级别的含义,请参考后面的章节。
以下支持的记录日志的参数(以 `logger.LEVEL` 举例如何使用,`LEVEL`指代为上述级别):
@@ -50,12 +51,20 @@ logger.LEVEL(message, error)
logger.LEVEL(message, error, CONTEXT)
```
-**只支持上述四种调用方式**:
-| 参数 | 类型 | 说明 |
-| ----- | ----- | ----- |
-| `message` | `string` | 必填项。这是日志的核心字段,记录的重点内容 |
-| `CONTEXT` | `object` | 可选。其他需要再日志文件中记录的信息,建议为`{ key: value, ...}`格式
-| `error` | `Error` | 可选。同时会打印错误堆栈信息。
注意`catch(error)`所捕获的`error`是`unknown`类型,按照`Typescript`最佳实践,请先用`instanceof`进行类型判断,如果确信一定是`Error`类型,也可用断言`as Error`。|
+**只支持上述四种调用方式**。
+
+| 参数 | 类型 | 说明 |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message` | `string` | 必填项。这是日志的核心字段,记录的重点内容 |
+| `CONTEXT` | `object` | 可选。其他需要再日志文件中记录的信息,建议为`{ key: value, ...}`格式 |
+| `error` | `Error` | 可选。同时会打印错误堆栈信息。
注意`catch(error)`所捕获的`error`是`unknown`类型,按照`Typescript`最佳实践,请先用`instanceof`进行类型判断,如果确信一定是`Error`类型,也可用断言`as Error`。 |
+
+#### 记录非`object`类型的上下文信息
+
+```typescript
+const foo = getFoo()
+logger.debug(`foo ${foo}`)
+```
### 记录级别
@@ -73,6 +82,7 @@ logger.LEVEL(message, error, CONTEXT)
## 在`renderer`进程中使用
在`renderer`进程中使用,_引入方法_、_设置`module`信息_、*设置`context`信息的方法*和`main`进程中是**完全一样**的。
+
下面着重讲一下不同之处。
### `initWindowSource`
@@ -100,6 +110,7 @@ loggerService.initWindowSource('windowName')
#### 更改日志记录级别
和`main`进程中一样,你可以通过`setLevel('level')`、`resetLevel()`和`getLevel()`来管理日志记录级别。
+
同样,该日志记录级别也是全局调整的。
#### 更改传输到`main`的级别
@@ -149,17 +160,17 @@ const logger = loggerService.initWindowSource('Worker').withContext('LetsWork')
环境变量可以在终端中自行设置,或者在开发根目录的`.env`文件中进行定义,可以定义的变量如下:
-| 变量名 | 含义 |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| CSLOGGER_MAIN_LEVEL | 用于`main`进程的日志级别,低于该级别的日志将不显示 |
-| CSLOGGER_MAIN_SHOW_MODULES | 用于`main`进程的日志module筛选,用`,`分隔,区分大小写。只有在该列表中的module的日志才会显示 |
-| CSLOGGER_RENDERER_LEVEL | 用于`renderer`进程的日志级别,低于该级别的日志将不显示 |
-| CSLOGGER_RENDERER_SHOW_MODULES | 用于`renderer`进程的日志module筛选,用`,`分隔,区分大小写。只有在该列表中的module的日志才会显示 |
+| 变量名 | 含义 |
+| -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `CSLOGGER_MAIN_LEVEL` | 用于`main`进程的日志级别,低于该级别的日志将不显示 |
+| `CSLOGGER_MAIN_SHOW_MODULES` | 用于`main`进程的日志module筛选,用`,`分隔,区分大小写。只有在该列表中的module的日志才会显示 |
+| `CSLOGGER_RENDERER_LEVEL` | 用于`renderer`进程的日志级别,低于该级别的日志将不显示 |
+| `CSLOGGER_RENDERER_SHOW_MODULES` | 用于`renderer`进程的日志module筛选,用`,`分隔,区分大小写。只有在该列表中的module的日志才会显示 |
示例:
```bash
-CSLOGGER_MAIN_LEVEL=vebose
+CSLOGGER_MAIN_LEVEL=verbose
CSLOGGER_MAIN_SHOW_MODULES=MCPService,SelectionService
```
@@ -173,11 +184,11 @@ CSLOGGER_MAIN_SHOW_MODULES=MCPService,SelectionService
日志有很多级别,什么时候应该用哪个级别,下面是在CherryStudio中应该遵循的规范:
(按日志级别从高到低排列)
-| 日志级别 | 核心定义与使用场景 | 示例 |
-| :------------ | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`error`** | **严重错误,导致程序崩溃或核心功能无法使用。**
这是最高优的日志,通常需要立即上报或提示用户。 | - 主进程或渲染进程崩溃。
- 无法读写用户关键数据文件(如数据库、配置文件),导致应用无法运行。
- 所有未捕获的异常。` |
-| **`warn`** | **潜在问题或非预期情况,但不影响程序核心功能。**
程序可以从中恢复或使用备用方案。 | - 配置文件 `settings.json` 缺失,已使用默认配置启动。
- 自动更新检查失败,但不影响当前版本使用。
- 某个非核心插件加载失败。` |
-| **`info`** | **记录应用生命周期和关键用户行为。**
这是发布版中默认应记录的级别,用于追踪用户的主要操作路径。 | - 应用启动、退出。
- 用户成功打开/保存文件。
- 主窗口创建/关闭。
- 开始执行一项重要任务(如“开始导出视频”)。` |
-| **`verbose`** | **比 `info` 更详细的流程信息,用于追踪特定功能。**
在诊断特定功能问题时开启,帮助理解内部执行流程。 | - 正在加载 `Toolbar` 模块。
- IPC 消息 `open-file-dialog` 已从渲染进程发送。
- 正在应用滤镜 'Sepia' 到图像。` |
-| **`debug`** | **开发和调试时使用的详细诊断信息。**
**严禁在发布版中默认开启**,因为它可能包含敏感数据并影响性能。 | - 函数 `renderImage` 的入参: `{ width: 800, ... }`。
- IPC 消息 `save-file` 收到的具体数据内容。
- 渲染进程中 Redux/Vuex 的 state 变更详情。` |
-| **`silly`** | **最详尽的底层信息,仅用于极限调试。**
几乎不在常规开发中使用,仅为解决棘手问题。 | - 鼠标移动的实时坐标 `(x: 150, y: 320)`。
- 读取文件时每个数据块(chunk)的大小。
- 每一次渲染帧的耗时。 |
+| 日志级别 | 核心定义与使用场景 | 示例 |
+| :------------ | :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`error`** | **严重错误,导致程序崩溃或核心功能无法使用。**
这是最高优的日志,通常需要立即上报或提示用户。 | - 主进程或渲染进程崩溃。
- 无法读写用户关键数据文件(如数据库、配置文件),导致应用无法运行。
- 所有未捕获的异常。 |
+| **`warn`** | **潜在问题或非预期情况,但不影响程序核心功能。**
程序可以从中恢复或使用备用方案。 | - 配置文件 `settings.json` 缺失,已使用默认配置启动。
- 自动更新检查失败,但不影响当前版本使用。
- 某个非核心插件加载失败。 |
+| **`info`** | **记录应用生命周期和关键用户行为。**
这是发布版中默认应记录的级别,用于追踪用户的主要操作路径。 | - 应用启动、退出。
- 用户成功打开/保存文件。
- 主窗口创建/关闭。
- 开始执行一项重要任务(如“开始导出视频”)。 |
+| **`verbose`** | **比 `info` 更详细的流程信息,用于追踪特定功能。**
在诊断特定功能问题时开启,帮助理解内部执行流程。 | - 正在加载 `Toolbar` 模块。
- IPC 消息 `open-file-dialog` 已从渲染进程发送。
- 正在应用滤镜 'Sepia' 到图像。 |
+| **`debug`** | **开发和调试时使用的详细诊断信息。**
**严禁在发布版中默认开启**,因为它可能包含敏感数据并影响性能。 | - 函数 `renderImage` 的入参: `{ width: 800, ... }`。
- IPC 消息 `save-file` 收到的具体数据内容。
- 渲染进程中 Redux/Vuex 的 state 变更详情。 |
+| **`silly`** | **最详尽的底层信息,仅用于极限调试。**
几乎不在常规开发中使用,仅为解决棘手问题。 | - 鼠标移动的实时坐标 `(x: 150, y: 320)`。
- 读取文件时每个数据块(chunk)的大小。
- 每一次渲染帧的耗时。 |