mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-19 14:41:24 +08:00
docs(logger): update logger docs (#8436)
* docs(logger): 更新日志使用文档的格式和内容 - 补充记录非object类型上下文信息的示例 - 修正环境变量格式为代码样式 - 统一中英文文档的标点符号和格式 - 修复文档中的拼写错误和示例错误 * docs: 修正日志使用文档中的标点格式 统一中英文文档中关于调用方式说明的标点格式，将中文文档的冒号改为句号以保持一致性 * docs(technical): 修正日志使用文档中的代码块标记 将环境变量示例的代码块标记从env改为bash以正确高亮显示 * docs(technical): 修正日志级别文档中的示例格式
This commit is contained in:
Phantom
GitHub
parent
1677cb7321
commit
14c3b11664
@ -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.<br />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
|
||||
|
||||
@ -151,11 +158,11 @@ 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. |
|
||||
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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:
|
||||
|
||||
|
||||
@ -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` | 可选。同时会打印错误堆栈信息。<br />注意`catch(error)`所捕获的`error`是`unknown`类型，按照`Typescript`最佳实践，请先用`instanceof`进行类型判断，如果确信一定是`Error`类型，也可用断言`as Error`。|
|
||||
| `CONTEXT` | `object` | 可选。其他需要再日志文件中记录的信息，建议为`{ key: value, ...}`格式 |
|
||||
| `error` | `Error` | 可选。同时会打印错误堆栈信息。<br />注意`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`的级别
|
||||
@ -150,16 +161,16 @@ 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
|
||||
```
|
||||
|
||||
@ -174,10 +185,10 @@ CSLOGGER_MAIN_SHOW_MODULES=MCPService,SelectionService
|
||||
(按日志级别从高到低排列)
|
||||
|
||||
| 日志级别 | 核心定义与使用场景 | 示例 |
|
||||
| :------------ | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`error`** | **严重错误，导致程序崩溃或核心功能无法使用。** <br> 这是最高优的日志，通常需要立即上报或提示用户。 | - 主进程或渲染进程崩溃。 <br> - 无法读写用户关键数据文件（如数据库、配置文件），导致应用无法运行。<br> - 所有未捕获的异常。` |
|
||||
| **`warn`** | **潜在问题或非预期情况，但不影响程序核心功能。** <br> 程序可以从中恢复或使用备用方案。 | - 配置文件 `settings.json` 缺失，已使用默认配置启动。 <br> - 自动更新检查失败，但不影响当前版本使用。<br> - 某个非核心插件加载失败。` |
|
||||
| **`info`** | **记录应用生命周期和关键用户行为。** <br> 这是发布版中默认应记录的级别，用于追踪用户的主要操作路径。 | - 应用启动、退出。<br> - 用户成功打开/保存文件。 <br> - 主窗口创建/关闭。<br> - 开始执行一项重要任务（如“开始导出视频”）。` |
|
||||
| **`verbose`** | **比 `info` 更详细的流程信息，用于追踪特定功能。** <br> 在诊断特定功能问题时开启，帮助理解内部执行流程。 | - 正在加载 `Toolbar` 模块。 <br> - IPC 消息 `open-file-dialog` 已从渲染进程发送。<br> - 正在应用滤镜 'Sepia' 到图像。` |
|
||||
| **`debug`** | **开发和调试时使用的详细诊断信息。** <br> **严禁在发布版中默认开启**，因为它可能包含敏感数据并影响性能。 | - 函数 `renderImage` 的入参: `{ width: 800, ... }`。<br> - IPC 消息 `save-file` 收到的具体数据内容。<br> - 渲染进程中 Redux/Vuex 的 state 变更详情。` |
|
||||
| :------------ | :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`error`** | **严重错误，导致程序崩溃或核心功能无法使用。** <br> 这是最高优的日志，通常需要立即上报或提示用户。 | - 主进程或渲染进程崩溃。 <br> - 无法读写用户关键数据文件（如数据库、配置文件），导致应用无法运行。<br> - 所有未捕获的异常。 |
|
||||
| **`warn`** | **潜在问题或非预期情况，但不影响程序核心功能。** <br> 程序可以从中恢复或使用备用方案。 | - 配置文件 `settings.json` 缺失，已使用默认配置启动。 <br> - 自动更新检查失败，但不影响当前版本使用。<br> - 某个非核心插件加载失败。 |
|
||||
| **`info`** | **记录应用生命周期和关键用户行为。** <br> 这是发布版中默认应记录的级别，用于追踪用户的主要操作路径。 | - 应用启动、退出。<br> - 用户成功打开/保存文件。 <br> - 主窗口创建/关闭。<br> - 开始执行一项重要任务（如“开始导出视频”）。 |
|
||||
| **`verbose`** | **比 `info` 更详细的流程信息，用于追踪特定功能。** <br> 在诊断特定功能问题时开启，帮助理解内部执行流程。 | - 正在加载 `Toolbar` 模块。 <br> - IPC 消息 `open-file-dialog` 已从渲染进程发送。<br> - 正在应用滤镜 'Sepia' 到图像。 |
|
||||
| **`debug`** | **开发和调试时使用的详细诊断信息。** <br> **严禁在发布版中默认开启**，因为它可能包含敏感数据并影响性能。 | - 函数 `renderImage` 的入参: `{ width: 800, ... }`。<br> - IPC 消息 `save-file` 收到的具体数据内容。<br> - 渲染进程中 Redux/Vuex 的 state 变更详情。 |
|
||||
| **`silly`** | **最详尽的底层信息，仅用于极限调试。** <br> 几乎不在常规开发中使用，仅为解决棘手问题。 | - 鼠标移动的实时坐标 `(x: 150, y: 320)`。<br> - 读取文件时每个数据块（chunk）的大小。<br> - 每一次渲染帧的耗时。 |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user