mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-20 23:22:05 +08:00
40f9601379
* Revert "feat: optimize minapp cache with LRU (#8160)"
This reverts commit f0043b4be5.
* feat: integrate logger service and enhance logging throughout the application
- Added a new LoggerService to standardize logging across the application.
- Replaced console.error and console.warn calls with logger methods for improved consistency and error tracking.
- Introduced a new IPC channel for logging messages to the main process.
- Updated various components and services to utilize the new logging system, enhancing error handling and debugging capabilities.
* refactor: enhance logging and error handling across various components
- Integrated the LoggerService for consistent logging throughout the application.
- Updated multiple components and services to utilize the new logging system, improving error tracking and debugging capabilities.
- Refactored file handling and error management in several services to enhance reliability and clarity.
- Improved the structure and readability of the codebase by removing redundant checks and simplifying logic.
* chore: update TypeScript configuration and enhance test setup
- Added test mock paths to tsconfig.web.json for improved test coverage.
- Configured Vitest to include a setup file for main tests, ensuring consistent test environment.
- Updated IPC logger context for better clarity in logging.
- Enhanced LoggerService to handle undefined values gracefully.
- Mocked LoggerService globally in renderer tests to streamline testing process.
* refactor: standardize logging across ProxyManager and ReduxService
- Replaced instances of Logger with logger for consistent logging implementation.
- Improved logging clarity in ProxyManager's configureProxy method and ReduxService's state handling.
- Enhanced error logging in ReduxService to align with the new logging system.
* refactor: reorganize LoggerService for improved clarity and consistency
- Moved the definition of SYSTEM_INFO, APP_VERSION, and DEFAULT_LEVEL to enhance code organization.
- Simplified the getIsDev function in the renderer LoggerService for better readability.
- Updated logging conditions to ensure messages are logged correctly based on context.
* docs: add usage instructions for LoggerService and clean up logging code
- Included important usage instructions for LoggerService in both English and Chinese.
- Commented out the console transport in LoggerService to streamline logging.
- Improved logging message formatting in MCPService for clarity.
- Removed redundant logging statements in SelectionService to enhance code cleanliness.
* refactor: update LoggerService documentation paths and enhance logging implementation
- Changed the documentation paths for LoggerService usage instructions to `docs/technical/how-to-use-logger-en.md` and `docs/technical/how-to-use-logger-zh.md`.
- Replaced console logging with the loggerService in various components, including `MCPSettings`, `BlockManager`, and multiple callback files, to ensure consistent logging practices across the application.
- Improved the clarity and context of log messages for better debugging and monitoring.
* docs: emphasize logger usage guidelines in documentation
- Added a note in both English and Chinese documentation to discourage the use of `console.xxx` for logging unless necessary, promoting consistent logging practices across the application.
134 lines
8.7 KiB
Markdown
134 lines
8.7 KiB
Markdown
# How to use the LoggerService
|
|
|
|
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**
|
|
|
|
The following are detailed instructions.
|
|
|
|
## Usage in the `main` process
|
|
|
|
### Importing
|
|
|
|
```typescript
|
|
import { loggerService } from '@logger'
|
|
```
|
|
|
|
### Setting module information (Required by convention)
|
|
|
|
After the import statements, set it up as follows:
|
|
|
|
```typescript
|
|
const logger = loggerService.withContext('moduleName')
|
|
```
|
|
|
|
- `moduleName` is the name of the current file's module. It can be named after the filename, main class name, main function name, etc. The principle is to be clear and understandable.
|
|
- `moduleName` will be printed in the terminal and will also be present in the file log, making it easier to filter.
|
|
|
|
### Setting `CONTEXT` information (Optional)
|
|
|
|
In `withContext`, you can also set other `CONTEXT` information:
|
|
|
|
```typescript
|
|
const logger = loggerService.withContext('moduleName', CONTEXT)
|
|
```
|
|
|
|
- `CONTEXT` is an object of the form `{ key: value, ... }`.
|
|
- `CONTEXT` information will not be printed in the terminal, but it will be recorded in the file log, making it easier to filter.
|
|
|
|
### Logging
|
|
|
|
In your code, you can call `logger` at any time to record logs. The supported methods are: `error`, `warn`, `info`, `verbose`, `debug`, `silly`.
|
|
For the meaning of each level, please refer to the section below.
|
|
|
|
The following examples show how to use `logger.info` and `logger.error`. Other levels are used in the same way:
|
|
```typescript
|
|
logger.info('message', CONTEXT)
|
|
logger.info('message %s %d', 'hello', 123, CONTEXT)
|
|
logger.error('message', new Error('error message'), CONTEXT)
|
|
```
|
|
- `message` is a required string. All other options are optional.
|
|
- `CONTEXT` as `{ key: value, ... }` is optional and will be recorded in the log file.
|
|
- If an `Error` type is passed, the error stack will be automatically recorded.
|
|
|
|
### Log Levels
|
|
|
|
- In the development environment, all log levels are printed to the terminal and recorded in the file log.
|
|
- In the production environment, the default log level is `info`. Logs are only recorded to the file and are not printed to the terminal.
|
|
|
|
Changing the log level:
|
|
- You can change the log level with `logger.setLevel('newLevel')`.
|
|
- `logger.resetLevel()` resets it to the default level.
|
|
- `logger.getLevel()` gets the current log level.
|
|
|
|
**Note:** Changing the log level has a global effect. Please do not change it arbitrarily in your code unless you are very clear about what you are doing.
|
|
|
|
## Usage in the `renderer` process
|
|
|
|
Usage in the `renderer` process for *importing*, *setting module information*, and *setting context information* is **exactly the same** as in the `main` process.
|
|
The following section focuses on the differences.
|
|
|
|
### `initWindowSource`
|
|
|
|
In the `renderer` process, there are different `window`s. Before starting to use the `logger`, we must set the `window` information:
|
|
|
|
```typescript
|
|
loggerService.initWindowSource('windowName')
|
|
```
|
|
|
|
As a rule, we will set this in the `window`'s `entryPoint.tsx`. This ensures that `windowName` is set before it's used.
|
|
- 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.
|
|
|
|
### Log Levels
|
|
|
|
- In the development environment, all log levels are printed to the `devTool`'s `console` by default.
|
|
- In the production environment, the default log level is `info`, and logs are printed to the `devTool`'s `console`.
|
|
- In both development and production environments, `warn` and `error` level logs are, by default, transmitted to the `main` process and recorded in the file log.
|
|
- In the development environment, the `main` process terminal will also print the logs transmitted from the renderer.
|
|
|
|
#### Changing the Log Level
|
|
|
|
Same as in the `main` process, you can manage the log level using `setLevel('level')`, `resetLevel()`, and `getLevel()`.
|
|
Similarly, changing the log level is a global adjustment.
|
|
|
|
#### Changing the Level Transmitted to `main`
|
|
|
|
Logs from the `renderer` are sent to `main` to be managed and recorded to a file centrally (according to `main`'s file logging level). By default, only `warn` and `error` level logs are transmitted to `main`.
|
|
|
|
There are two ways to change the log level for transmission to `main`:
|
|
|
|
##### Global Change
|
|
|
|
The following methods can be used to set, reset, and get the log level for transmission to `main`, respectively.
|
|
|
|
```typescript
|
|
logger.setLogToMainLevel('newLevel')
|
|
logger.resetLogToMainLevel()
|
|
logger.getLogToMainLevel()
|
|
```
|
|
**Note:** This method has a global effect. Please do not change it arbitrarily in your code unless you are very clear about what you are doing.
|
|
|
|
|
|
##### Per-log Change
|
|
|
|
By adding `{ logToMain: true }` at the end of the log call, you can force a single log entry to be transmitted to `main` (bypassing the global log level restriction), for example:
|
|
|
|
```typescript
|
|
logger.info('message', { logToMain: true })
|
|
```
|
|
|
|
## Log Level Usage Guidelines
|
|
|
|
There are many log levels. The following are the guidelines that should be followed in CherryStudio for when to use each level:
|
|
(Arranged from highest to lowest log level)
|
|
|
|
| Log Level | Core Definition & Use Case | Example |
|
|
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`error`** | **Critical error causing the program to crash or core functionality to become unusable.** <br> This is the highest-priority log, usually requiring immediate reporting or user notification. | - Main or renderer process crash. <br> - Failure to read/write critical user data files (e.g., database, configuration files), preventing the application from running. <br> - All unhandled exceptions. |
|
|
| **`warn`** | **Potential issue or unexpected situation that does not affect the program's core functionality.** <br> The program can recover or use a fallback. | - Configuration file `settings.json` is missing; started with default settings. <br> - Auto-update check failed, but does not affect the use of the current version. <br> - A non-essential plugin failed to load. |
|
|
| **`info`** | **Records application lifecycle events and key user actions.** <br> This is the default level that should be recorded in a production release to trace the user's main operational path. | - Application start, exit. <br> - User successfully opens/saves a file. <br> - Main window created/closed. <br> - Starting an important task (e.g., "Start video export"). |
|
|
| **`verbose`** | **More detailed flow information than `info`, used for tracing specific features.** <br> Enabled when diagnosing issues with a specific feature to help understand the internal execution flow. | - Loading `Toolbar` module. <br> - IPC message `open-file-dialog` sent from the renderer process. <br> - Applying filter 'Sepia' to the image. |
|
|
| **`debug`** | **Detailed diagnostic information used during development and debugging.** <br> **Must not be enabled by default in production releases**, as it may contain sensitive data and impact performance. | - Parameters for function `renderImage`: `{ width: 800, ... }`. <br> - Specific data content received by IPC message `save-file`. <br> - Details of Redux/Vuex state changes in the renderer process. |
|
|
| **`silly`** | **The most detailed, low-level information, used only for extreme debugging.** <br> Rarely used in regular development; only for solving very difficult problems. | - Real-time mouse coordinates `(x: 150, y: 320)`. <br> - Size of each data chunk when reading a file. <br> - Time taken for each rendered frame. | |