# tracer

**Repository Path**: chenyaopeng/tracer

## Basic Information

- **Project Name**: tracer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-30
- **Last Updated**: 2025-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tracer - 轻量级性能跟踪库

[![English](https://img.shields.io/badge/language-English-blue.svg)](README.md)
[![中文](https://img.shields.io/badge/language-中文-red.svg)](README_zh.md)

Tracer 是一个头文件级的轻量级性能跟踪库，用于记录和分析 C++ 程序的执行性能。它可以帮助开发者识别性能瓶颈、分析函数执行时间，并以兼容 Chrome Tracing 格式输出结果，便于可视化分析。

## 特性

- **易于集成**：仅需包含单个头文件
- **低开销**：设计为最小化对被分析程序的影响
- **可视化友好**：生成 Chrome Tracing 兼容的 JSON 格式输出
- **线程安全**：支持多线程应用程序分析
- **自动管理**：使用 RAII 风格的 C++ 对象自动管理作用域跟踪
- **可选编译**：可通过宏定义在编译时完全禁用

## 快速开始

1. 将 `tracer.h` 文件复制到您的项目中
2. 在需要跟踪的源文件中包含头文件：
   ```cpp
   #include "tracer/tracer.h"
   ```
3. 使用提供的宏跟踪代码执行：

   ```cpp
   void some_function() {
     TRACE_SCOPE("some_function");  // 自动跟踪函数作用域

     // 函数执行代码...

     TRACE_INSTANT("interesting_point");  // 记录即时事件

     // 更多代码...
   }
   ```

4. 程序结束时保存跟踪结果：
   ```cpp
   TRACE_SAVE("trace_result.json");
   ```
5. 在 Chrome 浏览器中查看结果：
   - 打开 Chrome
   - 访问 `chrome://tracing`
   - 点击 "Load" 按钮加载生成的 JSON 文件

## API 文档

### 宏定义

- `TRACE_SCOPE(name)`：创建一个作用域事件，自动记录进入和退出时间
- `TRACE_INSTANT(name)`：记录一个即时事件
- `TRACE_DATA(p_str)`：获取已收集的跟踪数据并保存到指定字符串指针
- `TRACE_SAVE(filename)`：将跟踪数据保存到文件

### 禁用跟踪

定义 `TRACE_DISABLED` 宏可以在编译时禁用所有跟踪代码：

```cpp
#define TRACE_DISABLED
#include "tracer/tracer.h"
```

或在编译命令中添加：

```bash
g++ -DTRACE_DISABLED ...
```

## 示例

查看 `example` 目录中的示例程序，了解如何在实际项目中使用 Tracer：

```bash
cd example
make
./tracer_example
```

示例程序生成的 `trace_result.json` 文件可以直接在 Chrome 的 tracing 页面中打开查看。

## 性能考虑

- Tracer 使用环形缓冲区存储事件，默认容量为 10,000 个事件
- 达到容量上限后，新事件会覆盖最旧的事件
- 每个事件包含名称、时间戳、持续时间、线程 ID、进程 ID 和 CPU 使用信息
- 通过线程本地存储实现高效的多线程支持

## 许可

本项目采用 MIT 许可证发布，详情请查看 LICENSE 文件。

## 贡献

欢迎通过 Issue 和 Pull Request 提供反馈和改进。