# MicroLog

**Repository Path**: MagicBude/micro-log

## Basic Information

- **Project Name**: MicroLog
- **Description**: MicroLog - 轻量级嵌入式日志系统
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-17
- **Last Updated**: 2025-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MicroLog - 轻量级嵌入式日志系统

> **版本：** v1.1.0  
> **日期：** 2025-10-18  
> **作者：** MagicBude  
> **许可：** MIT License

---

## 📖 简介

**MicroLog** 是一个专为嵌入式系统设计的轻量级日志库，具有以下特点：

- ✅ **轻量高效** - ROM占用小（< 10KB），RAM占用低（< 1KB）
- ✅ **功能完整** - 7级日志、模块过滤、格式定制、HEX转储
- ✅ **易于移植** - 清晰的移植层接口，支持裸机/FreeRTOS/RT-Thread
- ✅ **配置灵活** - 编译期/运行时双重配置，按需裁剪
- ✅ **零依赖** - 仅依赖标准C库，无第三方依赖
- ✅ **工业级** - 完善的断言、参数检查，代码规范

---

## 🚀 快速开始

### 1. 最简示例

```c
#include "log.h"

int main(void)
{
    /* 初始化日志系统 */
    log_init();
    
    /* 输出日志 */
    LOG_I(TAG_SYSTEM, "System started!");
    LOG_E(TAG_SYSTEM, "Error code: %d", 404);
    
    while(1);
}
```

**输出：**
```
============================================================
              MicroLog - 轻量级日志系统              
============================================================
设备型号: STM32F4xx
日志版本: v1.1.0
编译时间: Oct 18 2025 13:00:00
运行环境: 裸机
============================================================

[INFO ] [00:00:01] [SYS     ] System started!
[ERROR] [00:00:01] [SYS     ] Error code: 404
```

### 2. 文件级标签（推荐）

每个源文件可以定义自己的标签，使用更简洁的小写宏：

```c
/* motor.c */
#define LOG_TAG  "MOTOR"    /* 定义本文件标签 */
#include "log.h"

void motor_init(void)
{
    log_i("电机初始化");              // [MOTOR   ] 电机初始化
    log_d("PWM频率：%d Hz", 1000);    // [MOTOR   ] PWM频率：1000 Hz
    log_e("错误码：%d", -1);          // [MOTOR   ] 错误码：-1
}
```

**三种使用方式：**
```c
/* 方式1：文件级标签（最简洁）*/
#define LOG_TAG  "MOTOR"
#include "log.h"
log_i("message");              // [MOTOR   ] message

/* 方式2：显式标签（灵活）*/
LOG_I(TAG_SYSTEM, "message");  // [SYS     ] message

/* 方式3：不定义标签（警示）*/
log_i("message");              // [NO_TAG  ] message  ← 提示未定义
```

---

## ✨ 核心功能

### 1. 七级日志

| 级别 | 宏 | 用途 |
|------|---|------|
| **FATAL** | `LOG_F()` | 致命错误（系统崩溃）|
| **ERROR** | `LOG_E()` | 错误（功能失败）|
| **WARN** | `LOG_W()` | 警告（潜在问题）|
| **INFO** | `LOG_I()` | 信息（关键流程）|
| **DEBUG** | `LOG_D()` | 调试（详细信息）|
| **TRACE** | `LOG_T()` | 追踪（最详细）|
| **OFF** | - | 关闭日志 |

**示例：**
```c
LOG_F(TAG_SYSTEM, "Fatal: %s", "System crash!");
LOG_E(TAG_ADC, "ADC read failed: %d", error_code);
LOG_W(TAG_TEMP, "Temperature high: %d°C", temp);
LOG_I(TAG_APP, "Application started");
LOG_D(TAG_PARAM, "Config loaded: %d bytes", size);
LOG_T(TAG_FLOW, "Flow rate: %.2f L/min", rate);
```

---

### 2. 模块标签过滤

