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)的大小。
- 每一次渲染帧的耗时。 |