# 日志组件

agentUniverse的日志组件基于loguru实现，提供封装好的全局日志组件和定制日志组件。本教程将首先介绍agentUniverse中关于日志的配置文件使用方式，然后依次介绍关于全局日志组件和定制日志组件的使用方式，并在最后介绍如何对接外部的日志服务组件。
## 日志配置

### 配置文件路径
日志文件的配置路径会在agentUniverse的主配置config.toml中指定
```toml
[SUB_CONFIG_PATH]
# Log config file path, an absolute path or a relative path based on the dir where the current config file is located.
log_config_path = './log_config.toml'
```
如果该参数为相对路径形式，对应的父目录为主配置config.toml所在目录。
如果该参数不存在，则agentUniverse会使用默认日志配置，具体配置参考[默认配置](#默认配置)

### 配置文件选项
日志的配置文件为toml文件格式，一个示例配置如下。
```toml
[LOG_CONFIG]
[LOG_CONFIG.BASIC_CONFIG]
log_level = "INFO"
log_path = "~/.agent_universe_log"
log_rotation = "100 MB"
log_retention = "7 days"
```
- **`log_level`**: 默认的日志级别，可取值包括"TRACE","DEBUG","INFO", "SUCCESS","WARNING","ERROR","CRITICAL"。全局日志组件的级别和该值相同。创建定制日志组件的时候如果不额外指定级别，则也默认使用该级别。
- **`log_path`**: 日志存储路径，如果该值为空，则会创建一个{workdir}/../../logs文件夹作为日志存储路径。
- **`log_rotation`**: 该参数接受一个时间长度(e.g., "1 week")或一个文件大小 (e.g., "100 MB")，用于表示日志文件滚动的条件。
- **`log_retention`**: 该参数接受一个时间长度(e.g., "7 days")用于表示旧日志文件的保留时间，过期日志文件将会被删除。

### 默认配置
未在日志配置文件中指定的配置项采取以下默认配置：
- **`log_level`**: "INFO"
- **`log_rotation`**: "10MB"
- **`log_retention`**: "3 days"

在日志存储路径下会有两个默认日志文件`au_all.log`和`au_error.log`。其中all会记录所有高于日志配置中默认日志级别的日志，而error文件仅记录ERROR级别以上的日志。

日志组件的输出格式为：
```python
log_format: str = ("<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> "
                       "| <level>{level: <8}</level> "
                       "| {extra[context_prefix]} "
                       "| <cyan>{name}</cyan>"
                       ":<cyan>{function}</cyan>"
                       ":<cyan>{line}</cyan> "
                       "| <level>{message}</level>")
```
其中`{extra[context_prefix]}`默认为`default`, 当框架上下文中存在`LOG_CONTEXT`时，则会内容替换为`LOG_CONTEXT`的内容。关于更多框架上下文相关的内容，请参考[框架上下文](../其他/框架上下文.md)。

## 全局日志组件
agentUniverse提供一个可直接使用的日志组件`logging_util.Logger`,您可以在项目中通过如下方式引入该组件：
```python
from agentuniverse.base.util.logging.logging_util import LOGGER
```
您可以用通过该对象的不同成员函数记录不同等级的日志：
```python
from agentuniverse.base.util.logging.logging_util import LOGGER

LOGGER.info("This is an info log.")
LOGGER.debug("This is a debug log.")
LOGGER.warn("This is a warn log.")
LOGGER.error("This is an error log.")
```

## 定制日志组件
如果您想将某些日志单独输出保存，您可以使用`get_module_logger`函数创建一个自定义的日志组件:
```python
from agentuniverse.base.util.logging.logging_util import get_module_logger
new_logger = get_module_logger("new_module")
```
由这个新组件记录的日志会被保存在日志存储路径下名为`au_{module_name}.log`的日志文件中，其中`{module_name}`是您使用`get_module_logger`时传入的模块名称，如上述例子中对应的文件为`au_new_module.log`。

## 外部日志服务对接

关于外部日志服务对接相关的内容您可以参考[拓展日志组件](阿里云SLS.md)。