**预定义标签：**
```c
TAG_SYSTEM      // 系统
TAG_PARAM       // 参数管理
TAG_ADC         // ADC
TAG_LCD         // 液晶屏
TAG_KEY         // 按键
TAG_APP         // 应用层
// ... 更多标签
```

**全局级别控制：**
```c
log_set_global_level(LOG_LEVEL_WARN);  // 只显示WARN及以上
```

**模块独立控制：**
```c
log_set_tag_level(TAG_ADC, LOG_LEVEL_DEBUG);    // ADC模块显示DEBUG
log_set_tag_level(TAG_LCD, LOG_LEVEL_ERROR);    // LCD模块只显示ERROR
```

**优先级规则：** 模块级别 > 全局级别

---

### 3. 灵活的格式配置

**预定义格式：**
```c
LOG_FMT_ALL     // 所有字段（时间+级别+标签+任务+函数+行号）
LOG_FMT_SIMPLE  // 简洁模式（级别+标签）
LOG_FMT_MINIMAL // 最简模式（只有级别）
```

**自定义格式：**
```c
// ERROR级别：显示时间+级别+标签
log_set_fmt(LOG_LEVEL_ERROR, LOG_FMT_TIME | LOG_FMT_LVL | LOG_FMT_TAG);

// DEBUG级别：显示所有字段
log_set_fmt(LOG_LEVEL_DEBUG, LOG_FMT_ALL);
```

**输出示例：**
```
// 完整格式
[ERROR] [00:00:05] [ADC     ] main() :123 Read failed

// 简洁格式
[ERROR] [ADC     ] Read failed

// 最简格式
[ERROR] Read failed
```

---

### 4. HEX数据转储

**功能：** 以十六进制格式输出二进制数据

**示例：**
```c
uint8_t buffer[] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
LOG_HEX_I(TAG_SYSTEM, buffer, sizeof(buffer));
```

**输出：**
```
HEX Dump (8 bytes):
0000: 01 02 03 04 05 06 07 08  ........
```

---

### 5. 编译期优化

**编译期级别裁剪：**
```c
// log_cfg.h
#define LOG_COMPILE_LEVEL   LOG_LEVEL_INFO  // 只编译INFO及以上
```

**效果：**
- ✅ DEBUG/TRACE 宏在Release版本中**完全不编译**
- ✅ 节省ROM空间
- ✅ 零性能开销

---

## 📁 文件结构

```
Utils/log/
  ├── log.h          - 核心接口（用户包含此文件）
  ├── log.c          - 核心实现
  ├── log_cfg.h      - 配置文件（用户修改配置）
  ├── log_port.h     - 移植层接口
  ├── log_port.c     - 移植层实现（用户适配平台）
  ├── README.md      - 本文件
  ├── INTEGRATION.md - 集成指南
  └── example.c      - 示例代码
```

---

## 🔧 配置说明

### 常用配置项（log_cfg.h）

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `LOG_COMPILE_LEVEL` | 编译期级别 | Debug: TRACE, Release: INFO |
| `LOG_ENABLE_TIMESTAMP` | 时间戳功能 | 1（启用）|
| `LOG_ENABLE_FUNC` | 函数名输出 | 1（启用）|
| `LOG_ENABLE_LINE` | 行号输出 | 1（启用）|
| `LOG_ENABLE_TASK` | 任务信息（FreeRTOS）| 0（禁用）|
| `LOG_ENABLE_ASSERT` | 断言功能 | Debug启用 |
| `LOG_ENABLE_OUTPUT_LOCK` | 输出锁（多线程）| FreeRTOS自动启用 |
| `LOG_MAX_LINE_LENGTH` | 单行最大长度 | 256字节 |
| `LOG_MAX_TAG_FILTERS` | 标签过滤器数量 | 8个 |

---

## 🌟 特色功能

### 1. 智能级别过滤

**场景：** 全局只看ERROR，但想看某个模块的DEBUG

