← Back to Blog
EN中文

工业级黑盒记录：基于共享内存的跨进程日志设计

在构建高频交易系统、自动驾驶控制回路或实时搜索后端时，传统的日志方案往往面临一个两难困境：详细记录会拖慢关键路径（Critical Path），而异步记录在进程崩溃（Crash）时容易丢失最后几毫秒的关键数据——也就是所谓的“案发现场”。

本文探讨一种“黑盒”式的日志设计模式：利用 内存映射文件（Memory-Mapped Files, mmap） 构建跨进程的环形缓冲区。这种设计既保证了极低的写入延迟，又能像飞机黑匣子一样，在进程异常退出后依然保留完整现场。

我们将使用现代 C++ (C++20) 来演示这一核心机制。

为什么是 mmap？

标准的文件 I/O (std::ofstream, fwrite) 甚至异步日志库（如 spdlog 的异步模式）通常涉及用户态到内核态的拷贝，或者依赖内存队列。如果进程遭遇 SIGSEGV 或 SIGKILL，内存队列中的数据瞬间蒸发。

mmap 的优势在于：

  1. 零拷贝写入：写入操作本质上是内存 memcpy，由操作系统负责脏页回写。
  2. 崩溃幸存：只要操作系统内核不挂，即使进程崩溃，已写入映射区域的数据依然存在于文件系统中。
  3. 跨进程观测：由于映射的是文件，外部监控进程可以实时挂载同一个文件，像读取内存一样“偷窥”运行状态，完全不干扰主进程。

核心架构：基于 mmap 的环形缓冲区

我们需要设计一个定长的头部（Header）用于同步读写位置，加上一个定长的环形数据区（Ring Buffer）。

1. 内存布局设计

// layout.h
#include <cstdint>
#include <atomic>

struct LogHeader {
    static constexpr uint64_t MAGIC = 0xBADB0X01;
    uint64_t magic;
    uint32_t version;
    std::atomic<uint32_t> write_offset; // 原子操作，确保多进程安全
    std::atomic<uint32_t> wrap_count;   // 圈数，用于区分新旧数据
    uint64_t capacity;
};

// 数据紧跟在 Header 之后

2. 写入器实现 (C++20)

利用 std::span 和 std::filesystem 简化资源管理。

// blackbox_logger.h
#include <fcntl.h>
#include <sys/mman.h>
#include <unistd.h>
#include <filesystem>
#include <iostream>
#include <span>
#include <cstring>
#include "layout.h"

namespace fs = std::filesystem;

class BlackBoxLogger {
public:
    BlackBoxLogger(const fs::path& path, size_t size_mb) {
        size_t total_size = sizeof(LogHeader) + (size_mb * 1024 * 1024);
        
        int fd = open(path.c_str(), O_RDWR | O_CREAT, 0644);
        if (fd == -1) throw std::runtime_error("Failed to open file");
        
        // 预分配文件空间
        if (ftruncate(fd, total_size) == -1) {
            close(fd);
            throw std::runtime_error("Failed to resize file");
        }

        void* map_ptr = mmap(nullptr, total_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
        close(fd); // mmap 建立后可关闭 fd

        if (map_ptr == MAP_FAILED) throw std::runtime_error("mmap failed");

        _base_ptr = static_cast<uint8_t*>(map_ptr);
        _header = reinterpret_cast<LogHeader*>(_base_ptr);
        _payload = std::span<uint8_t>(_base_ptr + sizeof(LogHeader), total_size - sizeof(LogHeader));

        // 初始化 Header (如果是新文件)
        if (_header->magic != LogHeader::MAGIC) {
            _header->magic = LogHeader::MAGIC;
            _header->capacity = _payload.size();
            _header->write_offset = 0;
            _header->wrap_count = 0;
        }
    }

    ~BlackBoxLogger() {
        // 在析构时不 munmap 也可以，OS 会清理，但为了规范：
        munmap(_base_ptr, sizeof(LogHeader) + _payload.size());
    }

    void log(std::string_view msg) {
        // 简单的长度前缀协议: [len:2][msg:n]
        uint16_t len = static_cast<uint16_t>(msg.size());
        if (len == 0) return;

        write_raw(&len, sizeof(len));
        write_raw(msg.data(), len);
    }

private:
    void write_raw(const void* data, size_t size) {
        const uint8_t* src = static_cast<const uint8_t*>(data);
        size_t remaining = size;
        
        while (remaining > 0) {
            uint32_t current_offset = _header->write_offset.load(std::memory_order_acquire);
            size_t space_at_end = _payload.size() - current_offset;
            size_t chunk = std::min(remaining, space_at_end);

            std::memcpy(_payload.data() + current_offset, src, chunk);
            
            // 更新指针和状态
            src += chunk;
            remaining -= chunk;
            
            uint32_t next_offset = current_offset + chunk;
            if (next_offset == _payload.size()) {
                next_offset = 0;
                _header->wrap_count.fetch_add(1, std::memory_order_relaxed);
            }
            
            // 提交新的 offset，这使得 reader 可见
            _header->write_offset.store(next_offset, std::memory_order_release);
        }
    }

    uint8_t* _base_ptr;
    LogHeader* _header;
    std::span<uint8_t> _payload;
};

关键设计权衡

原子性与一致性

上面的代码使用了 std::atomic 来更新 write_offset。这是一个“最终一致性”的设计。

  • 优点：极快。没有互斥锁（Mutex），没有系统调用。
  • 缺点：在多写入者（Multi-Writer）场景下是不安全的。这种设计通常用于 单生产者-单消费者（监控） 模式。如果是多线程写入，仍需在应用层加锁，但锁的粒度仅限于 memcpy，不涉及 I/O 阻塞。

为什么不使用 msync？

许多人认为必须调用 msync 才能保证数据落盘。但在 Linux 中，msync(MS_SYNC) 会导致阻塞，违背了低延迟的初衷。我们依赖操作系统的脏页回写策略（通常是几十秒一次），或者在进程崩溃（Crash）时依赖内核的数据结构完整性。只要电源不断，OS 内核还活着，数据就在 Page Cache 中，重启后文件内容依然是最新的。

总结

这种“黑盒”日志模式非常适合记录系统的心跳、关键状态变更和崩溃前的最后时刻。它将日志系统从“文本流”转变为“内存数据库”，使得跨进程的实时监控和事后调试成为可能，且几乎不付出性能代价。