# hyperlog

**Repository Path**: tyking123/hyperlog

## Basic Information

- **Project Name**: hyperlog
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HyperLog (v1.1.1.1)

[![C++ Standard](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](https://en.cppreference.com/w/cpp/20)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg)]()

## 🚀 项目简介

HyperLog 是一个面向现代 **C++20** 标准开发的高性能、异步且安全的日志框架。它专为对日志写入延迟、存储安全性和系统可靠性有极高要求的应用场景（如高频交易、嵌入式系统、分布式后端）而设计。

HyperLog 不仅仅是一个日志库，它还提供了一整套从**高性能写入、内存映射持久化、实时压缩、端到端加密**到**离线解密分析**的完整日志生命周期解决方案。

---

## ✨ 核心特性

### 1. 极致性能与可靠性
- **Mmap 内存映射缓冲**：采用 `mmap` 技术实现磁盘文件与内存的映射。即使在进程崩溃或系统掉电的情况下，已写入缓存的日志也能最大程度地保留在磁盘上，实现日志的“准实时”持久化。
- **异步非阻塞流水线**：通过专有的 `Executor` 和 `TaskRunner` 将日志格式化与磁盘 I/O 分离。业务线程仅负责极轻量级的任务分发，日志的压缩、加密和写入完全在后台线程池异步完成。
- **双缓冲设计 (Swap Cache)**：主从缓存设计，确保在高并发写入时，后台落盘操作不会阻塞前台日志生成。

### 2. 金融级安全性
- **端到端加密**：支持基于 **ECDH (Elliptic Curve Diffie-Hellman)** 的密钥交换协议和 **AES-256 (GCM/CBC/CTR)** 对称加密。每批次日志独立加密，确保即便日志文件泄露，攻击者也无法在没有私钥的情况下读取内容。
- **零痕迹解密**：配备专门的 `Decoder` 模块，支持离线解密还原。

### 3. 高效存储
- **高性能压缩**：内置 **Zstd** (推荐) 和 **Zlib** 压缩引擎。实测在典型结构化日志场景下，压缩率可达 5x-10x，大幅降低存储开销与磁盘 I/O 压力。
- **Protobuf 序列化**：核心日志条目采用 Google Protobuf 进行二进制序列化，相比文本格式更小、解析更快。

### 4. 现代 C++ 体验
- **C++20 特性**：深度集成 `std::source_location`，自动捕获日志调用的文件名、行号及函数名，且无任何宏定义的负面影响。
- **类型安全格式化**：基于高性能 `fmt` 库，提供比 `printf` 更安全、比 `iostream` 更快速的格式化接口。

---

## 🛠️ 技术架构

```mermaid
graph LR
    App[应用程序] --> VariadicHandle[VariadicLogHandle]
    VariadicHandle --> MmapCache[Mmap 持续化缓存]
    MmapCache -- 异步调度 --> TaskRunner[TaskRunner / ThreadPool]
    TaskRunner --> ProtoBuf[Protobuf 序列化]
    ProtoBuf --> Compress[Zstd/Zlib 压缩]
    Compress --> Crypto[AES/ECDH 加密]
    Crypto --> Disk[磁盘 .log 文件]
```

---

## 📦 环境要求

- **编译器**：支持 C++20 标准（GCC 10.1+, Clang 11+, MSVC 19.28+）
- **构建系统**：CMake 3.22+
- **第三方依赖** (已内置/自动处理):
  - [fmt](https://github.com/fmtlib/fmt) - 高性能格式化
  - [Crypto++](https://github.com/weidai11/cryptopp) - 安全加密
  - [Protobuf](https://github.com/protocolbuffers/protobuf) - 数据序列化
  - [Zstd](https://github.com/facebook/zstd) / [Zlib](https://github.com/madler/zlib) - 压缩算法

---

## 🚀 快速开始

### 1. 基本使用

```cpp
#include "logger/log_factory.h"

int main() {
    auto& factory = logger::LogFactory::GetInstance();
    auto logger = factory.GetLogHandle();

    // 简单日志记录
    logger->Log(logger::LogLevel::kInfo, "Hello HyperLog! Current version: {}", "1.1.1.1");

    // 捕获源文件位置
    logger->Log(logger::LogLevel::kDebug, "This log includes file/line info automatically.");
    
    return 0;
}
```

### 2. 配置加密落盘 (EffectiveSink)

```cpp
#include "logger/sinks/effective_sinks.h"
#include "crypto/aes_crypto.h"

// 1. 生成 ECDH 密钥对 (服务端/客户端)
auto [private_key, public_key] = logger::crypto::GenerateEcdhKey();

// 2. 配置 EffectiveSink
logger::EffectiveSink::Config config;
config.directory_path = "./logs";
config.file_prefix = "secure_app";
config.public_key = public_key; // 设置加密公钥
config.interval_duration = std::chrono::minutes(1); // 周期性落盘

auto sink = std::make_shared<logger::EffectiveSink>(config);
auto logger = std::make_shared<logger::LogHandle>(sink);

logger->Log(logger::LogLevel::kCritical, "Sensitive security event detected!");
```

### 3. 日志解密还原

```cpp
#include "decode/decoder.h"

logger::Decoder::DecodeConfig decode_config;
decode_config.file_path = "./logs/secure_app_20250823.log";
decode_config.output_file_path = "./decoded.txt";
decode_config.private_key = my_private_key; // 使用匹配的私钥解密

logger::Decoder decoder(decode_config);
if (decoder.DecodeFile()) {
    printf("Logs successfully restored to decoded.txt\n");
}
```

---

## 📊 格式化占位符

| 占位符 | 说明 | 示例 |
| :--- | :--- | :--- |
| `%l` | 日志级别 | `INFO`, `ERROR` |
| `%D` | 日期时间 | `2026-03-30 14:00:00` |
| `%S` | Unix 时间戳 | `1743343200` |
| `%p` | 进程 ID | `1234` |
| `%t` | 线程 ID | `5678` |
| `%F` | 源文件名 | `main.cpp` |
| `%f` | 函数名 | `main` |
| `%#` | 行号 | `42` |
| `%v` | 日志正文 | `The actual log message` |

---

## 📁 目录结构

```text
├── decode/            # 日志解密与还原工具
├── logger/            # 核心日志库实现
│   ├── compress/      # Zstd/Zlib 压缩适配器
│   ├── context/       # 异步执行引擎与线程池
│   ├── crypto/        # AES/ECDH 加密实现
│   ├── formatter/     # 基于 fmt 的灵活格式化器
│   ├── mmap/          # 跨平台 mmap 封装
│   ├── protobuf/      # 结构化数据定义
│   └── sinks/         # 控制台、文件及加密文件输出目标
├── test/              # 单元测试模块
└── third_party/       # 外部依赖库
```

---

## 📜 许可证

本项目采用 **MIT** 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

---

## 🔗 相关资源

- **项目主页**: [https://gitee.com/tyking123/hyperlog](https://gitee.com/tyking123/hyperlog)
- **反馈与建议**: 欢迎提交 Issue 或 Pull Request 贡献代码。