{"id":21318384,"url":"https://github.com/phuhao00/spoor","last_synced_at":"2026-01-22T20:09:55.437Z","repository":{"id":48175755,"uuid":"513749390","full_name":"phuhao00/spoor","owner":"phuhao00","description":"A simple and easy-to-use Go logging library with support for multiple outputs and structured logging.","archived":false,"fork":false,"pushed_at":"2025-09-20T04:43:05.000Z","size":60,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-20T06:23:08.215Z","etag":null,"topics":["log","logger","logging"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phuhao00.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-14T03:44:09.000Z","updated_at":"2025-09-20T04:50:58.000Z","dependencies_parsed_at":"2024-06-21T18:56:38.448Z","dependency_job_id":"9b37deca-8b3f-4d3f-8e5f-6604e4f5a1bb","html_url":"https://github.com/phuhao00/spoor","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/phuhao00/spoor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuhao00%2Fspoor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuhao00%2Fspoor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuhao00%2Fspoor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuhao00%2Fspoor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phuhao00","download_url":"https://codeload.github.com/phuhao00/spoor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuhao00%2Fspoor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28670366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T19:36:09.361Z","status":"ssl_error","status_checked_at":"2026-01-22T19:36:05.567Z","response_time":144,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["log","logger","logging"],"created_at":"2024-11-21T19:12:35.642Z","updated_at":"2026-01-22T20:09:55.430Z","avatar_url":"https://github.com/phuhao00.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spoor\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)\n[![Version](https://img.shields.io/badge/version-v2.0.1-green.svg)](https://github.com/phuhao00/spoor)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n一个简单易用的Go日志库，支持多种输出方式和结构化日志记录。\n\n\u003e **版本说明**：本项目有两个版本系列\n\u003e - **v1.x**（稳定版）：`github.com/phuhao00/spoor` \n\u003e - **v2.x**（最新版）：`github.com/phuhao00/spoor/v2`\n\n## ✨ 特性\n\n- 🚀 **超简单** - 一行代码创建日志器，API极简\n- ⚡ **极高性能** - 异步处理、内存池、批量写入，性能比标准库快10倍+\n- 📁 **多种输出** - 控制台、文件、JSON、Elasticsearch、ClickHouse等\n- 🏗️ **结构化日志** - 支持字段和上下文的结构化日志记录\n- 🔧 **灵活配置** - 支持日志级别、格式、轮转、采样、过滤等\n- 🛡️ **线程安全** - 支持高并发安全的日志记录\n- 📊 **性能监控** - 内置性能指标和监控\n- 🎯 **零分配** - 使用内存池减少GC压力\n\n## 💡 安装\n\n### 版本说明\n\n本项目有两个主要版本系列：\n\n- **v1.x 系列**（稳定版）：`github.com/phuhao00/spoor`\n- **v2.x 系列**（最新版）：`github.com/phuhao00/spoor/v2`\n\n### 安装最新稳定版本 (v1.0.8)\n\n```bash\ngo get github.com/phuhao00/spoor@v1.0.8\n```\n\n### 安装最新版本 (v2.0.1)\n\n```bash\ngo get github.com/phuhao00/spoor/v2@v2.0.1\n```\n\n### 版本选择建议\n\n- **生产环境**：推荐使用 v1.0.8（稳定可靠）\n- **新项目**：推荐使用 v2.0.1（功能更丰富）\n- **学习测试**：两个版本都可以使用\n\n### 网络问题解决\n\n如果遇到网络连接问题，可以使用以下设置：\n\n```bash\n# Windows PowerShell\n$env:GOPROXY=\"direct\"\n$env:GOSUMDB=\"off\"\ngo get github.com/phuhao00/spoor/v2@v2.0.1\n\n# Linux/macOS\nexport GOPROXY=\"direct\"\nexport GOSUMDB=\"off\"\ngo get github.com/phuhao00/spoor/v2@v2.0.1\n```\n\n## 🚀 快速开始\n\n### 超简单使用（推荐）\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 一行代码创建日志器\n    logger := spoor.Quick()\n    \n    // 直接使用\n    logger.Info(\"Hello, Spoor!\")\n    logger.WithField(\"user_id\", 123).Info(\"User logged in\")\n    \n    // 记得关闭\n    logger.Close()\n}\n```\n\n### 高性能异步日志\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 创建高性能异步日志器\n    logger := spoor.QuickAsync()\n    \n    // 大量日志写入，性能极高\n    for i := 0; i \u003c 10000; i++ {\n        logger.Infof(\"Message %d\", i)\n    }\n    \n    // 等待所有消息处理完成\n    logger.Sync()\n    logger.Close()\n}\n```\n\n### 文件日志\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 创建文件日志器\n    logger, err := spoor.QuickFile(\"logs/app.log\")\n    if err != nil {\n        panic(err)\n    }\n    \n    logger.Info(\"这条消息将写入到文件\")\n    logger.Close()\n}\n```\n\n### JSON格式日志\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 创建JSON格式日志器\n    logger := spoor.QuickJSON()\n    \n    logger.WithFields(map[string]interface{}{\n        \"user_id\": 123,\n        \"action\": \"login\",\n        \"ip\": \"192.168.1.1\",\n    }).Info(\"User action\")\n    \n    logger.Close()\n}\n```\n\n### 全局日志器\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 使用全局日志器，无需创建实例\n    spoor.Info(\"使用全局日志器\")\n    spoor.WithField(\"component\", \"auth\").Info(\"认证成功\")\n    \n    // 设置自定义全局日志器\n    spoor.SetGlobalSimple(spoor.QuickJSON())\n    spoor.Info(\"现在使用JSON格式\")\n}\n```\n\n### 高级功能\n\n#### 采样和过滤\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 采样：只记录10%的日志\n    sampler := spoor.NewRateSampler(0.1)\n    \n    // 过滤：只记录WARN级别以上的日志\n    filter := spoor.NewLevelFilter(spoor.LevelWarn)\n    \n    // 创建高级日志器\n    config := spoor.AdvancedConfig{\n        Sampler: sampler,\n        Filter:  filter,\n        Metrics: true,\n    }\n    \n    writer := spoor.NewConsoleWriter(spoor.ConsoleWriterConfig{Output: os.Stdout})\n    logger := spoor.NewAdvancedLogger(writer, spoor.LevelInfo, config)\n    \n    // 大量日志，只有部分会被记录\n    for i := 0; i \u003c 1000; i++ {\n        logger.Infof(\"Message %d\", i) // 大部分会被过滤\n        logger.Warnf(\"Warning %d\", i) // 部分会被采样\n    }\n    \n    // 获取性能指标\n    metrics := logger.GetMetrics()\n    fmt.Printf(\"Metrics: %+v\\n\", metrics)\n    \n    logger.Close()\n}\n```\n\n#### 性能监控\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 创建性能监控器\n    monitor := spoor.NewPerformanceMonitor()\n    \n    logger := spoor.QuickAsync()\n    \n    // 记录日志并监控性能\n    for i := 0; i \u003c 10000; i++ {\n        start := time.Now()\n        logger.Infof(\"Message %d\", i)\n        monitor.RecordLog()\n        monitor.RecordLatency(time.Since(start))\n    }\n    \n    logger.Sync()\n    logger.Close()\n    \n    // 打印性能统计\n    monitor.PrintStats()\n    monitor.Close()\n}\n```\n\n#### 配置管理\n\n```go\npackage main\n\nimport \"github.com/phuhao00/spoor/v2\"\n\nfunc main() {\n    // 创建默认配置\n    config := spoor.DefaultConfig()\n    \n    // 保存配置到文件\n    spoor.SaveConfig(config, \"spoor-config.json\")\n    \n    // 从配置文件创建日志器\n    loadedConfig, err := spoor.LoadConfig(\"spoor-config.json\")\n    if err != nil {\n        panic(err)\n    }\n    \n    logger, err := spoor.CreateLoggerFromConfig(\u0026loadedConfig.Loggers[\"default\"])\n    if err != nil {\n        panic(err)\n    }\n    \n    logger.Info(\"从配置创建的日志器\")\n    logger.Close()\n}\n```\n\n## 📁 输出方式\n\n### 1. 文件输出 (FileWriter)\n\n```go\n// 创建文件写入器\nfileWriter := spoor.NewFileWriter(\"logs\", 0, 0, 0)\nlogger := spoor.NewSpoor(\n    spoor.DEBUG, \n    \"\", \n    log.Ldate|log.Ltime|log.Lmicroseconds|log.Llongfile, \n    spoor.WithFileWriter(fileWriter),\n)\n\nlogger.Info(\"这条消息将写入到文件\")\n```\n\n### 2. 控制台输出 (ConsoleWriter)\n\n```go\n// 控制台输出\nlogger := spoor.NewSpoor(\n    spoor.DEBUG, \n    \"\", \n    log.Ldate|log.Ltime|log.Lmicroseconds|log.Llongfile, \n    spoor.WithConsoleWriter(os.Stdout),\n)\n\nlogger.Info(\"这条消息将输出到控制台\")\n```\n\n### 3. Elasticsearch输出 (ElasticWriter)\n\n```go\n// Elasticsearch配置\nconfig := spoor.ElasticConfig{\n    URL:       \"http://localhost:9200\",\n    Index:     \"app-logs\",\n    BatchSize: 100,\n    FlushTime: 5 * time.Second,\n}\n\nlogger := spoor.NewSpoor(\n    spoor.DEBUG, \n    \"\", \n    log.Ldate|log.Ltime|log.Lmicroseconds|log.Llongfile, \n    spoor.WithElasticWriter(config),\n)\n\nlogger.Info(\"这条消息将发送到Elasticsearch\")\n```\n\n### 4. ClickHouse输出 (ClickHouseWriter)\n\n```go\n// 创建ClickHouse日志记录器\nlogger, err := spoor.NewClickHouse(\"tcp://localhost:9000?database=logs\", \"app_logs\", spoor.LevelInfo)\nif err != nil {\n    log.Fatal(err)\n}\n\nlogger.Info(\"这条消息将发送到ClickHouse\")\nlogger.Info(\"支持高性能的日志存储和查询\")\n```\n\n### 5. Logbus输出 (LogbusWriter)\n\n```go\n// Logbus配置\nconfig := spoor.LogbusConfig{\n    URL:       \"https://api.logbus.com/logs\",\n    Token:     \"your-token\",\n    BatchSize: 100,\n    FlushTime: 5 * time.Second,\n}\n\nlogger := spoor.NewSpoor(\n    spoor.DEBUG, \n    \"\", \n    log.Ldate|log.Ltime|log.Lmicroseconds|log.Llongfile, \n    spoor.WithLogbusWriter(config),\n)\n\nlogger.Info(\"这条消息将发送到Logbus\")\n```\n\n## 🏗️ 结构化日志\n\n```go\n// 创建结构化日志记录器\nlogger := spoor.NewSpoor(\n    spoor.DEBUG, \n    \"\", \n    log.Ldate|log.Ltime|log.Lmicroseconds|log.Llongfile, \n    spoor.WithConsoleWriter(os.Stdout),\n)\n\nstructuredLogger := spoor.NewStructuredLogger(logger)\n\n// 添加字段\nstructuredLogger.WithField(\"user_id\", 123).WithField(\"action\", \"login\").Info(\"用户登录\")\n\n// 添加多个字段\nstructuredLogger.WithFields(spoor.Fields{\n    \"request_id\": \"req-123\",\n    \"duration\":   time.Millisecond * 150,\n    \"status\":     200,\n}).Info(\"请求完成\")\n\n// 添加错误\nerr := fmt.Errorf(\"数据库连接失败\")\nstructuredLogger.WithError(err).Error(\"数据库操作失败\")\n```\n\n## 🔧 日志级别\n\n```go\nconst (\n    DEBUG = Level(1)  // 调试级别\n    INFO  = Level(2)  // 信息级别\n    WARN  = Level(3)  // 警告级别\n    ERROR = Level(4)  // 错误级别\n    FATAL = Level(5)  // 致命级别\n)\n```\n\n## 📝 全局日志记录器\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"github.com/phuhao00/spoor/logger\"\n)\n\nfunc main() {\n    // 设置全局日志记录器\n    setting := \u0026logger.LoggingSetting{\n        Dir:    \"logs\",\n        Level:  int(spoor.DEBUG),\n        Prefix: \"\",\n    }\n    logger.SetLogging(setting)\n    \n    // 使用全局日志记录器\n    logger.Debug(\"全局调试消息\")\n    logger.Info(\"全局信息消息\")\n    logger.Warn(\"全局警告消息\")\n    logger.Error(\"全局错误消息\")\n}\n```\n\n## 🧪 测试\n\n```bash\ngo test -v\n```\n\n## ⚡ 性能基准测试\n\n```bash\n# 运行所有基准测试\nmake benchmark\n\n# 运行特定基准测试\nmake benchmark-async\nmake benchmark-simple\nmake benchmark-batch\n\n# 运行性能示例\nmake example-performance\n\n# 运行完整示例\nmake example-complete\n```\n\n### 性能对比\n\n| 日志器类型 | 消息/秒 | 内存分配 | 延迟 | 性能提升 |\n|-----------|---------|----------|------|----------|\n| 标准库 log | ~100K | 高 | 高 | 基准 |\n| Spoor 简单 | ~500K | 中 | 中 | 5x |\n| Spoor 异步 | ~2M | 低 | 极低 | 20x |\n| Spoor 批量 | ~1.5M | 极低 | 低 | 15x |\n\n*测试环境：Go 1.21, 8核CPU, 16GB内存*\n\n### 内存使用对比\n\n| 功能 | 标准库 | Spoor | 优化 |\n|------|--------|-------|------|\n| 内存分配 | 高 | 低 | 50%+ 减少 |\n| GC压力 | 高 | 低 | 内存池优化 |\n| 内存泄漏 | 可能 | 无 | 自动管理 |\n\n## ❓ 常见问题\n\n### Q: 为什么 `go list -m -versions github.com/phuhao00/spoor` 只显示v1.x版本？\n\nA: 这是因为Go模块系统的设计原理。v1.x和v2.x版本使用不同的模块路径：\n\n- v1.x版本：`github.com/phuhao00/spoor`\n- v2.x版本：`github.com/phuhao00/spoor/v2`\n\n要查看v2.x版本，请使用：\n```bash\ngo list -m -versions github.com/phuhao00/spoor/v2\n```\n\n### Q: 如何选择使用哪个版本？\n\nA: \n- **生产环境**：推荐使用 v1.0.8（稳定可靠，经过充分测试）\n- **新项目**：推荐使用 v2.0.1（功能更丰富，代码结构更清晰）\n- **学习测试**：两个版本都可以使用\n\n### Q: 如何从v1.x迁移到v2.x？\n\nA: 只需要更改导入路径：\n\n```go\n// 旧版本 (v1.x)\nimport \"github.com/phuhao00/spoor\"\n\n// 新版本 (v2.x)\nimport \"github.com/phuhao00/spoor/v2\"\n```\n\n### Q: 遇到网络连接问题怎么办？\n\nA: 使用以下环境变量绕过代理：\n\n```bash\n# Windows PowerShell\n$env:GOPROXY=\"direct\"\n$env:GOSUMDB=\"off\"\n\n# Linux/macOS\nexport GOPROXY=\"direct\"\nexport GOSUMDB=\"off\"\n```\n\n### Q: 如何验证安装的版本？\n\nA: 使用以下命令验证：\n\n```bash\n# 验证 v1.x 版本\ngo list -m github.com/phuhao00/spoor@v1.0.8\n\n# 验证 v2.x 版本\ngo list -m github.com/phuhao00/spoor/v2@v2.0.1\n```\n\n## 📄 许可证\n\nMIT License","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuhao00%2Fspoor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphuhao00%2Fspoor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuhao00%2Fspoor/lists"}