```c
log_set_global_level(LOG_LEVEL_ERROR);        // 全局ERROR
log_set_tag_level(TAG_ADC, LOG_LEVEL_DEBUG);  // ADC模块DEBUG

LOG_E(TAG_SYSTEM, "System error");   // ✅ 显示
LOG_I(TAG_SYSTEM, "System info");    // ❌ 不显示（被全局过滤）
LOG_D(TAG_ADC, "ADC value: %d", 123);// ✅ 显示（模块优先）
```

---

### 2. 原始输出

**功能：** 不带格式的纯文本输出

```c
LOG_RAW("========== Test Start ==========\n");
LOG_I(TAG_APP, "Running test...");
LOG_RAW("========== Test End ==========\n");
```

**输出：**
```
========== Test Start ==========
[INFO ] [00:00:10] [APP     ] Running test...
========== Test End ==========
```

---

### 3. 自定义输出函数

**默认：** 使用 `printf` 输出到串口

**自定义：** 输出到文件/网络/LCD等

```c
void my_log_output(const char *str)
{
    // 输出到文件
    fwrite(str, 1, strlen(str), log_file);
    
    // 或输出到LCD
    LCD_DisplayString(str);
}

int main(void)
{
    log_init();
    log_set_output(my_log_output);  // 设置自定义输出
    
    LOG_I(TAG_APP, "This goes to file/LCD");
}
```

---

### 4. 动态控制

```c
// 运行时开关日志
log_set_output_enabled(false);  // 关闭
LOG_I(TAG_APP, "This won't print");
log_set_output_enabled(true);   // 开启
LOG_I(TAG_APP, "This will print");

// 清除标签过滤
log_clear_tag_level(TAG_ADC);        // 清除单个
log_clear_all_tag_levels();          // 清除所有
```

---

## 📊 性能指标

### ROM占用（Keil MDK-ARM, -O2优化）

| 配置 | 大小 |
|------|------|
| 最小配置（无时间戳/函数名/行号）| ~6KB |
| 标准配置（带时间戳+函数名+行号）| ~8KB |
| 完整配置（所有功能）| ~10KB |

### RAM占用

| 项目 | 大小 |
|------|------|
| 单行缓冲区（可配置）| 256 字节 |
| 标签过滤器（8个）| 160 字节 |
| 全局变量 | ~50 字节 |
| **总计** | **< 500 字节** |

### 性能

- **单条日志耗时：** ~100μs（STM32F4@168MHz）
- **带格式化：** ~200μs
- **HEX转储：** ~2ms（32字节）

---

## 🎯 适用场景

✅ **适合：**
- 嵌入式系统（STM32/GD32/ESP32等）
- 裸机环境
- FreeRTOS/RT-Thread
- 资源受限设备（RAM < 10KB）
- 需要详细调试信息的项目

❌ **不适合：**
- 需要异步/缓冲输出（可扩展）
- 需要文件日志（可扩展）
- PC端应用（有更好选择）

---

## 🔗 相关链接

- **集成指南：** [INTEGRATION.md](INTEGRATION.md)
- **示例代码：** [example.c](example.c)

---

## 📝 更新日志

### v1.1.0 (2025-10-18)

**架构优化**
- 采用全局缓冲区替代栈上缓冲区，避免栈溢出
- 统一输出接口使用带长度参数(`printf("%.*s")`)，更安全可靠
- 优化变量声明位置，在使用时才声明，遵循C99最佳实践

### v1.0.0 (2025-10-17)

- 初始版本发布
- 7级日志系统（FATAL/ERROR/WARN/INFO/DEBUG/TRACE）
- 模块标签过滤、格式定制、HEX转储
- 支持裸机/FreeRTOS/RT-Thread

---

## 📄 许可证

MIT License - 自由使用、修改、商用

---

## 🤝 贡献

欢迎提交Issue和PR！

---

## 📮 联系方式

- **作者：** MagicBude
- **项目：** MicroLog v1.1.0
- **日期：** 2025-10-18

---

**感谢使用 MicroLog！** 🎉