debugger

package
v0.17.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 35 Imported by: 4

README

调试器组件 (Debugger Component)

概述

调试器组件是一个专为Gin框架设计的HTTP请求调试工具,用于解决Gin框架默认日志输出过多、并发请求下日志混杂的问题。该组件支持多种存储方式(文件、内存、数据库),提供完整的请求和响应信息记录、查询、搜索和详情查看功能。

功能特性

核心功能
  • ✅ 请求拦截: 自动拦截HTTP请求并记录完整的调试信息,支持请求体大小限制和二进制数据检测
  • ✅ 多存储支持: 支持内存、文件、数据库等多种存储方式,提供统一的Storage接口
  • ✅ 日志查询: 支持按时间、请求路径、状态码、记录类型、是否含错误等条件过滤,实现真正的分页查询
  • ✅ 全文搜索: 支持关键词搜索进程名称、URL、请求体、响应体、错误信息等内容
  • ✅ 详情查看: 显示完整的请求和响应信息,支持HTML和JSON格式,自动计算存储大小
  • ✅ 增强型 JSON 查看器: 详情页集成 VSCode 同款 jsonc-parser,支持 JSON 美化、层级折叠/展开、自动修复(注释/尾部逗号等)、原始/修复后切换、一键复制
  • ✅ 统计信息: 提供请求统计、错误率、响应时间、HTTP方法、状态码等分析数据
  • ✅ 流式请求支持: 自动检测和记录流式响应(SSE、分块传输等),支持分块记录、元数据统计和内存管理优化
  • ✅ 进程级调试: 支持非HTTP进程的调试记录,适用于后台任务、批处理作业等场景
  • ✅ 内置Logger: 提供多级别日志记录器,支持字段附加和日志收集
  • ✅ 主进程日志: 支持应用程序主进程日志记录,采用文件存储,支持按日期或大小分割
记录内容
  • 请求方法、URL、查询参数
  • 请求头和响应头
  • 请求体和响应体(支持JSON格式化、二进制数据检测)
  • 会话数据和错误信息
  • 客户端IP、User Agent、请求ID
  • 请求处理时间和状态码
  • 流式响应元数据(分块数量、分块大小、流式状态、最大分块限制等)
  • 进程记录信息(进程ID、进程名称、进程类型、开始时间、结束时间、状态)
  • Logger日志信息(时间戳、级别、消息、附加字段、位置信息)
  • 存储大小信息(自动计算和格式化显示)

反向代理 / 二级目录部署

调试器前端页面(日志列表、详情)默认基于后端内部 basePath(如 /jcbase/debug)拼装链接。 当服务经反向代理部署在二级目录(如 /aaa)下时,代理会透明剥离前缀后再转发给后端, 后端只认内部路径,但浏览器中的完整路径应为 /aaa/jcbase/debug/...。 若仍使用绝对路径,浏览器跳转与静态资源(如 jsonc-parser.bundle.js)都会丢失 /aaa 前缀导致 404。

本组件采用纯前端自检测方案,无需修改反向代理配置、也无需在后端额外配置代理前缀:

  1. 自检测前缀:页面注入脚本对比 window.location.pathname(含 /aaa)与后端下发的内部 basePath, 计算出含代理前缀的外部 basePath(变量 window.__basePath);未部署在二级目录时回退为内部路径,行为不变。
  2. 注入 <base>:以 window.__basePath + "/" 设置 <base href>,使页面内所有相对链接 / 资源 (列表、详情、下载、API、静态 JS)自动基于完整 URL 解析,从而带上 /aaa。
  3. 相对化链接:模板中服务端渲染的 <a href> 与 <script src> 均使用相对路径(不再带 {{.BasePath}} 前缀)。
  4. 根路径直渲:根路由(/jcbase/debug)不再 302 重定向到 /list,而是直接渲染列表页, 绕开"服务端无法感知代理前缀、无法拼出正确 Location"的问题(前端无法干预 302)。
Nginx 部署示例(无需特殊头部)
location /aaa/ {
    proxy_pass http://127.0.0.1:8080/;   # 注意结尾的 /,用于剥离 /aaa 前缀
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

按以上配置,访问 https://your-domain/aaa/jcbase/debug/list 即可正常使用,所有跳转与静态资源均自动包含 /aaa。

快速开始

安装

确保项目已安装Gin框架:

go get -u github.com/gin-gonic/gin
基本使用
便捷构造函数(推荐)

我们提供了多种便捷构造函数,使用更加简单直观:

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	// 方式1:使用简单调试器(默认配置)
	dbg, err := debugger.NewSimpleDebugger()
	if err != nil {
		panic(err)
	}

	// 方式2:使用内存存储器(开发环境)
	dbg, err := debugger.NewWithMemoryStorage(1000)
	if err != nil {
		panic(err)
	}

	// 方式3:使用文件存储器(生产环境)
	dbg, err := debugger.NewWithFileStorage("/var/log/debug_logs", 5000)
	if err != nil {
		panic(err)
	}

	// 方式4:使用自定义存储器
	customStorage, _ := debugger.NewMemoryStorage(150)
	dbg, err := debugger.NewWithCustomStorage(customStorage)
	if err != nil {
		panic(err)
	}

	// 方式5:生产环境调试器
	dbg, err := debugger.NewProductionDebugger("/var/log/debug_logs")
	if err != nil {
		panic(err)
	}

	// 创建Gin路由
	router := gin.New()

	// 使用调试器中间件(默认顺序)
	router.Use(dbg.Middleware())

	// 或者指定中间件执行顺序
	// router.Use(dbg.MiddlewareWithOrder("early"))  // 优先执行
	// router.Use(dbg.MiddlewareWithOrder("late"))   // 最后执行
	
	// 添加业务路由
	router.GET("/api/users", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "Hello World"})
	})
	
	router.Run(":8080")
}
详细使用指南
配置选项

调试器支持丰富的配置选项,推荐使用便捷构造函数:

便捷构造函数方式(推荐)
// 方式1:使用简单调试器(默认配置)
dbg, err := debugger.NewSimpleDebugger()

// 方式2:使用内存存储器(开发环境)
dbg, err := debugger.NewWithMemoryStorage(1000)

// 方式3:使用文件存储器(生产环境)
dbg, err := debugger.NewWithFileStorage("/var/log/debug_logs", 5000)

// 方式4:使用自定义存储器
customStorage, _ := debugger.NewMemoryStorage(150)
dbg, err := debugger.NewWithCustomStorage(customStorage)

// 方式5:生产环境调试器
		dbg, err := debugger.NewProductionDebugger("/var/log/debug_logs")
		if err != nil {
			panic(err)
		}

		router.Use(dbg.Middleware())
		// 或指定中间件顺序: router.Use(dbg.MiddlewareWithOrder("early"))
手动配置方式(高级使用)
// 创建存储器实例
memoryStorage, _ := debugger.NewMemoryStorage(150)

// 创建调试器配置
autoSkipStatic := true // *bool 三态:nil(未配置)默认开启;显式 false 生效关闭
config := &debugger.Config{
	Enabled:         true,                    // 是否启用调试器
	Storage:         memoryStorage,           // 必须传入实例化的存储器
	MaxBodySize:     1024,                    // 最大请求/响应体大小(KB),默认1MB
	RetentionPeriod: 7 * 24 * time.Hour,      // 日志保留期限,默认7天
	Level:           debugger.LevelWarn,     // 日志级别:LevelInfo/LevelWarn/LevelError/LevelSilent(默认:LevelWarn)
	MaxRecords:      150,                     // 最大记录数量,默认150

	// 过滤配置
	SkipPaths:        []string{"/static", "/health"}, // 跳过的路径
	SkipMethods:      []string{"OPTIONS"},              // 跳过的HTTP方法
	AutoSkipStatic:   &autoSkipStatic,                   // 自动跳过静态资源请求(*bool:nil默认开启,显式false关闭)
	StaticExtensions: []string{".css", ".js", ".png"},   // 自定义静态资源扩展名

	// 采样配置
	SampleRate: 1.0,                            // 采样率(0-1之间),默认1.0(记录所有请求)

	// IP访问控制配置
	AllowedIPs: []string{"127.0.0.1"},          // 调试页面/API 的 IP 白名单(鉴权走 ctx.ClientIP())
	AllowEmptyWhitelist: false,                 // 白名单为空时是否仍开放页面,默认 false(fail-closed,不注册路由)

	// 凭据掩码配置(默认开启,在写入日志条目时统一替换为 ***)
	BodyMaskEnabled:         nil,                       // *bool:nil=默认开启,显式 false 关闭
	HeaderMaskKeys:          []string{"x-custom-auth"}, // 追加需掩码的请求/响应头(内置含 authorization/cookie/set-cookie 等)
	BodyMaskKeys:            []string{"custom_secret"}, // 追加需掩码的请求/响应体字段名
	HeaderMaskKeyExclusions: nil,                       // 排除的请求/响应头键名(从「内置+追加」并集中减去,放行被误伤的字段)
	BodyMaskKeyExclusions:   []string{"phone"},         // 排除的正文/查询参数字段名(如放行内置的 phone 供业务排查)

	// Multipart请求配置
	EnableMultipartSupport: true,               // 启用multipart请求支持
	MultipartMaxPartSize:   64,                 // multipart单个部分最大大小(KB)
	MultipartSkipFiles:     nil,                // *bool:nil=默认只记文件元数据,显式 false 才记录文件内容
	MultipartPreserveState: nil,                // *bool:nil=默认复制请求体,保证后续 c.FormFile 可用

	// 中间件执行顺序配置
	MiddlewareOrder: "normal",                  // 中间件执行顺序:normal/early/late

	// 日志记录器配置(可选)
	Logger:  nil,                              // 日志记录器实例
}

// 使用自定义配置
dbg, err := debugger.New(config)
if err != nil {
	panic(err)
}

router.Use(dbg.Middleware())
日志级别说明
  • LevelSilent: 静默模式,不记录任何调试日志(生产环境/关闭调试)
  • LevelInfo: 记录所有详细信息,包括请求体、响应体等(开发环境/最高调试级别)
  • LevelWarn: 只记录警告级别的信息
  • LevelError: 只记录错误级别的信息
IP访问控制

调试器组件支持IP访问控制功能,可以限制只有特定IP地址或IP段的客户端才能访问调试器界面和API接口。

配置说明
config := &debugger.Config{
    // ... 其他配置
    
    // IP访问控制配置
    AllowedIPs: []string{
        "192.168.1.100",      // 允许单个IP
        "10.0.0.0/8",         // 允许10.0.0.0-10.255.255.255整个B类网络
        "172.16.0.0/12",      // 允许172.16.0.0-172.31.255.255
        "192.168.1.0/24",     // 允许192.168.1.0-192.168.1.255
    },
}
使用规则
  1. 默认拒绝(fail-closed):AllowedIPs为空且AllowEmptyWhitelist=false时,调试页面与API路由不注册,访问返回404,并打印一行提示;这是为了避免「配置漏填」变成「公网全开」
  2. 显式开放:确需无鉴权开放时,设置AllowEmptyWhitelist: true
  3. 白名单限制:配置了IP白名单时,只有名单内的地址可以访问,支持CIDR格式(如192.168.1.0/24)
  4. 鉴权口径:一律使用ctx.ClientIP()判定,与UseCDN(只影响日志里记录的客户端IP)无关。gin默认信任所有代理,因此反向代理场景下宿主必须调用engine.SetTrustedProxies()收紧可信代理,否则伪造X-Forwarded-For/X-Real-IP即可绕过白名单
示例配置
// 开发环境:允许本地和内部网络访问
config := &debugger.Config{
    Enabled: true,
    Storage: memoryStorage,
    AllowedIPs: []string{
        "127.0.0.1",           // 本地回环
        "::1",                 // IPv6本地回环
        "192.168.1.0/24",      // 内部网络
        "10.0.0.0/8",          // 私有网络A类
    },
}

// 生产环境:只允许管理员IP访问
config := &debugger.Config{
    Enabled: true,
    Storage: fileStorage,
    AllowedIPs: []string{
        "203.0.113.100",       // 管理员IP
        "203.0.113.101",       // 备用管理员IP
    },
}

// 受控开放:明确知道风险时才使用
config := &debugger.Config{
    Enabled:             true,
    Storage:             memoryStorage,
    AllowedIPs:          []string{}, // 名单为空
    AllowEmptyWhitelist: true,       // 显式开放
}
错误响应

当IP不在白名单中时,调试器会返回HTTP 403状态码和JSON格式的错误信息:

{
    "error": "禁止访问:IP地址 172.16.1.100 不在允许列表中",
    "client_ip": "172.16.1.100",
    "allowed_ips": ["192.168.1.100", "10.0.0.0/8"]
}

凭据掩码

调试日志默认会把请求/响应原文入库并渲染到页面,其中可能含密码、验证码、令牌等敏感值。组件在「写入日志条目」这一唯一出口统一做键名匹配替换,因此页面、导出、存储三条下游路径都拿不到原文。

  • 开关:BodyMaskEnabled为*bool三态,nil(不配置)= 开启,显式false才关闭;关闭后原文照记,仅建议在受控环境使用
  • 头部:默认掩码authorization、proxy-authorization、cookie、set-cookie、x-api-key、x-access-token、x-auth-token,可用HeaderMaskKeys追加
  • 正文:默认覆盖password/pwd/old_password一类凭据字段,以及token、*_secret、api_key、session_id、captcha、sms_code、verify_code、id_card、phone等;code这类业务状态码字段刻意不在名单内,避免把接口返回值掩成不可读
  • 排除:HeaderMaskKeyExclusions/BodyMaskKeyExclusions从「内置默认 + 追加」的并集中减去指定键,用于放行被误伤的业务字段(如内置的phone、session_id恰好是要排查的字段时);排除优先级最高,同一键无论来自内置还是追加均不再掩码——这比整体关闭BodyMaskEnabled的暴露面小得多
  • 排除的边界:组件不对排除键做白名单校验,把authorization、cookie、set-cookie或password、token、*_secret一类内置凭据键排除后,其原文会照常入库、渲染到页面并进入导出。排除只应用于确认过的业务字段;生产环境不建议排除任何内置凭据键,需要临时排查时用BodyMaskEnabled=false并当场复原,避免配置长期留存
  • 查询串:URL 列与请求级 logger 的url字段走同一套键名匹配(与正文共用BodyMaskKeys与BodyMaskKeyExclusions),命中参数的值替换为***——GET 类凭据(如短信验证码接口)的敏感值只体现在查询串上,若只掩码 query_params 映射,同一份原文仍会留在 url 列,明文检索即可命中
  • 形态:正则替换、不解析重排,因此保留原始排版,且对被截断的非法JSON同样安全——正文被切成两半的凭据值,靠「尾部未闭合值」规则命中
  • 顺序:先掩码再追加[Body truncated: ...]截断说明。顺序颠倒会让说明行被当成字段值一起掩掉,也会让尾部规则匹配不到
  • 二进制:二进制正文只记摘要,不进入掩码流程
  • 默认集合演进:内置名单只减不增;确需新增默认键时视为破坏性变更(下游相关字段会悄然变为***),须在 changelog 显式标注

流式请求支持

概述

debugger组件现在支持流式请求的自动检测和记录功能,可以识别和记录Server-Sent Events (SSE)、分块传输编码等流式响应。流式请求支持允许您监控和分析实时数据流,同时保持对传统HTTP请求的完整兼容性。

功能特性
  • ✅ 自动检测: 自动识别流式响应类型(SSE、分块传输、二进制流等)
  • ✅ 分块记录: 支持流式响应的分块记录和元数据统计
  • ✅ 配置控制: 可配置分块大小限制和最大分块数量
  • ✅ 统计信息: 提供流式请求数量、平均分块数、最大分块数等统计
  • ✅ 筛选查询: 支持按流式请求状态和活跃状态进行筛选
  • ✅ Web界面支持: 在调试器Web界面中可查看流式请求详情
配置说明

流式请求支持需要显式启用,相关配置选项如下:

config := &debugger.Config{
    // ... 其他配置
    
    // 流式请求支持配置
    EnableStreamingSupport: true,                    // 启用流式请求支持
    StreamingChunkSize:     1024,                    // 流式响应分块大小(KB),默认1MB,0表示无限制
    MaxStreamingChunks:     10,                      // 最大流式响应分块数量,默认10个,0表示无限制
    MaxStreamingMemory:     10485760,                // 流式响应总内存限制(字节),默认10MB,0表示无限制
}
配置选项说明
  • EnableStreamingSupport: 是否启用流式请求支持,默认为false
  • StreamingChunkSize: 单个流式响应分块的大小限制(KB),默认1024KB(1MB),设置为0表示无限制
  • MaxStreamingChunks: 最大流式响应分块数量,默认10个,设置为0表示无限制
  • MaxStreamingMemory: 流式响应总内存使用限制(字节),默认10485760字节(10MB),设置为0表示无限制
无限制配置示例

如果您希望完全禁用流式请求的限制,可以这样配置:

config := &debugger.Config{
    EnableStreamingSupport: true,
    StreamingChunkSize:     0,      // 无分块大小限制
    MaxStreamingChunks:     0,      // 无分块数量限制
    MaxStreamingMemory:     0,      // 无内存限制
}
支持的流式响应类型
  • Server-Sent Events (SSE): Content-Type: text/event-stream
  • 分块传输编码: Transfer-Encoding: chunked
  • 流式JSON响应: Content-Type: application/x-ndjson 或 application/json-seq
  • 二进制流: Content-Type: application/octet-stream
  • WebSocket升级响应: Upgrade: websocket
使用示例
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	// 创建调试器配置,启用流式请求支持
	memoryStorage, _ := debugger.NewMemoryStorage(100)
	config := &debugger.Config{
		Enabled:                true,
		Storage:                memoryStorage,
		EnableStreamingSupport: true,    // 启用流式请求支持
		StreamingChunkSize:     512,      // 分块大小限制为512KB
		MaxStreamingChunks:     5,        // 最多记录5个分块
	}
	
	dbg, err := debugger.New(config)
	if err != nil {
		panic(err)
	}

	router := gin.New()
	router.Use(dbg.Middleware())

	// SSE流式响应示例
	router.GET("/sse", func(c *gin.Context) {
		c.Header("Content-Type", "text/event-stream")
		c.Header("Cache-Control", "no-cache")
		c.Header("Connection", "keep-alive")

		for i := 1; i <= 3; i++ {
			c.Writer.Write([]byte(fmt.Sprintf("data: 消息 %d\n\n", i)))
			c.Writer.(http.Flusher).Flush()
			time.Sleep(1 * time.Second)
		}
	})

	// 分块传输编码示例
	router.GET("/chunked", func(c *gin.Context) {
		c.Header("Transfer-Encoding", "chunked")
		
		for i := 1; i <= 4; i++ {
			chunk := fmt.Sprintf("分块 %d 内容\n", i)
			c.Writer.Write([]byte(chunk))
			c.Writer.(http.Flusher).Flush()
			time.Sleep(500 * time.Millisecond)
		}
	})

	router.Run(":8080")
}
流式请求记录内容

流式请求记录包含以下额外信息:

  • 流式响应标记: IsStreamingResponse: true
  • 分块数量: StreamingChunks: 3
  • 分块大小限制: StreamingChunkSize: 512
  • 最大分块数量: MaxStreamingChunks: 5
  • 内存使用限制: MaxStreamingMemory: 10485760
  • 流式数据摘要: StreamingData: "Streaming Response: 3 chunks, total size: 1024 bytes"
内存管理机制

调试器组件实现了智能的内存管理机制,确保流式请求记录不会导致内存溢出:

  1. 分块数量限制: 当分块数量超过MaxStreamingChunks限制时,采用LRU策略移除最旧的分块
  2. 分块大小限制: 单个分块大小超过StreamingChunkSize限制时,数据会被截断并添加"[truncated]"标记
  3. 总内存限制: 当所有分块的总内存使用量超过MaxStreamingMemory限制时,持续移除最旧的分块直到满足限制
  4. 无限制支持: 所有限制都支持设置为0,表示无限制记录
Web界面筛选

在调试器Web界面中,您可以使用以下筛选选项:

  • 流式状态筛选: 所有流式状态 / 流式请求 / 非流式请求
  • 流式活跃状态: 活跃流式请求 / 非流式请求
  • 错误状态筛选: 所有错误状态 / 仅看含error / 仅看无error(基于派生严重度,见下文)
  • 服务筛选: 所有服务 / 指定服务标识(多服务共享存储时区分日志来源,下拉选项异步加载自api/services接口并附带条目计数,未配置ServiceName的历史条目不进入选项)
派生严重度(列表error识别)

日志条目在保存时会自动统计派生严重度字段(UpdateSeverity),用于在列表中直观识别"虽然执行完成但含error日志"的记录:

  • has_error: 是否存在错误。判定规则:含error级Logger日志、error字段非空、或HTTP状态码 >= 500
  • error_count: Logger日志中error级别的数量
  • warn_count: Logger日志中warn级别的数量

列表页展示效果:

  • 进程记录:状态(如completed)旁显示橙色⚠ N徽标(N为error数量),warn数量以灰色徽标显示
  • HTTP记录:状态码旁同样显示徽标(状态码200但含error日志时也会高亮)
  • 含error的行整行浅红色背景高亮
  • 筛选区提供"仅看含error"开关(对应has_error过滤参数,三种存储均支持)

统计时机:HTTP中间件保存前、ProcessLogger.EndProcess、Debugger.EndProcess。历史数据在列表/详情读取时会自动现算补全,无需迁移。

Logger功能

概述

debugger组件提供了内置的Logger功能,支持多级别日志记录和结构化字段附加。Logger可以在HTTP请求处理过程中记录调试信息,也可以在进程级Debugger中使用,为应用程序提供统一的日志记录解决方案。

功能特性
  • ✅ 多级别日志: 支持Silent、Error、Warn、Info四种日志级别
  • ✅ 结构化字段: 支持添加自定义字段到日志记录
  • ✅ 日志收集: 自动收集Logger日志并与HTTP请求或进程记录关联
  • ✅ 级别控制: 支持根据配置的日志级别过滤日志记录
基本使用示例
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	dbg, err := debugger.NewSimpleDebugger()
	if err != nil {
		panic(err)
	}

	router := gin.New()
	router.Use(dbg.Middleware())

	router.GET("/api/users", func(c *gin.Context) {
		// 获取当前请求的Logger实例
		logger := debugger.GetLoggerFromContext(c)
		
		// 记录不同级别的日志
		logger.Info("开始处理用户请求")
		logger.Info("用户ID", map[string]interface{}{"user_id": 123})
		logger.Warn("用户权限检查", map[string]interface{}{"permission": "read"})
		
		// 使用WithFields创建带字段的Logger
		userLogger := logger.WithFields(map[string]interface{}{
			"user_id": 123,
			"action": "get_user",
		})
		
		userLogger.Info("获取用户信息")
		
		// 记录错误信息
		if err := someBusinessLogic(); err != nil {
			logger.Error("业务逻辑错误", map[string]interface{}{
				"error": err.Error(),
				"stack": "调用堆栈信息",
			})
		}
		
		c.JSON(200, gin.H{"message": "Hello World"})
	})

	router.Run(":8080")
}
Logger接口方法
// LoggerInterface 日志记录器接口
type LoggerInterface interface {
	// Info 记录信息级别日志
	Info(msg any, fields ...map[string]interface{})

	// Warn 记录警告级别日志
	Warn(msg any, fields ...map[string]interface{})

	// Error 记录错误级别日志
	Error(msg any, fields ...map[string]interface{})

	// WithFields 创建带有字段的日志记录器
	WithFields(fields map[string]interface{}) LoggerInterface

	// GetLevel 获取当前日志记录器的日志级别
	GetLevel() LogLevel
}
Context 辅助函数(请求级 Logger 与标准 context 桥接)

Debugger 中间件在处理请求时,除了把请求级 Logger 存入 gin.Context(键 debugger_logger)之外, 还会同步注入到 c.Request.Context() 中。这样业务代码中沿用 GORM 惯用的 WithContext(c.Request.Context()) 写法,SQL 日志即可自动归属到当前请求的调试详情(需配合 ORM 组件的上下文感知 SQL 日志模式,见 component/orm/README.md)。

import "github.com/jcbowen/jcbaseGo/component/debugger"

// 将 Logger 注入标准 context(中间件已自动完成,业务代码通常无需调用)
ctx = debugger.ContextWithLogger(ctx, logger)

// 从 context 中取 Logger,取不到时返回 NoopLogger(安全空实现)
logger := debugger.LoggerFromContext(ctx)

// 仅判断 context 中是否存在 Logger,不创建实例
exists := debugger.HasLoggerFromContext(ctx)

// 摘除 context 中的 Logger,供 WebSocket 等长连接场景使用,
// 避免长连接期间的日志累积写入早已归档的请求日志
ctx = debugger.ContextWithoutLogger(ctx)

注意事项:

  • ContextWithLogger 使用私有 key 类型,不会与其他包的 context key 冲突;
  • WebSocket 等长连接场景,握手完成后建议改用 context.Background() 或调用 ContextWithoutLogger 摘除请求级 Logger。
位置信息记录功能

调试器组件现在支持自动记录日志打印的位置信息,包括文件名、行号和函数名。这个功能可以帮助开发者快速定位日志输出的具体位置,提高调试效率。

功能特性
  • ✅ 自动位置记录: 每次日志调用自动记录调用位置
  • ✅ 完整位置信息: 包含文件名、行号、函数名
  • ✅ 结构化存储: 位置信息存储在LoggerLog结构体中
  • ✅ 格式化输出: 日志输出包含位置信息格式
位置信息字段
type LoggerLog struct {
	Timestamp time.Time              `json:"timestamp"` // 时间戳
	Level     string                 `json:"level"`     // 日志级别
	Message   string                 `json:"message"`   // 日志消息
	Fields    map[string]interface{} `json:"fields"`    // 附加字段
	FileName  string                 `json:"fileName"`  // 文件名(新增)
	Line      int                    `json:"line"`      // 行号(新增)
	Function  string                 `json:"function"`  // 函数名(新增)
}
日志输出格式

日志输出现在包含位置信息,格式为:

[级别] 文件名:行号 函数名: 消息内容

示例输出:

[INFO] debugger_test.go:209 TestLoggerLocationInfo.func1: 测试位置信息记录
使用示例

位置信息记录功能是自动启用的,无需额外配置。所有通过Logger接口记录的日志都会自动包含位置信息。

// 获取调试器的Logger实例
logger := dbg.GetLogger()

// 记录日志(自动包含位置信息)
logger.Info("用户登录成功", map[string]interface{}{
	"user_id": 123,
	"username": "张三",
})

// 输出示例:
// [INFO] user_controller.go:45 handleUserLogin: 用户登录成功
测试验证

可以通过测试用例验证位置信息记录功能:

func TestLoggerLocationInfo(t *testing.T) {
	dbg, _ := debugger.NewSimpleDebugger()
	logger := dbg.GetLogger()
	
	// 记录测试日志
	logger.Info("测试位置信息记录")
	
	// 验证位置信息字段
	// FileName: 包含当前测试文件名
	// Line: 包含调用日志的行号
	// Function: 包含调用日志的函数名
}
日志级别说明
  • LevelSilent: 静默模式,不记录任何调试日志(生产环境/关闭调试)
  • LevelError: 只记录错误级别的信息
  • LevelWarn: 记录错误和警告级别的信息(默认级别)
  • LevelInfo: 记录所有详细信息,包括请求体、响应体等(开发环境/最高调试级别)
消息格式支持

Logger支持多种消息格式:

  • 字符串: logger.Info("用户登录成功")
  • 结构体: logger.Info(User{ID: 123, Name: "张三"})
  • Map: logger.Info(map[string]interface{}{"user_id": 123, "action": "login"})
  • 实现Stringer接口的类型: logger.Info(customStringer)

进程级Debugger功能

概述

debugger组件现在支持进程级日志记录功能,可以在非HTTP请求场景下记录进程执行日志。进程级debugger允许您为后台任务、批处理作业、定时任务等非HTTP进程创建独立的日志记录器,并支持与HTTP请求日志共存于同一存储中。

功能特性
  • ✅ 进程记录管理: 支持创建、获取、结束进程记录
  • ✅ 多级日志记录: 支持Silent、Error、Warn、Info四种日志级别
  • ✅ 结构化字段: 支持添加自定义字段到日志记录
  • ✅ 存储共存: 进程记录与HTTP请求记录共存于同一存储
  • ✅ 查询过滤: 支持按进程名称、进程ID、记录类型等条件过滤
  • ✅ Web界面支持: 在调试器Web界面中可查看进程记录

注:进程级Debugger继承了Logger的所有功能特性。

基本使用示例
package main

import (
	"fmt"
	"time"

	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	// 创建调试器实例
	dbg, err := debugger.NewProductionDebugger("/var/log/debug_logs")
	if err != nil {
		panic(err)
	}

	// 启动一个进程记录
	logger := dbg.StartProcess("数据同步任务", "batch")
	defer dbg.EndProcess(logger.GetProcessID(), debugger.ProcessStatusCompleted) // 确保进程结束时记录结束时间

	// 记录进程执行日志
	logger.Info("开始执行数据同步任务", map[string]interface{}{
		"source": "MySQL",
		"target": "Elasticsearch",
		"batch_size": 1000,
	})

	// 模拟数据处理
	for i := 0; i < 5; i++ {
		logger.Info("获取数据源信息", map[string]interface{}{
			"source": "MySQL",
			"table": "users",
		})
		time.Sleep(100 * time.Millisecond)

		if i == 2 {
			logger.Warn("遇到网络延迟", map[string]interface{}{
				"retry_count": 1,
				"delay_ms": 500,
			})
		}
	}

	// 记录任务完成
	logger.Info("数据同步任务完成", map[string]interface{}{
		"processed_records": 5000,
		"duration_seconds": 2.5,
		"status": "success",
	})
}
进程记录方法
启动进程记录
// 启动进程记录,返回进程级Logger实例
logger := dbg.StartProcess(processName string, processType string)
获取进程Logger
// 通过进程ID获取对应的Logger实例
logger, err := dbg.GetProcessLogger(processID string)
结束进程记录
// 结束进程记录,记录结束时间和状态
err := dbg.EndProcess(processID string, status string)

进程状态常量

为了更好的代码可维护性,建议使用预定义的进程状态常量。这些常量定义在debugger包中:

// 进程状态常量定义(位于debugger包中)
const (
	ProcessStatusCompleted = "completed" // 进程正常完成
	ProcessStatusFailed    = "failed"    // 进程执行失败
	ProcessStatusCancelled = "cancelled" // 进程被取消
)

使用示例:

// 推荐使用常量
dbg.EndProcess(logger.GetProcessID(), debugger.ProcessStatusCompleted)

// 不推荐使用字符串字面量
dbg.EndProcess(logger.GetProcessID(), "completed")

注意: StartProcess 返回的记录器会登记到调试器内部注册表,因此无论调用 logger.EndProcess(status) 还是 dbg.EndProcess(processID, status),Logger收集的日志都会随记录一并落库,并在保存前自动统计派生严重度字段(has_error/error_count/warn_count)。即使进程状态为completed,只要Logger中记录过error级日志,列表中也会显示error徽标并高亮该行,便于快速定位问题进程。GetProcessLogger 对运行中的进程返回注册表中的同一记录器实例,保证日志汇聚。

获取进程记录列表
// 获取进程记录列表,支持分页和过滤
records, total, err := dbg.GetProcessRecords(page int, pageSize int, filters map[string]interface{})
高级使用示例
并发进程管理
package main

import (
	"sync"
	"time"

	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func processWorker(dbg *debugger.Debugger, wg *sync.WaitGroup, workerID int) {
	defer wg.Done()

	// 为每个工作进程创建独立的记录
	logger := dbg.StartProcess(fmt.Sprintf("工作进程-%d", workerID), "worker")
	defer dbg.EndProcess(logger.GetProcessID(), debugger.ProcessStatusCompleted)

	logger.Info("工作进程启动", map[string]interface{}{
		"worker_id": workerID,
		"start_time": time.Now().Format(time.RFC3339),
	})

	// 模拟工作负载
	for i := 0; i < 3; i++ {
		logger.Info(fmt.Sprintf("处理任务批次 %d", i+1), map[string]interface{}{
			"batch": i + 1,
			"worker": workerID,
		})
		time.Sleep(200 * time.Millisecond)
	}

	logger.Info("工作进程完成", map[string]interface{}{
		"worker_id": workerID,
		"end_time": time.Now().Format(time.RFC3339),
		"tasks_processed": 3,
	})
}

func main() {
	dbg, _ := debugger.NewWithMemoryStorage(1000)
	
	var wg sync.WaitGroup
	
	// 启动3个并发工作进程
	for i := 1; i <= 3; i++ {
		wg.Add(1)
		go processWorker(dbg, &wg, i)
	}
	
	wg.Wait()
	
	// 获取所有进程记录
	records, total, err := dbg.GetProcessRecords(1, 20, nil)
	if err != nil {
		fmt.Printf("获取进程记录失败: %v\n", err)
	} else {
		fmt.Printf("共完成 %d 个进程记录,总计 %d 条记录\n", len(records), total)
	}
}
批处理任务监控
package main

import (
	"time"

	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func batchProcessor(dbg *debugger.Debugger) {
	// 创建批处理任务记录
	logger := dbg.StartProcess("夜间批处理任务", "batch")
	defer dbg.EndProcess(logger.GetProcessID(), debugger.ProcessStatusCompleted)

	logger.Info("开始夜间批处理", map[string]interface{}{
		"scheduled_time": "02:00",
		"estimated_duration": "2小时",
	})

	// 模拟多个处理步骤
	steps := []string{"数据备份", "统计计算", "报告生成", "清理临时文件"}
	
	for i, step := range steps {
		stepLogger := logger.WithFields(map[string]interface{}{
			"step_number": i + 1,
			"step_name": step,
		})
		
		stepLogger.Info("开始处理步骤")
		time.Sleep(500 * time.Millisecond) // 模拟处理时间
		
		if i == 1 {
			stepLogger.Warn("统计计算耗时较长", map[string]interface{}{
				"actual_duration": "45分钟",
				"expected_duration": "30分钟",
			})
		}
		
		stepLogger.Info("步骤处理完成")
	}

	logger.Info("夜间批处理任务完成", map[string]interface{}{
		"total_steps": len(steps),
		"completion_time": time.Now().Format(time.RFC3339),
		"status": "success",
	})
}

func main() {
	dbg, _ := debugger.NewWithFileStorage("/var/log/batch_logs", 5000)
	batchProcessor(dbg)
}
查询和过滤进程记录

进程记录支持与HTTP请求记录相同的查询和过滤功能:

// 查询所有进程记录
filters := map[string]interface{}{
	"record_type": "process", // 按记录类型过滤
}
logs, total, err := storage.FindAll(1, 20, filters)

// 按进程名称过滤
filters = map[string]interface{}{
	"process_name": "数据同步任务",
}
logs, total, err := storage.FindAll(1, 10, filters)

// 按进程ID过滤
filters = map[string]interface{}{
	"process_id": "process-123456",
}
logs, total, err := storage.FindAll(1, 10, filters)

// 搜索进程记录
result, total, err := storage.Search("同步", 1, 10)
Web界面查看

在调试器Web界面中,您可以:

  1. 在日志列表页面使用"记录类型"过滤器查看进程记录
  2. 通过"进程名称"或"进程ID"进行精确过滤
  3. 在详情页面查看进程的完整执行日志和时间线
  4. 使用关键词搜索功能查找特定进程记录

访问调试器界面:http://localhost:8080/jcbase/debug/list

查看完整示例

更多详细的使用示例,请查看:

  • example/debugger/process_usage.go - 完整的进程级debugger使用示例

Logger功能使用

在控制器中使用Logger

debugger组件提供了Logger接口,可以在业务控制器中记录调试日志。通过GetLoggerFromContext函数可以从Gin上下文中获取Logger实例。

基本使用示例
package main

import (
	"net/http"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	r := gin.Default()

	// 创建调试器实例
	dbg, err := debugger.NewWithMemoryStorage(100)
	if err != nil {
		panic(err)
	}

	// 添加调试器中间件
	r.Use(dbg.Middleware())

	// 在控制器中使用Logger
	r.GET("/api/users", func(c *gin.Context) {
		// 从上下文中获取Logger实例
		logger := debugger.GetLoggerFromContext(c)

		// 记录不同级别的日志
		logger.Info("开始处理用户列表请求", map[string]interface{}{
			"query_params": c.Request.URL.Query(),
			"page":         c.Query("page"),
			"limit":        c.Query("limit"),
		})

		// 模拟数据库查询
		time.Sleep(50 * time.Millisecond)

		logger.Info("用户列表查询成功", map[string]interface{}{
			"user_count": 3,
			"status_code": http.StatusOK,
		})

		c.JSON(http.StatusOK, gin.H{
			"users": []gin.H{
				{"id": 1, "name": "张三"},
				{"id": 2, "name": "李四"},
				{"id": 3, "name": "王五"},
			},
		})
	})

	r.Run(":8080")
}
Logger接口方法

Logger接口支持的方法与Logger功能章节中定义的LoggerInterface接口一致,包括Info、Warn、Error三种日志级别记录方法,以及WithFields和GetLevel方法。

使用WithFields添加结构化字段
// 在控制器中使用WithFields
r.GET("/api/users/:id", func(c *gin.Context) {
	userID := c.Param("id")

	// 使用WithFields创建带有用户ID的logger
	logger := debugger.GetLoggerFromContext(c).WithFields(map[string]interface{}{
		"user_id": userID,
		"endpoint": "/api/users/:id",
	})

	logger.Info("开始查询用户详情")

	// 模拟用户不存在的情况
	if userID == "999" {
		logger.Warn("用户不存在", map[string]interface{}{
			"reason": "数据库中未找到该用户",
		})
		c.JSON(http.StatusNotFound, gin.H{"error": "用户不存在"})
		return
	}

	logger.Info("用户详情查询成功")
	c.JSON(http.StatusOK, gin.H{"id": userID, "name": "示例用户"})
})
错误处理示例
r.GET("/api/error", func(c *gin.Context) {
	logger := debugger.GetLoggerFromContext(c)

	logger.Info("开始处理错误示例请求")

	// 模拟业务逻辑错误
	err := fmt.Errorf("数据库连接失败: 连接超时")

	logger.Error("业务处理失败", map[string]interface{}{
		"error":         err.Error(),
		"error_type":    "database_connection_timeout",
		"retry_count":   3,
		"last_attempt":  time.Now().Format(time.RFC3339),
	})

	c.JSON(http.StatusInternalServerError, gin.H{
		"error": "服务器内部错误",
		"details": "请稍后重试",
	})
})
查看完整示例

更多详细的使用示例,请查看:

  • example/debugger/logger_usage.go - 完整的Logger使用示例
  • example/debugger/basic_usage.go - 基础使用示例

主进程日志功能

概述

debugger组件提供了主进程日志功能,用于记录应用程序主进程的日志,采用文件存储方式,支持按日期或大小分割日志文件,有效避免日志文件过大。

功能特性
  • ✅ 文件存储: 主进程日志采用文件存储,路径可配置
  • ✅ 日志分割: 支持按日期或大小两种分割模式
  • ✅ 配置简单: 复用debugger的日志级别和调用位置信息配置
  • ✅ 易于使用: 提供便捷的API接口
  • ✅ 与现有系统集成: 与debugger组件无缝集成
配置说明

主进程日志功能需要在调试器配置中显式启用,相关配置选项如下:

config := &debugger.Config{
    // ... 其他配置
    
    // 主进程日志配置
    EnableMainLogger:   true,                  // 启用主进程日志
    MainLogPath:        "./runtime/logs/",   // 日志文件路径(默认:./runtime/logs/)
    MainLogSplitMode:   "size",              // 日志分割模式:size(按大小)、date(按日期)
    MainLogMaxSize:     100,                  // 日志文件最大大小(MB),按大小分割时有效
    MainLogMaxBackups:  7,                    // 最大备份文件数量
    MainLogCompress:    false,                // 是否压缩备份日志
    
    // 主进程日志复用以下配置项
    Level:            debugger.LevelInfo,    // 日志级别(与主进程日志共享)
    EnableCallerInfo: &callerInfo,            // 是否启用调用位置信息(*bool:nil默认开启,显式false关闭)
}
存储方式和日志分割
存储方式
  • 文件存储: 主进程日志采用文件存储,存储路径可通过MainLogPath配置
  • 默认路径: ./runtime/logs/
  • 文件名格式:
    • 按日期分割: process.log.2024-01-01
    • 按大小分割: process.log.1, process.log.2
日志分割机制
  1. 按日期分割 (date):

    • 每天0点自动创建新的日志文件
    • 文件名格式: process.log.YYYY-MM-DD
    • 例如: process.log.2024-01-01, process.log.2024-01-02
  2. 按大小分割 (size):

    • 当日志文件大小达到MainLogMaxSize指定的大小(MB)时,创建新的日志文件
    • 文件名格式: process.log.N(N从1开始递增)
    • 例如: process.log.1, process.log.2, process.log.3
  3. 日志备份和清理:

    • 最多保留MainLogMaxBackups个备份文件
    • 超过最大备份数量时,自动删除最旧的日志文件
    • 支持配置是否压缩备份日志
基本使用示例
1. 启用主进程日志
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	// 创建调试器配置
	callerInfo := true // *bool 三态:nil(未配置)默认开启;显式 false 生效关闭
	config := &debugger.Config{
		Enabled:            true,
		EnableMainLogger:   true,                  // 启用主进程日志
		MainLogPath:        "./runtime/logs/",   // 日志文件路径
		MainLogSplitMode:   "date",              // 按日期分割
		MainLogMaxSize:     100,                  // 单个文件最大100MB
		MainLogMaxBackups:  7,                    // 保留7个备份文件
		Level:             debugger.LevelInfo,   // 日志级别
		EnableCallerInfo:  &callerInfo,          // 启用调用位置信息(*bool:nil默认开启,显式false关闭)
	}

	// 创建调试器实例
	dbg, err := debugger.New(config)
	if err != nil {
		panic(err)
	}

	// 获取主进程日志记录器
	mainLogger := dbg.GetMainLogger()

	// 记录主进程日志
	mainLogger.Info("应用程序启动")
	mainLogger.Info("初始化配置", map[string]interface{}{"config_path": "./config.yml"})
	mainLogger.Warn("使用默认配置,建议在生产环境中指定自定义配置")

	router := gin.New()
	router.Use(dbg.Middleware())

	router.GET("/api/users", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "Hello World"})
	})

	mainLogger.Info("服务器启动成功", map[string]interface{}{"port": 8080})
	router.Run(":8080")
}
2. 记录不同级别的日志
// 获取主进程日志记录器
mainLogger := dbg.GetMainLogger()

// 记录信息级别日志
mainLogger.Info("应用程序启动")
mainLogger.Info("处理请求", map[string]interface{}{
    "method": "GET",
    "url":    "/api/users",
})

// 记录警告级别日志
mainLogger.Warn("配置文件不存在,使用默认配置", map[string]interface{}{
    "config_path": "./config.yml",
})

// 记录错误级别日志
mainLogger.Error("数据库连接失败", map[string]interface{}{
    "error": "connection refused",
    "host":  "localhost",
    "port":  3306,
})

高级功能

采样率配置

采样率可以控制记录日志的频率,避免在高并发场景下产生过多日志:

memoryStorage, _ := debugger.NewMemoryStorage(10000)
config := &debugger.Config{
    Enabled:    true,
    Storage:    memoryStorage,
    MaxRecords: 10000,
    Level:      debugger.LevelInfo,
    
    // 采样率配置:每10个请求记录1个(10%采样率)
    SampleRate: 0.1,
}

dbg, err := debugger.New(config)
if err != nil {
    panic(err)
}
过滤配置

可以配置请求过滤规则,避免记录某些不需要的请求:

memoryStorage, _ := debugger.NewMemoryStorage(10000)
config := &debugger.Config{
    Enabled:    true,
    Storage:    memoryStorage,
    MaxRecords: 10000,
    Level:      debugger.LevelInfo,
    
    // 过滤配置
    SkipPaths: []string{
        "/static/*",
        "/favicon.ico",
        "/robots.txt",
    },
    
    // 忽略特定HTTP方法
    SkipMethods: []string{"OPTIONS"},
    
    // 最大请求体大小(字节)
    MaxBodySize:     1024,        // 1MB(单位:KB)
}

dbg, err := debugger.New(config)
if err != nil {
    panic(err)
}
自定义存储

您可以实现自己的存储后端:

type CustomStorage struct {
    // 实现 Storage 接口
}

func (s *CustomStorage) Save(entry *LogEntry) error {
    // 自定义保存逻辑
}

func (s *CustomStorage) FindByID(id string) (*LogEntry, error) {
    // 自定义查询逻辑
}

// 实现其他接口方法...

破坏性变更提醒:Storage接口已新增GetServices() (map[string]int, error)方法(服务标识统计,参照GetMethods实现即可),自定义存储实现升级后需补齐该方法才能通过编译。

进程级调试器支持

调试器组件支持进程级日志记录,适用于后台任务、批处理作业、定时任务等非HTTP进程场景。

基本使用
// 开始进程记录
logger := dbg.StartProcess("数据同步任务", "batch")
defer dbg.EndProcess(logger.GetProcessID(), "completed")

// 记录进程日志
logger.Info("开始处理数据同步")
logger.Info("获取数据源信息", map[string]interface{}{
    "source": "MySQL",
    "table": "users",
})

// 更新进度
logger.UpdateProgress(25.0)

// 记录警告和错误
logger.Warn("发现重复数据", map[string]interface{}{
    "duplicate_count": 5,
})

// 完成进程
logger.Info("数据同步完成", map[string]interface{}{
    "processed_count": 1000,
    "success_count": 995,
    "error_count": 5,
})
进程记录器接口
type ProcessLoggerInterface interface {
    LoggerInterface

    // GetProcessID 获取进程ID
    GetProcessID() string

    // GetProcessName 获取进程名称
    GetProcessName() string

    // GetProcessType 获取进程类型
    GetProcessType() string

    // GetStartTime 获取进程开始时间
    GetStartTime() time.Time

    // SetProcessInfo 设置进程信息
    SetProcessInfo(info map[string]interface{})

    // EndProcess 结束进程记录
    EndProcess(status string) error
}
流式请求支持

调试器组件支持流式请求的完整记录,包括流式响应的元数据和状态跟踪。

启用流式支持
config := &debugger.Config{
    Enabled:               true,
    EnableStreamingSupport: true,  // 启用流式请求支持
    MaxRecords:            1000,
}

dbg, err := debugger.New(config)
流式请求记录

流式请求会自动记录以下信息:

  • 流式请求标识
  • 流式状态(started/processing/completed)
  • 响应块数量
  • 流式响应相关元数据
查询和搜索功能
基本查询
// 通过调试器实例获取存储
storage := dbg.GetStorage()

// 查询最近的日志
logs, total, err := storage.FindAll(1, 10, nil)

// 按时间范围查询
startTime := time.Now().AddDate(0, 0, -7) // 一周前
endTime := time.Now()
filters := map[string]interface{}{
    "start_time": startTime,
    "end_time":   endTime,
}
result, total, err := storage.FindAll(1, 20, filters)

// 按方法查询
filters = map[string]interface{}{
    "method": "POST",
}
result, total, err := storage.FindAll(1, 10, filters)

// 按状态码查询
filters = map[string]interface{}{
    "status_code": 404,
}
result, total, err := storage.FindAll(1, 10, filters)

// 按服务标识查询(多服务共享存储时区分日志来源,三种存储均支持)
filters = map[string]interface{}{
    "service_name": "gateway",
}
result, total, err := storage.FindAll(1, 10, filters)

// 查询错误日志(has_error基于派生严重度:含error级日志/error字段非空/状态码>=500)
filters = map[string]interface{}{
    "has_error": true,
}
result, total, err := storage.FindAll(1, 10, filters)
高级查询
// 使用查询选项
options := debugger.QueryOptions{
	Page:     1,
	PageSize: 20,
	Filters: map[string]interface{}{
		"method":      "POST",
		"status_code": 200,
		"url_contains": "/api",
		"has_error":   false,
	},
	SortBy:    "timestamp",
	SortOrder: "desc",
}

result, err := queryManager.Query(options)
全文搜索
// 搜索包含关键词的日志
result, total, err := storage.Search("用户", 1, 10)
Logger日志显示功能

debugger组件现在支持在详情页面中显示业务控制器中记录的logger日志。当您在控制器中使用GetLoggerFromContext记录日志时,这些日志会自动收集并在日志详情页面中显示。

功能特性
  • ✅ 自动收集: 在请求处理过程中自动收集logger日志
  • ✅ 级别区分: 支持Silent、Error、Warn、Info四种日志级别
  • ✅ 结构化字段: 显示日志的附加字段信息
  • ✅ 时间戳: 记录每条日志的精确时间戳
  • ✅ 响应式布局: 适配不同屏幕尺寸的显示
在详情页中查看Logger日志
  1. 访问调试器列表页面:http://localhost:8080/jcbase/debug/list
  2. 点击任意日志条目的"详情"按钮
  3. 在详情页面中查看"Logger日志"区域
示例效果

当您在控制器中记录如下日志:

logger := debugger.GetLoggerFromContext(c)
logger.Info("开始处理请求", map[string]interface{}{
    "user_id": 123,
    "action": "create_user",
})
logger.Info("用户创建成功")
logger.Warn("密码强度较弱")
logger.Error("数据库连接失败", map[string]interface{}{
    "error": "connection timeout",
    "retry_count": 3,
})

在详情页面中,您将看到格式化的logger日志显示:

  • DEBUG 开始处理请求 (user_id: 123, action: create_user)
  • INFO 用户创建成功
  • WARN 密码强度较弱
  • ERROR 数据库连接失败 (error: connection timeout, retry_count: 3)
详情查看功能
// 创建详情查看器
detailViewer := debugger.NewDetailViewer(queryManager)

// 获取日志详情
detail, err := detailViewer.GetDetail("log_id")

// 获取HTML格式的详情
html, err := detailViewer.GetDetailHTML("log_id")

// 获取JSON格式的详情
jsonData, err := detailViewer.GetDetailJSON("log_id")

// 比较两个日志条目
comparison, err := detailViewer.CompareEntries("id1", "id2")
增强型 JSON 查看器

详情页对 JSON 内容(请求体、响应体、流式响应数据、Logger 日志、会话数据)提供了类 VSCode 的查看体验:

  • JSON 美化:自动缩进格式化并语法高亮
  • 层级折叠/展开:对象 {} 与数组 [] 支持点击箭头折叠,提供「全部展开」「全部折叠」按钮
  • 自动修复:基于 VSCode 同款 jsonc-parser 库,自动处理注释、尾部逗号等常见非标准 JSON
  • 原始/修复后切换:当 JSON 存在格式问题时,可在原始内容与修复后内容之间切换查看
  • 一键复制:支持复制原始或修复后的 JSON 内容

JSON 查看器依赖的 jsonc-parser 静态资源已内嵌到组件中(component/debugger/static/jsonc-parser.bundle.js),无需依赖外部 CDN。

统计信息
// 获取统计信息
stats, err := queryManager.GetStats()

// 统计信息包含:
// - 存储统计(总数、错误率等)
// - 方法统计(各HTTP方法的请求数量)
// - 状态码统计(各状态码的分布)
// - 时间统计(今天、本周、本月的请求数量)
数据导出
// 导出为JSON格式
jsonData, err := queryManager.Export("json", options)

// 导出为CSV格式
csvData, err := queryManager.Export("csv", options)

Gin控制器使用指南

调试器组件提供了完整的Gin控制器,可以快速集成到现有的Gin应用中,提供Web管理界面。

基本使用
1. 使用默认路由配置
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	// 创建Gin引擎
	router := gin.Default()
	
	// 创建调试器实例(推荐使用便捷构造函数)
	dbg, err := debugger.NewWithMemoryStorage(1000)
	if err != nil {
		panic(err)
	}
	
	// 注册调试器路由(使用默认路径:/jcbase/debug)
	dbg.RegisterRoutes(router)
	
	// 添加业务路由
	router.GET("/api/users", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "Hello World"})
	})
	
	router.Run(":8080")
}
2. 使用自定义路由组
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	router := gin.Default()
	
	// 创建调试器实例
	dbg, err := debugger.NewWithMemoryStorage(1000)
	if err != nil {
		panic(err)
	}
	
	// 创建自定义路由组
	adminGroup := router.Group("/admin")
	adminGroup.Use(authMiddleware()) // 添加认证中间件
	
	// 注册调试器路由到自定义路由组
	dbg.RegisterRoutes(adminGroup)
	
	router.Run(":8080")
}
3. 高级配置
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/jcbowen/jcbaseGo/component/debugger"
)

func main() {
	router := gin.Default()
	
	// 创建调试器实例
	dbg, err := debugger.NewWithMemoryStorage(1000)
	if err != nil {
		panic(err)
	}
	
	// 创建自定义控制器配置
	controllerConfig := &debugger.ControllerConfig{
		BasePath: "/custom/debug", // 自定义基础路径
		Title:    "调试管理界面",     // 自定义页面标题
		PageSize: 50,               // 自定义每页显示数量
	}
	
	// 创建自定义路由组
	adminGroup := router.Group("/admin")
	
	// 创建控制器实例
	controller := debugger.NewController(dbg, adminGroup, controllerConfig)
	
	// 控制器会自动注册路由到指定的路由组
	
	router.Run(":8080")
}
控制器功能

Gin控制器提供以下功能:

1. 日志列表页面
  • 路径:GET /jcbase/debug/
  • 功能:显示所有调试日志的列表,支持分页和搜索
2. 日志详情页面
  • 路径:GET /jcbase/debug/detail/:id
  • 功能:显示单个日志的详细信息,包括请求头、响应头、请求体等
3. 搜索功能
  • 路径:GET /jcbase/debug/list?q=关键词
  • 功能:在日志列表页面顶部提供搜索框,支持关键词搜索请求头、响应头、请求体等内容,搜索结果直接在列表页显示
4. API接口

控制器还提供对应的API接口,方便前端集成:

  • GET /jcbase/debug/api/logs - 获取日志列表(JSON格式)
  • GET /jcbase/debug/api/logs/:id - 获取日志详情(JSON格式)
  • GET /jcbase/debug/api/search - 搜索日志(JSON格式)
  • GET /jcbase/debug/api/services - 获取服务标识列表及条目计数(JSON格式,供前端筛选下拉异步加载)
示例代码

项目提供了完整的示例代码,位于 example/debugger/ 目录下:

  • basic_usage.go - 基础使用示例,包含GIN框架集成和基本路由
  • file_storage.go - 文件存储使用示例,支持日志文件管理
  • controller_usage.go - 控制器使用示例,提供调试器Web界面
  • config_examples.go - 配置示例,包含6种不同的配置方式
  • process_usage.go - 进程级debugger使用示例,演示进程级日志记录功能

运行示例代码:

cd example/debugger/
go run basic_usage.go

Web管理界面

调试器组件可以轻松集成到Web管理界面中:

日志列表接口
router.GET("/admin/debug/logs", func(c *gin.Context) {
	page := getIntParam(c, "page", 1)
	pageSize := getIntParam(c, "page_size", 20)
	
	options := debugger.QueryOptions{
		Page:     page,
		PageSize: pageSize,
		Filters:  buildFilters(c),
		SortBy:   c.DefaultQuery("sort_by", "timestamp"),
		SortOrder: c.DefaultQuery("sort_order", "desc"),
	}
	
	result, err := queryManager.Query(options)
	if err != nil {
		c.JSON(500, gin.H{"error": err.Error()})
		return
	}
	
	c.JSON(200, result)
})
日志详情接口
router.GET("/admin/debug/logs/:id", func(c *gin.Context) {
	id := c.Param("id")
	
	detail, err := detailViewer.GetDetail(id)
	if err != nil {
		c.JSON(404, gin.H{"error": "日志不存在"})
		return
	}
	
	c.JSON(200, detail)
})
统计信息接口
router.GET("/admin/debug/stats", func(c *gin.Context) {
	stats, err := queryManager.GetStats()
	if err != nil {
		c.JSON(500, gin.H{"error": err.Error()})
		return
	}
	
	c.JSON(200, stats)
})

存储方式比较

存储方式 创建方式 优点 缺点 适用场景
内存存储器 NewMemoryStorage(maxSize) 速度快,零配置 数据易丢失,重启后清空 开发环境,临时调试
文件存储器 NewFileStorage(path, maxSize) 数据持久化,易于备份 文件IO可能成为瓶颈 生产环境,中小规模应用
数据库存储器 NewDatabaseStorage(db, tableName) 查询性能好,支持复杂查询 需要数据库依赖 生产环境,大规模应用
存储创建示例
// 内存存储器(默认10000条记录)
memoryStorage, err := debugger.NewMemoryStorage()

// 内存存储器(自定义最大记录数)
memoryStorage, err := debugger.NewMemoryStorage(5000)

// 文件存储器(默认路径,默认10000条记录)
fileStorage, err := debugger.NewFileStorage("/var/log/debug_logs")

// 文件存储器(自定义最大记录数)
fileStorage, err := debugger.NewFileStorage("/var/log/debug_logs", 20000)

// 数据库存储器(需要GORM连接)
databaseStorage, err := debugger.NewDatabaseStorage(db, "debug_logs")

// 推荐使用便捷构造函数直接创建调试器
dbg, err := debugger.NewWithMemoryStorage(1000)  // 内存存储
dbg, err := debugger.NewWithFileStorage("/var/log/debug_logs", 5000)  // 文件存储
dbg, err := debugger.NewProductionDebugger("/var/log/debug_logs")  // 生产环境配置
多服务共享存储(ServiceName)

多个服务(如1个Gin网关 + 多个gRPC服务)可共享同一个存储(典型场景:共用MySQL同一张debug_logs表),日志汇聚后通过ServiceName区分来源:

// 各服务配置各自的标识,指向同一存储
config := &debugger.Config{
    Enabled:     true,
    ServiceName: "gateway", // 各服务分别配置: gateway / order-service / ...
    Storage:     sharedDatabaseStorage, // 各服务共享同一存储实例
}
dbg, err := debugger.New(config)
  • HTTP中间件记录与进程记录(StartProcess/NewProcessLogger)都会自动携带配置的ServiceName,默认空 = 不标识,完全向后兼容
  • Web界面的"服务筛选"下拉与GET /api/services接口可按服务区分和过滤;JSON/CSV导出同步包含service_name字段
  • 注意:共享表场景下MaxSize(按全表count删最旧)与RetentionPeriod(全表Cleanup)按全表语义生效,接入方需按汇聚后的总量配置
  • 已有存量表时,service_name列由AutoMigrate自动补充,无需手工迁移脚本

性能优化建议

生产环境配置
  1. 使用LevelInfo级别: 避免记录请求体和响应体,减少存储空间
  2. 定期清理旧日志: 设置自动清理策略
  3. 使用数据库索引: 对常用查询字段创建索引
  4. 限制日志大小: 设置单个日志文件的最大大小
清理策略示例
// 定期清理7天前的日志
func cleanupOldLogs() {
	ticker := time.NewTicker(24 * time.Hour) // 每天执行一次
	defer ticker.Stop()
	
	for range ticker.C {
		sevenDaysAgo := time.Now().AddDate(0, 0, -7)
		err := queryManager.Cleanup(sevenDaysAgo)
		if err != nil {
			log.Printf("清理旧日志失败: %v", err)
		} else {
			log.Println("旧日志清理完成")
		}
	}
}

安全考虑

敏感数据处理
  1. 避免记录敏感信息: 在生产环境中使用LevelInfo级别
  2. 加密存储: 对敏感日志内容进行加密
  3. 访问控制: 对调试接口进行身份验证
生产环境安全配置
// 生产环境配置
config := debugger.Config{
	Enabled: true,
	Level:   debugger.LevelInfo, // 不记录请求体和响应体
}

// 保护调试接口
admin := router.Group("/admin")
admin.Use(authMiddleware()) // 添加认证中间件
admin.GET("/debug/logs", debugLogsHandler)

故障排除

常见问题
  1. 内存使用过高

    • 使用文件或数据库存储器替代内存存储器
    • 设置日志数量上限
    • 定期清理旧日志
  2. 存储性能问题

    • 对数据库字段添加索引
    • 使用更快的存储介质(SSD)
    • 考虑日志分片存储
  3. 日志丢失

    • 检查存储路径权限
    • 验证数据库连接
    • 添加错误重试机制

API参考

主要结构体
LogEntry
type LogEntry struct {
	ID              string            `json:"id"`          // 日志唯一标识
	Timestamp       time.Time         `json:"timestamp"`   // 请求时间戳
	Method          string            `json:"method"`      // HTTP方法
	URL             string            `json:"url"`         // 请求URL
	StatusCode      int               `json:"status_code"` // HTTP状态码
	Duration        time.Duration     `json:"duration"`    // 处理耗时
	ClientIP        string            `json:"client_ip"`   // 客户端IP
	UserAgent       string            `json:"user_agent"`  // 用户代理
	RequestID       string            `json:"request_id"`  // 请求ID(用于追踪)
	ServiceName     string            `json:"service_name,omitempty"` // 服务标识(多服务共享存储时区分日志来源)

	// 请求信息
	RequestHeaders map[string]string `json:"request_headers"` // 请求头
	QueryParams    map[string]string `json:"query_params"`    // 查询参数
	RequestBody    string            `json:"request_body"`    // 请求体内容

	// 响应信息
	ResponseHeaders map[string]string `json:"response_headers"` // 响应头
	ResponseBody    string            `json:"response_body"`    // 响应体内容

	// 会话数据(可选)
	SessionData map[string]interface{} `json:"session_data,omitempty"` // 会话数据

	// 错误信息
	Error string `json:"error,omitempty"` // 错误信息

	// 进程记录字段(用于非HTTP进程场景)
	RecordType      string            `json:"record_type,omitempty"`    // 记录类型:"http" 或 "process"
	ProcessID       string            `json:"process_id,omitempty"`     // 进程ID
	ProcessName     string            `json:"process_name,omitempty"`   // 进程名称
	ProcessType     string            `json:"process_type,omitempty"`   // 进程类型:background/worker/cron/batch等
	Status          string            `json:"status,omitempty"`         // 进程状态:running/completed/failed
	Progress        float64           `json:"progress,omitempty"`       // 进度百分比(0-100)
	ProcessData     map[string]interface{} `json:"process_data,omitempty"` // 进程相关数据

	// 流式响应元数据
	IsStreaming     bool              `json:"is_streaming,omitempty"`    // 是否为流式请求
	StreamingStatus string            `json:"streaming_status,omitempty"` // 流式状态:started/processing/completed
	ChunkCount      int               `json:"chunk_count,omitempty"`     // 流式响应块数量
	StreamingData   map[string]interface{} `json:"streaming_data,omitempty"` // 流式响应相关数据

	// 主机信息
	Host            string            `json:"host,omitempty"`            // 请求主机信息

	// 时间信息
	EndTime         time.Time         `json:"end_time,omitempty"`        // 请求结束时间

	// Logger日志
	LoggerLogs      []LoggerLog       `json:"logger_logs,omitempty"`     // 关联的Logger日志列表

	// 派生严重度(保存时由UpdateSeverity自动统计)
	HasError        bool              `json:"has_error,omitempty"`       // 是否存在错误:含error级日志/error字段非空/状态码>=500
	ErrorCount      int               `json:"error_count,omitempty"`     // Logger日志中error级别数量
	WarnCount       int               `json:"warn_count,omitempty"`      // Logger日志中warn级别数量
}
Config
type Config struct {
	Enabled                 bool            // 是否启用调试器
	Storage                 Storage         // 存储器实例
	MaxBodySize             int64           // 最大请求/响应体大小(KB)
	RetentionPeriod         time.Duration   // 日志保留期限
	Level                   LogLevel        // 日志级别
	MaxRecords              int             // 最大记录数量
	SkipPaths               []string        // 跳过的路径
	SkipMethods             []string        // 跳过的HTTP方法
	AutoSkipStatic          *bool           // 是否自动跳过静态资源请求(*bool 三态:nil=默认开启,显式false关闭)
	StaticExtensions        []string        // 静态资源扩展名列表
	SampleRate              float64         // 采样率(0-1之间)
	Logger                  LoggerInterface // 日志记录器实例
	AllowedIPs              []string        // 调试页面/API 的 IP 白名单(鉴权走 ctx.ClientIP())
	AllowEmptyWhitelist     bool            // 白名单为空时是否仍开放,默认 false(fail-closed 不注册路由)
	UseCDN                  bool            // 仅影响日志中记录的客户端IP,不参与鉴权
	BodyMaskEnabled         *bool           // 凭据掩码开关(*bool 三态:nil=默认开启,显式false关闭)
	HeaderMaskKeys          []string        // 追加需掩码的请求/响应头键名
	BodyMaskKeys            []string        // 追加需掩码的请求/响应体字段名
	HeaderMaskKeyExclusions []string        // 排除的请求/响应头键名(从「内置+追加」并集中减去)
	BodyMaskKeyExclusions   []string        // 排除的正文/查询参数字段名(从「内置+追加」并集中减去)
	EnableStreamingSupport  bool            // 启用流式请求支持
	EnableMultipartSupport  bool            // 启用multipart请求支持
	MultipartMaxPartSize    int64           // multipart单个部分最大大小(KB)
	MultipartSkipFiles      *bool           // 文件部件是否只记元数据(*bool 三态:nil=默认只记元数据,显式false记录内容)
	MultipartPreserveState  *bool           // 是否复制请求体以保持Gin上下文(*bool 三态:nil=默认开启)
	MiddlewareOrder         string          // 中间件执行顺序:normal/early/late
	ServiceName             string          // 服务标识,多服务共享同一存储时区分日志来源,默认空 = 不标识
}
主要接口
Storage接口
type Storage interface {
	Save(entry *LogEntry) error
	FindByID(id string) (*LogEntry, error)
	FindAll(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)
	Search(keyword string, page, pageSize int) ([]*LogEntry, int, error)
	Cleanup(before time.Time) error
	GetStats() (map[string]interface{}, error)
	GetMethods() (map[string]int, error)
	GetStatusCodes() (map[int]int, error)
	GetServices() (map[string]int, error) // 服务标识统计(多服务共享存储时用于区分日志来源)
	Close() error
}
LoggerInterface接口
type LoggerInterface interface {
	// Info 记录信息级别日志
	Info(msg any, fields ...map[string]interface{})

	// Warn 记录警告级别日志
	Warn(msg any, fields ...map[string]interface{})

	// Error 记录错误级别日志
	Error(msg any, fields ...map[string]interface{})

	// WithFields 创建带有字段的日志记录器
	WithFields(fields map[string]interface{}) LoggerInterface

	// GetLevel 获取当前日志记录器的日志级别
	GetLevel() LogLevel
}
便捷构造函数
// 便捷构造函数
func NewSimpleDebugger() (*Debugger, error)                    // 创建简单调试器,使用默认内存存储(150条记录)
func NewWithMemoryStorage(maxRecords int) (*Debugger, error)   // 创建使用内存存储的调试器,指定最大记录数
func NewWithFileStorage(path string, maxRecords int) (*Debugger, error) // 创建使用文件存储的调试器,指定存储路径和最大记录数
func NewWithCustomStorage(customStorage Storage) (*Debugger, error)      // 创建使用自定义存储器的调试器
func NewProductionDebugger(storagePath string) (*Debugger, error)        // 创建生产环境调试器,使用文件存储(1000条记录)

// 存储器构造函数
func NewMemoryStorage(maxRecords int) (Storage, error)                  // 创建内存存储器
func NewFileStorage(path string, maxRecords int) (*FileStorage, error)  // 创建文件存储器
func NewDatabaseStorage(db *gorm.DB, maxSize int, tableName ...string) (*DatabaseStorage, error) // 创建数据库存储器

// DatabaseStorage 可选链式配置:裁剪等内部操作的错误经实例 logger 记录(未设置时退回标准输出)
func (ds *DatabaseStorage) SetLogger(logger LoggerInterface) *DatabaseStorage

贡献指南

欢迎提交Issue和Pull Request来改进这个组件。

许可证

MIT License

Documentation

Index

Constants

View Source
const (
	ProcessStatusCompleted = "completed" // 进程正常完成
	ProcessStatusFailed    = "failed"    // 进程执行失败
	ProcessStatusCancelled = "cancelled" // 进程被取消
)

进程状态常量定义

Variables

This section is empty.

Functions

func ContextWithLogger added in v0.15.0

func ContextWithLogger(ctx context.Context, logger LoggerInterface) context.Context

ContextWithLogger 将日志记录器注入到 context.Context 中。

注入后,下游代码可通过 LoggerFromContext 取回该日志记录器, 常用于把「请求级 logger」沿着调用链透传给 ORM、RPC 等不具备 gin.Context 的组件。

参数:

  • ctx: 父级上下文,允许为 nil(此时等价于 context.Background())
  • logger: 待注入的日志记录器;传 nil 时等价于 ContextWithoutLogger,即移除已有 logger

返回:

  • context.Context: 携带(或不携带)日志记录器的新上下文

使用示例:

ctx := debugger.ContextWithLogger(c.Request.Context(), debugger.GetLoggerFromContext(c))
db.WithContext(ctx).Find(&list)

func ContextWithoutLogger added in v0.15.0

func ContextWithoutLogger(ctx context.Context) context.Context

ContextWithoutLogger 从 context.Context 中移除日志记录器。

适用于 WebSocket 长连接、后台 goroutine 等生命周期超出单次请求的场景: 这类场景若继续复用请求级 logger,日志会持续累积到一个早已归档的请求日志中, 既无法在调试面板查看,也会造成内存增长。

参数:

  • ctx: 父级上下文,允许为 nil

返回:

  • context.Context: 不含日志记录器的新上下文;原上下文中不存在 logger 时原样返回

使用示例:

ctx = debugger.ContextWithoutLogger(ctx) // 长连接建立后调用一次

func GenerateID

func GenerateID() string

GenerateID 生成唯一请求标识 使用纳秒时间戳、进程ID和随机数确保唯一性,经过SM4加密后输出,密文结果不包含=字符 注意:Windows等平台计时器精度有限,连续调用的纳秒时间戳可能相同, 纯"时间戳+进程ID"组合在同进程内会重复(如多服务共享存储时日志互相覆盖),故追加随机数保证唯一性

func HasLoggerFromContext added in v0.15.0

func HasLoggerFromContext(ctx context.Context) bool

HasLoggerFromContext 判断 context.Context 中是否存在有效的日志记录器。

与 LoggerFromContext 的区别:后者在缺失时返回 noopLogger,无法区分「取不到」与「取到空实现」; 需要「取不到则回退兜底 logger」的场景(如 ORM 的 SQL 日志)应使用本函数判断。

参数:

  • ctx: 待判断的上下文,允许为 nil

返回:

  • bool: 存在有效日志记录器返回 true,否则返回 false

使用示例:

if debugger.HasLoggerFromContext(ctx) {
    logger = debugger.LoggerFromContext(ctx)
} else {
    logger = fallbackLogger
}

Types

type Config

type Config struct {
	Enabled         bool          `json:"enabled" default:"true" preserve:"true"` // 是否启用调试器
	MaxBodySize     int64         `json:"max_body_size" default:"1024"`           // 最大请求/响应体大小(KB),默认1MB
	RetentionPeriod time.Duration `json:"retention_period" default:"168h"`        // 日志保留期限,默认7天
	// CleanupInterval 过期日志自动清理的执行间隔,默认24小时。
	// 仅在调用方显式调用 StartPeriodicCleanup 时生效;<=0 归一化为默认值。
	CleanupInterval time.Duration `json:"cleanup_interval" default:"24h"`
	Level           LogLevel      `json:"level" default:"3"`         // 日志级别:LevelWarn
	MaxRecords      int           `json:"max_records" default:"150"` // 最大记录数量,默认150条
	// EnableCallerInfo 是否启用调用位置信息(关闭可提高高并发场景下的性能)。
	// 与 AutoSkipStatic 同理使用 *bool 三态:nil(JSON 未配置)默认开启,显式 false 生效关闭,
	// 避免 bool + default:"true" 的默认值机制把显式设置的 false 强制改回 true 导致开关失效
	EnableCallerInfo *bool `json:"enable_caller_info"` // 是否启用调用位置信息;nil默认开启,显式false生效关闭

	// 服务标识配置
	ServiceName string `json:"service_name" default:""` // 服务标识,用于多服务共享同一存储时区分日志来源,默认空 = 不标识

	// 过滤配置
	SkipPaths   []string `json:"skip_paths" default:""`          // 跳过的路径(如静态文件:"/static/,/favicon.ico")
	SkipMethods []string `json:"skip_methods" default:"OPTIONS"` // 跳过的HTTP方法
	// AutoSkipStatic 是否自动跳过静态资源请求。
	// 使用 *bool 表达三态语义:nil(JSON 未配置)默认开启;显式 false 生效关闭。
	// 不用 bool + default:"true" 的原因:CheckAndSetDefault 的布尔默认值机制会把
	// 显式设置的 false 也强制改回 true(无法区分「未配置」与「显式关闭」),导致该开关失效;
	// 也不用 preserve:"true" 的原因:preserve 会把「JSON 未配置」(零值 false)同样按显式值保留,
	// 使未写该键的下游配置默认行为从开启静默变为关闭。
	AutoSkipStatic   *bool    `json:"auto_skip_static"`
	StaticExtensions []string `` // 静态资源扩展名列表
	/* 138-byte string literal not displayed */

	// 采样配置
	SampleRate float64 `json:"sample_rate" default:"1.0"` // 采样率(0-1之间),默认记录所有请求

	// 凭据掩码配置
	// HeaderMaskKeys 追加到内置默认头名集合(authorization、cookie 等)之后参与掩码,
	// 不提供覆盖能力:默认集合按「宁可多掩」取向固化,避免下游配置写错造成明文入库
	HeaderMaskKeys []string `json:"header_mask_keys" default:""`
	// BodyMaskKeys 追加到内置默认字段名集合(password、token、sms_code 等)之后,
	// 作用于查询参数与请求/响应体
	BodyMaskKeys []string `json:"body_mask_keys" default:""`
	// BodyMaskEnabled 是否启用凭据掩码。
	// 与 AutoSkipStatic 同理使用 *bool 三态:nil(JSON 未配置)默认开启,显式 false 生效关闭;
	// 关闭会让密码、验证码、令牌原文写入存储与页面,仅建议本地一次性排查时使用
	BodyMaskEnabled *bool `json:"body_mask_enabled"`
	// HeaderMaskKeyExclusions 从「内置默认 + HeaderMaskKeys 追加」的头名并集中排除指定键,
	// 放行被误伤的字段;排除优先级最高,同一键无论来自内置还是追加均不再掩码
	HeaderMaskKeyExclusions []string `json:"header_mask_key_exclusions" default:""`
	// BodyMaskKeyExclusions 从「内置默认 + BodyMaskKeys 追加」的字段名并集中排除指定键,
	// 作用于查询参数与请求/响应体;典型场景:放行内置的 phone、session_id 等业务排查字段
	BodyMaskKeyExclusions []string `json:"body_mask_key_exclusions" default:""`

	// IP访问控制配置
	AllowedIPs []string `json:"allowed_ips" default:""` // 页面访问IP白名单(支持IP与CIDR);为空时默认不注册页面路由
	// AllowEmptyWhitelist 白名单为空时是否仍然开放调试页面(默认 false = fail-closed)。
	// 调试页会输出全量请求日志,无白名单等于把凭据交给任意访问者;需要沿用旧行为的消费方显式置 true
	AllowEmptyWhitelist bool `json:"allow_empty_whitelist" default:"false" preserve:"true"`
	UseCDN              bool `json:"use_cdn" default:"false" preserve:"true"` // 是否使用CDN,仅影响记录(entry.ClientIP)的取IP方式,不参与页面鉴权

	// 流式请求配置
	EnableStreamingSupport bool  `json:"enable_streaming_support" default:"false" preserve:"true"` // 是否启用流式请求支持
	StreamingChunkSize     int64 `json:"streaming_chunk_size" default:"1024"`                      // 流式响应分块大小(KB),默认1MB,0表示无限制
	MaxStreamingChunks     int   `json:"max_streaming_chunks" default:"10"`                        // 最大流式响应分块数量,默认10个,0表示无限制
	MaxStreamingMemory     int64 `json:"max_streaming_memory" default:"10485760"`                  // 流式响应最大内存使用量(字节),默认10MB,0表示无限制

	// Multipart请求配置
	EnableMultipartSupport bool  `json:"enable_multipart_support" default:"true" preserve:"true"` // 是否启用multipart支持
	MultipartMaxPartSize   int64 `json:"multipart_max_part_size" default:"64"`                    // multipart单个部分最大大小(KB),默认64KB
	// MultipartSkipFiles 是否跳过文件内容记录,只记录元数据(filename / Content-Type)。
	// 默认开启:上传的文件字节既不该进数据库 LONGTEXT,也不该被调试日志带走;需要内容时显式置 false。
	// 与 AutoSkipStatic 同理使用 *bool 三态:preserve 标签下的「值与默认不同即视为显式提供」
	// 会把未配置的零值 false 当成显式关闭,导致 default:"true" 永远不生效,故只能用 *bool 表达默认开启
	MultipartSkipFiles *bool `json:"multipart_skip_files"`
	// MultipartPreserveState 是否保持 Gin 上下文状态,避免破坏后续中间件与业务处理。
	// 同样必须是 *bool 三态(nil = 默认开启):开启时复制一份请求体来解析,原文通过
	// MultiReader 在读取处就回灌给后续处理链;关掉则走 MultipartReader 直接消费原始请求体,
	// 之后 gin 的 ParseMultipartForm 返回 ErrMultipartAlreadyWritten,业务侧 c.FormFile 拿不到文件。
	// 两种路径都不做事后「恢复」:回灌已在读取处完成,真被消耗掉的流也无法复原
	MultipartPreserveState *bool `json:"multipart_preserve_state"`

	// 中间件执行顺序配置
	MiddlewareOrder string `json:"middleware_order" default:"normal"` // 中间件执行顺序:normal(正常)、early(优先)、late(最后)

	// 核心组件配置 - 必须传入实例化的存储器
	Storage Storage         `json:"-"` // 存储实现(必须传入实例化的存储器)
	Logger  LoggerInterface `json:"-"` // 日志记录器(推荐直接传入实例化的日志记录器)

	// 主进程日志配置
	EnableMainLogger  bool   `json:"enable_main_logger" default:"false"`      // 是否启用主进程日志
	MainLogPath       string `json:"main_log_path" default:"./runtime/logs/"` // 主进程日志文件路径
	MainLogSplitMode  string `json:"main_log_split_mode" default:"size"`      // 日志分割模式:size(按大小)、date(按日期)
	MainLogMaxSize    int64  `json:"main_log_max_size" default:"100"`         // 日志文件最大大小(MB),按大小分割时有效
	MainLogMaxBackups int    `json:"main_log_max_backups" default:"7"`        // 最大备份文件数量
	MainLogCompress   bool   `json:"main_log_compress" default:"false"`       // 是否压缩备份日志
}

Config 调试器配置结构

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig 返回默认配置 使用helper.CheckAndSetDefault方法设置默认值,符合jcbaseGo规范

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller 调试器控制器结构

func NewController

func NewController(debugger *Debugger, router *gin.Engine, config *ControllerConfig) *Controller

NewController 创建新的调试器控制器

func (*Controller) GetBasePath

func (c *Controller) GetBasePath() string

GetBasePath 获取基础路径

func (*Controller) GetDebugger

func (c *Controller) GetDebugger() *Debugger

GetDebugger 获取调试器实例

func (*Controller) RegisterRoutes

func (c *Controller) RegisterRoutes(router *gin.Engine)

RegisterRoutes 手动注册路由到指定的Gin引擎 用于在初始化时没有传入路由组的情况

func (*Controller) SetBasePath

func (c *Controller) SetBasePath(path string)

SetBasePath 设置基础路径

type ControllerConfig

type ControllerConfig struct {
	BasePath string `json:"base_path" default:"/jcbase/debug"` // 基础路径,默认为 "/jcbase/debug"
	// UseCDN 保留字段,控制器不再读取:页面鉴权统一走 ctx.ClientIP()(尊重 gin 可信代理),
	// 记录用的 client_ip 口径由 Debugger.Config.UseCDN 决定
	UseCDN   bool   `json:"use_cdn" default:"false"`
	Title    string `json:"title" default:"调试器"`    // 页面标题,默认为 "调试器"
	PageSize int    `json:"page_size" default:"20"` // 页面大小,默认为 20
}

ControllerConfig 控制器配置

type DatabaseStorage

type DatabaseStorage struct {
	// contains filtered or unexported fields
}

DatabaseStorage 数据库存储器实现 使用GORM将调试日志保存到数据库中

func NewDatabaseStorage

func NewDatabaseStorage(db *gorm.DB, maxSize int, tableName ...string) (*DatabaseStorage, error)

NewDatabaseStorage 创建新的数据库存储器 db: GORM数据库连接 maxSize: 最大存储条目数(0表示无限制) tableName: 数据表名(可选,默认为"debug_logs")

func (*DatabaseStorage) Cleanup

func (ds *DatabaseStorage) Cleanup(before time.Time) error

Cleanup 清理过期日志

func (*DatabaseStorage) Close

func (ds *DatabaseStorage) Close() error

Close 关闭数据库存储器

func (*DatabaseStorage) CreateIndexes

func (ds *DatabaseStorage) CreateIndexes() error

CreateIndexes 创建索引(优化查询性能)

func (*DatabaseStorage) FindAll

func (ds *DatabaseStorage) FindAll(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

FindAll 查找所有日志条目,支持分页和过滤

func (*DatabaseStorage) FindByID

func (ds *DatabaseStorage) FindByID(id string) (*LogEntry, error)

FindByID 根据ID查找日志条目

func (*DatabaseStorage) GetMethods

func (ds *DatabaseStorage) GetMethods() (map[string]int, error)

GetMethods 获取所有HTTP方法统计

func (*DatabaseStorage) GetServices added in v0.16.2

func (ds *DatabaseStorage) GetServices() (map[string]int, error)

GetServices 获取服务标识统计(含空标识的条目计数,调用方可自行过滤空值)

func (*DatabaseStorage) GetStats

func (ds *DatabaseStorage) GetStats() (map[string]interface{}, error)

GetStats 获取存储统计信息

func (*DatabaseStorage) GetStatusCodes

func (ds *DatabaseStorage) GetStatusCodes() (map[int]int, error)

GetStatusCodes 获取所有状态码统计

func (*DatabaseStorage) Save

func (ds *DatabaseStorage) Save(entry *LogEntry) error

Save 保存日志条目到数据库 以主键 upsert 一次落库:HTTP 条目用新生成的 ID 插入, 进程条目以同一 ID 二次保存补全结束时间与结果,两条路径共用同一条语句, 省去原先「COUNT(*) + 存在性 SELECT + Create/Save」三次往返

func (*DatabaseStorage) Search

func (ds *DatabaseStorage) Search(keyword string, page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

Search 搜索日志内容,支持分页和过滤 在日志条目的多个字段中进行全文搜索,同时支持额外的筛选条件 该方法提供不区分大小写的搜索功能,适用于快速查找特定内容的日志记录

参数:

keyword: 搜索关键词,支持在URL、请求体、响应体、错误信息、用户代理等字段中搜索
page: 页码(从1开始)
pageSize: 每页显示数量
filters: 过滤条件映射,支持record_type、method、status_code、url、process_name、process_id等字段

返回值:

[]*LogEntry: 包含关键词且符合过滤条件的日志条目列表(按时间倒序排列)
int: 包含关键词且符合过滤条件的总条目数
error: 如果搜索过程中发生错误返回错误信息,否则返回nil

func (*DatabaseStorage) SetLogger added in v0.16.3

func (ds *DatabaseStorage) SetLogger(logger LoggerInterface) *DatabaseStorage

SetLogger 设置内部操作(上限裁剪等)的日志记录器 经 Debugger.New 创建时会自动注入实例 logger,无需手动调用; 独立创建存储器时可显式设置,未设置时错误退回标准输出。 应在并发写入开始前调用(Save 路径会并发读取该字段)

参数:

  • logger: 日志记录器实例,传 nil 恢复标准输出兜底

返回值:

  • *DatabaseStorage: 支持链式调用

异常:不触发 panic 使用示例:

store, _ := NewDatabaseStorage(db, 1000)
store.SetLogger(myLogger)

type Debugger

type Debugger struct {
	// contains filtered or unexported fields
}

Debugger 调试器主结构

func New

func New(config *Config) (*Debugger, error)

New 创建新的调试器实例 config: 调试器配置,如果没有传入存储实例,将使用默认的内存存储

func NewProductionDebugger

func NewProductionDebugger(storagePath string) (*Debugger, error)

NewProductionDebugger 创建生产环境调试器实例 使用文件存储,适合生产环境

func NewSimpleDebugger

func NewSimpleDebugger() (*Debugger, error)

NewSimpleDebugger 创建简单的调试器实例 使用默认配置,适合快速开始

func NewWithCustomStorage

func NewWithCustomStorage(customStorage Storage) (*Debugger, error)

NewWithCustomStorage 创建使用自定义存储器的调试器 适用于需要自定义存储逻辑的场景

func NewWithFileStorage

func NewWithFileStorage(storagePath string, maxRecords int) (*Debugger, error)

NewWithFileStorage 创建使用文件存储器的调试器 适用于生产环境,日志会持久化到文件系统

func NewWithMemoryStorage

func NewWithMemoryStorage(maxRecords int) (*Debugger, error)

NewWithMemoryStorage 创建使用内存存储器的调试器 适用于开发和测试环境

func (*Debugger) EndProcess added in v0.13.3

func (d *Debugger) EndProcess(processID, status string) error

EndProcess 结束进程记录 通过进程ID结束指定的进程记录,记录进程的结束时间和状态 该方法应在进程执行完成时调用,以确保记录完整的执行时间线

参数:

processID: 进程ID,由StartProcess方法返回
status: 进程结束状态,使用预定义的常量:ProcessStatusCompleted、ProcessStatusFailed、ProcessStatusCancelled

返回值:

error: 错误信息,当进程记录不存在、类型不匹配或保存失败时返回错误

示例:

err := dbg.EndProcess("process-123456", ProcessStatusCompleted)
if err != nil {
    // 处理错误
}

func (*Debugger) GetConfig

func (d *Debugger) GetConfig() *Config

GetConfig 获取配置信息

func (*Debugger) GetController

func (d *Debugger) GetController() *Controller

GetController 获取控制器实例

func (*Debugger) GetLogger

func (d *Debugger) GetLogger() LoggerInterface

GetLogger 获取调试器的日志记录器 可以在控制器中通过此方法获取Logger实例来记录日志

func (*Debugger) GetLoggerWithFields

func (d *Debugger) GetLoggerWithFields(fields map[string]interface{}) LoggerInterface

GetLoggerWithFields 获取带有指定字段的日志记录器

func (*Debugger) GetMainLogger added in v0.13.15

func (d *Debugger) GetMainLogger() LoggerInterface

GetMainLogger 获取主进程日志记录器 可以在应用程序的任何地方通过此方法获取主进程日志记录器实例

func (*Debugger) GetMainLoggerWithFields added in v0.13.15

func (d *Debugger) GetMainLoggerWithFields(fields map[string]interface{}) LoggerInterface

GetMainLoggerWithFields 获取带有指定字段的主进程日志记录器 可以在应用程序的任何地方通过此方法获取带有指定字段的主进程日志记录器实例

func (*Debugger) GetProcessLogger added in v0.13.3

func (d *Debugger) GetProcessLogger(processID string) (ProcessLoggerInterface, error)

GetProcessLogger 获取进程级日志记录器 通过进程ID获取已存在的进程记录器,用于在进程执行过程中获取记录器实例 该方法适用于需要跨函数或协程共享同一进程记录器的场景

参数:

processID: 进程ID,由StartProcess方法返回

返回值:

ProcessLoggerInterface: 进程级日志记录器实例
error: 错误信息,当进程记录不存在、类型不匹配或进程已结束时返回错误

示例:

logger, err := dbg.GetProcessLogger("process-123456")
if err != nil {
    // 处理错误
}
logger.Info("继续处理任务")

func (*Debugger) GetProcessRecords added in v0.13.3

func (d *Debugger) GetProcessRecords(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

GetProcessRecords 获取进程记录列表 支持分页和过滤查询进程记录,可用于监控和分析进程执行情况

参数:

page: 页码,从1开始
pageSize: 每页记录数
filters: 过滤条件,支持record_type/process_name/process_id等字段

返回值:

[]*LogEntry: 进程记录列表
int: 总记录数
error: 错误信息

示例:

records, total, err := dbg.GetProcessRecords(1, 20, map[string]interface{}{
    "process_name": "数据同步任务",
})

func (*Debugger) GetStorage

func (d *Debugger) GetStorage() Storage

GetStorage 获取存储实例(用于外部访问)

func (*Debugger) Middleware

func (d *Debugger) Middleware() gin.HandlerFunc

Middleware 创建Gin中间件 用于拦截HTTP请求并记录调试信息

func (*Debugger) RegisterRoutes

func (d *Debugger) RegisterRoutes(router *gin.Engine)

RegisterRoutes 手动注册路由到指定的Gin引擎 只支持 *gin.Engine 类型,使用更简洁

func (*Debugger) SetSessionData

func (d *Debugger) SetSessionData(c *gin.Context, data map[string]interface{})

SetSessionData 设置会话数据(供外部调用)

func (*Debugger) StartPeriodicCleanup added in v0.16.3

func (d *Debugger) StartPeriodicCleanup() (stop func())

StartPeriodicCleanup 启动过期日志的自动清理:先立即执行一次(覆盖长期停机造成的积压), 之后按 CleanupInterval 周期执行;返回的 stop 用于停止协程并释放定时器。

参数:无(全部取实例配置) 返回值:

  • stop: 停止清理协程的函数,可安全重复调用;未启动清理时为空操作

异常:不触发 panic;单次清理失败仅经实例 logger 记录,不影响后续周期 使用示例:

stop := dbg.StartPeriodicCleanup()
defer stop()

语义约定:RetentionPeriod <= 0 表示「调用方不希望按时间清理」,此时不启动任何协程。 过期清理的删除条件是 timestamp < now-RetentionPeriod,保留期为 0 会退化成「删除全表」, 必须显式拒绝而不是静默执行。注意 New 会经 CheckAndSetDefault 把零值 RetentionPeriod 归一化为默认 168h,所以「不清理」的权威表达是调用方不启动本方法(如业务侧 retention_days<=0 时跳过调用),本函数的判空用于防御绕过 New 直接构造的实例。 幂等:重复调用返回同一个 stop,不会启动第二个协程。

func (*Debugger) StartProcess added in v0.13.3

func (d *Debugger) StartProcess(processName, processType string) ProcessLoggerInterface

StartProcess 开始进程记录 创建一个进程级日志记录器,用于在进程中记录不同级别的debugger日志 该方法适用于后台任务、批处理作业、定时任务等非HTTP进程场景

参数:

processName: 进程名称,用于标识进程用途(如"数据同步任务")
processType: 进程类型,可选值:background/worker/cron/batch等

返回值:

ProcessLoggerInterface: 进程级日志记录器实例

示例:

logger := dbg.StartProcess("数据同步任务", "batch")
defer dbg.EndProcess(logger.GetProcessID(), "completed")

func (*Debugger) WithController

func (d *Debugger) WithController(router *gin.Engine, config *ControllerConfig) *Debugger

WithController 为调试器添加控制器支持 router: Gin引擎,用于注册调试器页面路由 config: 控制器配置(可选)

type DefaultLogger

type DefaultLogger struct {
	// contains filtered or unexported fields
}

DefaultLogger 调试器内置的日志记录器实现(默认实现) 不能直接创建DefaultLogger实例,只能通过NewDefaultLogger创建

func (*DefaultLogger) ClearLogs

func (l *DefaultLogger) ClearLogs()

ClearLogs 清空收集的日志信息

func (*DefaultLogger) Error

func (l *DefaultLogger) Error(msg any, fields ...map[string]interface{})

Error 记录错误级别日志

func (*DefaultLogger) GetLevel added in v0.13.2

func (l *DefaultLogger) GetLevel() LogLevel

GetLevel 获取当前日志记录器的日志级别

func (*DefaultLogger) GetLogs

func (l *DefaultLogger) GetLogs() []LoggerLog

GetLogs 获取收集的日志信息

func (*DefaultLogger) Info

func (l *DefaultLogger) Info(msg any, fields ...map[string]interface{})

Info 记录信息级别日志

func (*DefaultLogger) Warn

func (l *DefaultLogger) Warn(msg any, fields ...map[string]interface{})

Warn 记录警告级别日志

func (*DefaultLogger) WithFields

func (l *DefaultLogger) WithFields(fields map[string]interface{}) LoggerInterface

WithFields 创建带有字段的日志记录器

type DetailView

type DetailView struct {
	LogEntry *LogEntry `json:"log_entry"` // 原始日志条目

	// 格式化后的内容
	FormattedRequestHeaders  string `json:"formatted_request_headers"`  // 格式化请求头
	FormattedResponseHeaders string `json:"formatted_response_headers"` // 格式化响应头
	FormattedRequestBody     string `json:"formatted_request_body"`     // 格式化请求体
	FormattedResponseBody    string `json:"formatted_response_body"`    // 格式化响应体
	FormattedSessionData     string `json:"formatted_session_data"`     // 格式化会话数据
	FormattedQueryParams     string `json:"formatted_query_params"`     // 格式化查询参数

	// 进程记录专用格式化字段
	FormattedProcessInfo   string `json:"formatted_process_info"`   // 格式化进程信息
	FormattedEndTime       string `json:"formatted_end_time"`       // 格式化结束时间
	FormattedProcessStatus string `json:"formatted_process_status"` // 格式化进程状态

	// 统计信息
	RequestSize  int `json:"request_size"`  // 请求大小(字节)
	ResponseSize int `json:"response_size"` // 响应大小(字节)

	// 时间信息
	FormattedTimestamp string `json:"formatted_timestamp"` // 格式化时间戳
	FormattedDuration  string `json:"formatted_duration"`  // 格式化持续时间

	// 相关日志
	RelatedEntries []*LogEntry `json:"related_entries"` // 相关日志条目
}

DetailView 详情视图 包含日志条目的完整信息和格式化后的内容

type DetailViewer

type DetailViewer struct {
	// contains filtered or unexported fields
}

DetailViewer 日志详情查看器 提供丰富的日志详情展示功能,支持格式化显示请求和响应信息

func NewDetailViewer

func NewDetailViewer(queryManager *QueryManager) *DetailViewer

NewDetailViewer 创建新的详情查看器 queryManager: 查询管理器实例

func (*DetailViewer) CompareEntries

func (dv *DetailViewer) CompareEntries(id1, id2 string) (map[string]interface{}, error)

CompareEntries 比较两个日志条目

func (*DetailViewer) GetDetail

func (dv *DetailViewer) GetDetail(id string) (*DetailView, error)

GetDetail 获取日志详情 id: 日志条目ID

func (*DetailViewer) GetDetailHTML

func (dv *DetailViewer) GetDetailHTML(id string) (string, error)

GetDetailHTML 获取HTML格式的详情

func (*DetailViewer) GetDetailJSON

func (dv *DetailViewer) GetDetailJSON(id string) ([]byte, error)

GetDetailJSON 获取JSON格式的详情

type Fields added in v0.13.23

type Fields = map[string]interface{}

Fields 日志字段映射的便捷类型别名

type FileStorage

type FileStorage struct {
	// contains filtered or unexported fields
}

FileStorage 文件存储器实现 将调试日志保存到文件系统中

func NewFileStorage

func NewFileStorage(basePath string, maxSize int) (*FileStorage, error)

NewFileStorage 创建新的文件存储器 basePath: 文件存储的基础路径 maxSize: 最大存储条目数(0表示无限制)

func (*FileStorage) Cleanup

func (fs *FileStorage) Cleanup(before time.Time) error

Cleanup 清理过期日志

func (*FileStorage) Close

func (fs *FileStorage) Close() error

Close 关闭文件存储器(文件存储不需要特殊关闭操作)

func (*FileStorage) ExportAll

func (fs *FileStorage) ExportAll(outputPath string) error

ExportAll 导出所有日志到单个文件

func (*FileStorage) FindAll

func (fs *FileStorage) FindAll(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

FindAll 查找所有日志条目,支持分页和过滤 优化性能:实现真正的分页查询,避免全量文件读取 该方法提供统一的查询接口,适用于HTTP记录和进程记录的检索

参数:

page: 页码(从1开始)
pageSize: 每页显示数量
filters: 过滤条件映射,支持record_type、method、status_code、url、process_name、process_id等字段

返回值:

[]*LogEntry: 符合条件的日志条目列表(按时间倒序排列)
int: 符合条件的总条目数
error: 如果查询过程中发生错误返回错误信息,否则返回nil

优化逻辑:

  • 首先统计符合条件的文件总数(不读取文件内容)
  • 按文件名时间戳排序,只读取当前页需要的文件
  • 避免全量文件读取,减少I/O操作和内存占用

func (*FileStorage) FindByID

func (fs *FileStorage) FindByID(id string) (*LogEntry, error)

FindByID 根据ID查找日志条目

func (*FileStorage) GetMethods

func (fs *FileStorage) GetMethods() (map[string]int, error)

GetMethods 获取HTTP方法统计

func (*FileStorage) GetServices added in v0.16.2

func (fs *FileStorage) GetServices() (map[string]int, error)

GetServices 获取服务标识统计(含空标识的条目计数,调用方可自行过滤空值)

func (*FileStorage) GetStats

func (fs *FileStorage) GetStats() (map[string]interface{}, error)

GetStats 获取存储统计信息 计算文件存储的详细统计信息,包括存储大小、请求数量、错误率等指标 该方法提供与内存存储器相同的统计接口,确保存储组件的一致性

返回值:

map[string]interface{}: 统计信息映射,包含以下字段:
  - total_requests: 总请求数(HTTP记录和进程记录的总数)
  - storage_size: 存储大小(格式化显示,单位KB)
  - max_size: 最大存储条目数
  - storage_type: 存储类型(固定为"file")
  - storage_path: 存储路径
  - error_rate: 错误率(仅当有记录时计算)
  - error_count: 错误数量(仅当有记录时计算)
error: 如果获取统计信息失败返回错误

统计计算说明:

  • 存储大小计算采用精确算法,与内存存储器和单个条目计算逻辑保持一致
  • 统计信息包含所有有效的日志文件(HTTP记录和进程记录)
  • 跳过读取失败的文件,确保统计的准确性

func (*FileStorage) GetStatusCodes

func (fs *FileStorage) GetStatusCodes() (map[int]int, error)

GetStatusCodes 获取状态码统计

func (*FileStorage) ImportFromFile

func (fs *FileStorage) ImportFromFile(filePath string) error

ImportFromFile 从文件导入日志

func (*FileStorage) Save

func (fs *FileStorage) Save(entry *LogEntry) error

Save 保存日志条目到文件 每个日志条目保存为一个独立的JSON文件

func (*FileStorage) Search

func (fs *FileStorage) Search(keyword string, page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

Search 搜索日志内容,支持分页和过滤 优化性能:实现真正的分页搜索,避免全量文件读取 在日志条目的多个字段中进行全文搜索,支持HTTP记录和进程记录的关键词检索 该方法提供不区分大小写的搜索功能,适用于快速查找特定内容的日志记录

参数:

keyword: 搜索关键词,支持在进程名称、URL、请求体、响应体、错误信息等字段中搜索
page: 页码(从1开始)
pageSize: 每页显示数量
filters: 过滤条件映射,支持record_type、method、status_code、url、process_name、process_id等字段

返回值:

[]*LogEntry: 包含关键词且符合过滤条件的日志条目列表(按时间倒序排列)
int: 包含关键词且符合过滤条件的总条目数
error: 如果搜索过程中发生错误返回错误信息,否则返回nil

优化逻辑:

  • 首先统计符合条件的文件总数(使用快速文件头读取)
  • 按文件名时间戳排序,只读取当前页需要的文件
  • 应用额外的过滤条件
  • 避免全量文件读取,减少I/O操作和内存占用

type LogEntry

type LogEntry struct {
	ID          string        `json:"id"`                     // 日志唯一标识
	Timestamp   time.Time     `json:"timestamp"`              // 请求/进程开始时间戳
	Method      string        `json:"method"`                 // HTTP方法(HTTP记录专用)
	URL         string        `json:"url"`                    // 请求URL(HTTP记录专用)
	StatusCode  int           `json:"status_code"`            // HTTP状态码(HTTP记录专用)
	Duration    time.Duration `json:"duration"`               // 处理耗时
	ClientIP    string        `json:"client_ip"`              // 客户端IP(HTTP记录专用)
	UserAgent   string        `json:"user_agent"`             // 用户代理(HTTP记录专用)
	Host        string        `json:"host"`                   // 请求域名(HTTP记录专用)
	RequestID   string        `json:"request_id"`             // 请求ID(用于追踪)
	ServiceName string        `json:"service_name,omitempty"` // 服务标识(多服务共享存储时区分日志来源)

	// 记录类型标识
	RecordType string `json:"record_type" default:"http"` // 记录类型:http/process

	// 进程记录专用字段
	ProcessID   string    `json:"process_id,omitempty"`   // 进程唯一标识
	ProcessName string    `json:"process_name,omitempty"` // 进程名称
	ProcessType string    `json:"process_type,omitempty"` // 进程类型(background/worker/cron等)
	EndTime     time.Time `json:"end_time,omitempty"`     // 进程结束时间
	Status      string    `json:"status,omitempty"`       // 进程状态(running/completed/failed)

	// 请求信息(HTTP记录专用)
	RequestHeaders map[string]string `json:"request_headers"` // 请求头
	QueryParams    map[string]string `json:"query_params"`    // 查询参数
	RequestBody    string            `json:"request_body"`    // 请求体内容

	// 响应信息(HTTP记录专用)
	ResponseHeaders map[string]string `json:"response_headers"` // 响应头
	ResponseBody    string            `json:"response_body"`    // 响应体内容

	// 会话数据(可选)
	SessionData map[string]interface{} `json:"session_data,omitempty"` // 会话数据

	// 错误信息
	Error string `json:"error,omitempty"` // 错误信息

	// Logger日志信息(新增)
	LoggerLogs []LoggerLog `json:"logger_logs,omitempty"` // 通过logger记录的日志

	// 派生严重度(由 UpdateSeverity 统计,用于列表直观展示与过滤)
	HasError   bool `json:"has_error,omitempty"`   // 是否存在错误:含error级日志、HTTP状态码>=500或Error字段非空
	ErrorCount int  `json:"error_count,omitempty"` // LoggerLogs中error级别日志数量
	WarnCount  int  `json:"warn_count,omitempty"`  // LoggerLogs中warn级别日志数量

	// 流式响应元数据(新增)
	IsStreamingResponse bool   `json:"is_streaming_response,omitempty"` // 是否为流式响应
	StreamingChunks     int    `json:"streaming_chunks,omitempty"`      // 流式响应分块数量
	StreamingChunkSize  int    `json:"streaming_chunk_size,omitempty"`  // 流式响应分块大小限制(字节)
	MaxStreamingChunks  int    `json:"max_streaming_chunks,omitempty"`  // 流式响应最大分块数量限制
	StreamingData       string `json:"streaming_data,omitempty"`        // 流式响应数据摘要(格式化显示)

	// 存储大小(计算字段,不持久化到存储)
	StorageSize string `json:"storage_size,omitempty"` // 存储大小(格式化显示)
}

LogEntry 调试日志条目结构 用于记录单个HTTP请求或进程的完整调试信息

func (*LogEntry) CalculateStorageSize

func (e *LogEntry) CalculateStorageSize() string

CalculateStorageSize 计算日志条目的存储大小并格式化显示 计算内容包括:基本字段、请求体、响应体、请求头、响应头、查询参数、会话数据等 与总存储计算逻辑保持一致

func (*LogEntry) ComputeHasError added in v0.15.6

func (e *LogEntry) ComputeHasError() bool

ComputeHasError 实时判断日志条目是否含错误(不修改条目字段) 与 UpdateSeverity 的判定规则一致,但直接基于原始数据现算, 用于过滤历史数据(旧条目的 HasError 字段可能尚未回填)

参数: 无

返回值:

bool: 含error级日志、Error字段非空或HTTP状态码>=500时返回true

示例:

if entry.ComputeHasError() {
    // 展示错误徽标
}

func (*LogEntry) JSONString

func (e *LogEntry) JSONString() string

JSONString 返回日志条目的JSON字符串表示

func (*LogEntry) Summary

func (e *LogEntry) Summary() string

Summary 返回日志条目的摘要信息

func (*LogEntry) UpdateSeverity added in v0.15.6

func (e *LogEntry) UpdateSeverity()

UpdateSeverity 统计并更新日志条目的派生严重度字段 扫描LoggerLogs统计error/warn级别数量,并结合HTTP状态码与Error字段判定HasError 应在条目保存前调用;对历史数据也可在读取时调用补全

参数: 无

返回值: 无

判定规则:

ErrorCount: LoggerLogs中Level为error的日志数量
WarnCount:  LoggerLogs中Level为warn的日志数量
HasError:   ErrorCount>0 或 Error字段非空 或 HTTP记录StatusCode>=500

示例:

entry.LoggerLogs = logger.GetLogs()
entry.UpdateSeverity()

type LogEntryModel

type LogEntryModel struct {
	ID          string    `gorm:"column:id;type:VARCHAR(64);primaryKey" json:"id"`
	Timestamp   time.Time `gorm:"column:timestamp;type:DATETIME;index" json:"timestamp"`
	Method      string    `gorm:"column:method;type:VARCHAR(10);index" json:"method"`
	URL         string    `gorm:"column:url;type:TEXT" json:"url"`
	StatusCode  int       `gorm:"column:status_code;type:INT;index" json:"status_code"`
	Duration    int64     `gorm:"column:duration;type:BIGINT" json:"duration"` // 存储纳秒数
	ClientIP    string    `gorm:"column:client_ip;type:VARCHAR(45)" json:"client_ip"`
	UserAgent   string    `gorm:"column:user_agent;type:TEXT" json:"user_agent"`
	Host        string    `gorm:"column:host;type:VARCHAR(255);index" json:"host"`
	RequestID   string    `gorm:"column:request_id;type:VARCHAR(64);index" json:"request_id"`
	ServiceName string    `gorm:"column:service_name;type:VARCHAR(100);index" json:"service_name"` // 服务标识(多服务共享表时区分日志来源)

	// 记录类型和进程相关字段
	RecordType  string `gorm:"column:record_type;type:VARCHAR(20);index" json:"record_type"` // 记录类型:http/process
	ProcessID   string `gorm:"column:process_id;type:VARCHAR(64);index" json:"process_id"`   // 进程唯一标识
	ProcessName string `gorm:"column:process_name;type:VARCHAR(255)" json:"process_name"`    // 进程名称
	ProcessType string `gorm:"column:process_type;type:VARCHAR(50)" json:"process_type"`     // 进程类型
	// EndTime 进程结束时间:指针语义(nil 落库 NULL)——HTTP 条目无结束时间,进程进行中同样为 NULL;
	// 非指针 time.Time 的 Go 零值会写出 '0000-00-00',被 MySQL 8 严格模式(NO_ZERO_DATE)拒绝(Error 1292)
	EndTime *time.Time `gorm:"column:end_time;type:DATETIME" json:"end_time,omitempty"`
	Status  string     `gorm:"column:status;type:VARCHAR(20);index" json:"status"` // 进程状态

	// JSON格式存储的字段
	RequestHeaders  string `gorm:"column:request_headers;type:JSON" json:"request_headers"`
	QueryParams     string `gorm:"column:query_params;type:JSON" json:"query_params"`
	RequestBody     string `gorm:"column:request_body;type:LONGTEXT" json:"request_body"`
	ResponseHeaders string `gorm:"column:response_headers;type:JSON" json:"response_headers"`
	ResponseBody    string `gorm:"column:response_body;type:LONGTEXT" json:"response_body"`
	SessionData     string `gorm:"column:session_data;type:JSON" json:"session_data"`
	Error           string `gorm:"column:error;type:TEXT" json:"error"`

	// 索引字段
	URLHash string `gorm:"column:url_hash;type:VARCHAR(32);index" json:"url_hash"` // URL的MD5哈希,用于快速搜索

	// 流式响应相关字段
	IsStreamingResponse bool   `gorm:"column:is_streaming_response;type:BOOLEAN;index" json:"is_streaming_response"` // 是否为流式响应
	StreamingChunks     int    `gorm:"column:streaming_chunks;type:INT" json:"streaming_chunks"`                     // 流式响应分块数量
	StreamingChunkSize  int    `gorm:"column:streaming_chunk_size;type:INT" json:"streaming_chunk_size"`             // 流式响应分块大小限制(字节)
	MaxStreamingChunks  int    `gorm:"column:max_streaming_chunks;type:INT" json:"max_streaming_chunks"`             // 流式响应最大分块数量限制
	StreamingData       string `gorm:"column:streaming_data;type:TEXT" json:"streaming_data"`                        // 流式响应数据摘要(格式化显示)

	// Logger日志字段(JSON格式存储)
	LoggerLogs string `gorm:"column:logger_logs;type:JSON" json:"logger_logs"` // 通过logger记录的日志(JSON格式)

	// 派生严重度字段(由 UpdateSeverity 统计,用于列表直观展示与过滤)
	HasError   bool `gorm:"column:has_error;type:BOOLEAN;index" json:"has_error"` // 是否存在错误
	ErrorCount int  `gorm:"column:error_count;type:INT" json:"error_count"`       // error级别日志数量
	WarnCount  int  `gorm:"column:warn_count;type:INT" json:"warn_count"`         // warn级别日志数量
}

LogEntryModel 数据库模型结构 对应数据库中的日志条目表,支持HTTP记录和进程记录

func (LogEntryModel) TableName

func (LogEntryModel) TableName() string

TableName 实现自定义表名

type LogLevel added in v0.13.8

type LogLevel int
const (
	LevelSilent LogLevel = iota + 1 // 静默级别:不记录任何日志
	LevelError                      // 错误级别:只记录错误信息
	LevelWarn                       // 警告级别:记录错误+警告信息
	LevelInfo                       // 信息级别:记录所有详细信息
)

日志级别常量

func (LogLevel) String added in v0.13.8

func (l LogLevel) String() string

String 返回日志级别的字符串表示

type LoggerInterface

type LoggerInterface interface {
	// Info 记录信息级别日志
	Info(msg any, fields ...map[string]interface{})

	// Warn 记录警告级别日志
	Warn(msg any, fields ...map[string]interface{})

	// Error 记录错误级别日志
	Error(msg any, fields ...map[string]interface{})

	// WithFields 创建带有字段的日志记录器
	WithFields(fields map[string]interface{}) LoggerInterface

	// GetLevel 获取当前日志记录器的日志级别
	GetLevel() LogLevel

	// GetLogs 获取收集的日志信息
	GetLogs() []LoggerLog

	// ClearLogs 清空收集的日志信息
	ClearLogs()
}

LoggerInterface 日志记录器接口 支持不同级别的日志记录,可以在控制器中直接使用

func GetLoggerFromContext

func GetLoggerFromContext(c *gin.Context) LoggerInterface

GetLoggerFromContext 从Gin上下文中获取Logger实例 控制器可以通过此函数获取Logger来记录日志

func LoggerFromContext added in v0.15.0

func LoggerFromContext(ctx context.Context) LoggerInterface

LoggerFromContext 从 context.Context 中获取日志记录器。

参数:

  • ctx: 待读取的上下文,允许为 nil

返回:

  • LoggerInterface: 上下文中携带的日志记录器;不存在或已被移除时返回 noopLogger(空操作实现,可安全调用)

使用示例:

logger := debugger.LoggerFromContext(ctx)
logger.Info("执行完成", map[string]interface{}{"cost": 12})

func NewDefaultLogger added in v0.13.7

func NewDefaultLogger(debugger *Debugger) LoggerInterface

NewDefaultLogger 创建默认日志记录器实例

func NewMainLogger added in v0.13.15

func NewMainLogger(debugger *Debugger) LoggerInterface

NewMainLogger 创建新的主进程日志记录器 该方法会创建主进程日志记录器,适用于需要持久化保存的应用程序级日志 支持按日期或大小分割日志文件

参数:

debugger: 调试器实例,用于配置管理

返回值:

LoggerInterface: 主进程日志记录器实例

示例:

mainLogger := NewMainLogger(dbg)
mainLogger.Info("应用程序启动")

func NoopLogger added in v0.15.0

func NoopLogger() LoggerInterface

NoopLogger 返回一个空操作日志记录器实例。

适用于「日志目标可选」的场景:调用方允许传入 nil 表示不记录日志时, 用本函数的返回值占位,可避免下游出现 nil 接口调用 panic。

返回:

  • LoggerInterface: 所有方法均为空实现的日志记录器

使用示例:

if fallback == nil {
    fallback = debugger.NoopLogger()
}

type LoggerLog

type LoggerLog struct {
	Timestamp time.Time              `json:"timestamp"` // 日志时间戳
	Level     LogLevel               `json:"level"`     // 日志级别:silent/error/warn/info
	Message   string                 `json:"message"`   // 日志消息
	Fields    map[string]interface{} `json:"fields"`    // 日志附加字段

	// 位置信息字段(新增)
	FileName string `json:"file_name,omitempty"` // 文件名
	Line     int    `json:"line,omitempty"`      // 行号
	Function string `json:"function,omitempty"`  // 函数名
}

LoggerLog 记录通过logger打印的日志信息

type MainLogger added in v0.13.15

type MainLogger struct {
	// contains filtered or unexported fields
}

func (*MainLogger) ClearLogs added in v0.13.19

func (l *MainLogger) ClearLogs()

ClearLogs 清空收集的日志信息 MainLogger不支持此操作,为空操作

func (*MainLogger) Error added in v0.13.15

func (l *MainLogger) Error(msg any, fields ...map[string]interface{})

Error 记录错误级别日志

func (*MainLogger) GetLevel added in v0.13.15

func (l *MainLogger) GetLevel() LogLevel

GetLevel 获取当前日志记录器的日志级别

func (*MainLogger) GetLogs added in v0.13.19

func (l *MainLogger) GetLogs() []LoggerLog

GetLogs 获取收集的日志信息 MainLogger不支持此操作,返回空切片

func (*MainLogger) Info added in v0.13.15

func (l *MainLogger) Info(msg any, fields ...map[string]interface{})

Info 记录信息级别日志

func (*MainLogger) Warn added in v0.13.15

func (l *MainLogger) Warn(msg any, fields ...map[string]interface{})

Warn 记录警告级别日志

func (*MainLogger) WithFields added in v0.13.15

func (l *MainLogger) WithFields(fields map[string]interface{}) LoggerInterface

WithFields 创建带有字段的日志记录器

type MemoryStorage

type MemoryStorage struct {
	// contains filtered or unexported fields
}

MemoryStorage 内存存储器实现 将调试日志保存在内存中,适合开发环境使用

func NewMemoryStorage

func NewMemoryStorage(maxSize ...int) (*MemoryStorage, error)

NewMemoryStorage 创建新的内存存储器 maxSize: 最大存储条目数(0表示无限制)

func (*MemoryStorage) Cleanup

func (ms *MemoryStorage) Cleanup(before time.Time) error

Cleanup 清理过期日志

func (*MemoryStorage) Clear

func (ms *MemoryStorage) Clear() error

Clear 清空所有日志条目

func (*MemoryStorage) Close

func (ms *MemoryStorage) Close() error

Close 关闭内存存储器

func (*MemoryStorage) ExportAll

func (ms *MemoryStorage) ExportAll() ([]*LogEntry, error)

ExportAll 导出所有日志到内存(返回副本)

func (*MemoryStorage) FindAll

func (ms *MemoryStorage) FindAll(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

FindAll 查找所有日志条目,支持分页和过滤 优化性能:实现真正的分页查询,避免全量数据遍历 优化并发:减少锁持有时间,提高并发性能 该方法提供统一的查询接口,适用于HTTP记录和进程记录的检索

参数:

page: 页码(从1开始)
pageSize: 每页显示数量
filters: 过滤条件映射,支持record_type、method、status_code、url、process_name、process_id等字段

返回值:

[]*LogEntry: 符合条件的日志条目列表(按时间倒序排列)
int: 符合条件的总条目数
error: 如果查询过程中发生错误返回错误信息,否则返回nil

优化逻辑:

  • 首先收集所有有效的日志条目(非nil)
  • 计算符合条件的总条目数
  • 按时间倒序排序后,只返回当前页需要的数据
  • 支持空过滤条件,返回分页数据
  • 减少锁持有时间,提高并发性能

func (*MemoryStorage) FindByID

func (ms *MemoryStorage) FindByID(id string) (*LogEntry, error)

FindByID 根据ID查找日志条目

func (*MemoryStorage) GetByTimeRange

func (ms *MemoryStorage) GetByTimeRange(startTime, endTime time.Time) ([]*LogEntry, error)

GetByTimeRange 根据时间范围获取日志条目

func (*MemoryStorage) GetMethods

func (ms *MemoryStorage) GetMethods() (map[string]int, error)

GetMethods 获取所有HTTP方法统计

func (*MemoryStorage) GetRecent

func (ms *MemoryStorage) GetRecent(count int) ([]*LogEntry, error)

GetRecent 获取最近的日志条目

func (*MemoryStorage) GetServices added in v0.16.2

func (ms *MemoryStorage) GetServices() (map[string]int, error)

GetServices 获取服务标识统计(含空标识的条目计数,调用方可自行过滤空值)

func (*MemoryStorage) GetStats

func (ms *MemoryStorage) GetStats() (map[string]interface{}, error)

GetStats 获取存储统计信息

func (*MemoryStorage) GetStatusCodes

func (ms *MemoryStorage) GetStatusCodes() (map[int]int, error)

GetStatusCodes 获取所有状态码统计

func (*MemoryStorage) ImportEntries

func (ms *MemoryStorage) ImportEntries(entries []*LogEntry) error

ImportEntries 导入日志条目

func (*MemoryStorage) Save

func (ms *MemoryStorage) Save(entry *LogEntry) error

Save 保存日志条目到内存 将HTTP记录或进程记录保存到内存存储中,支持自动清理和更新机制 该方法确保存储的线程安全性,并维护ID索引以提高查询性能

参数:

entry: 要保存的日志条目,包含HTTP记录或进程记录的完整信息

返回值:

error: 如果保存过程中发生错误返回错误信息,否则返回nil

保存逻辑:

  • 如果条目ID已存在,则更新现有条目(支持进程记录的动态更新)
  • 使用环形缓冲区存储条目,当超过最大存储限制时,自动覆盖最旧的条目(FIFO策略)
  • 维护ID到索引的映射,提高FindByID等操作的性能
  • 使用读写锁确保多线程环境下的数据一致性
  • 时间复杂度O(1),避免了重建索引的开销

func (*MemoryStorage) Search

func (ms *MemoryStorage) Search(keyword string, page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

Search 搜索日志内容,支持分页和过滤 优化性能:实现真正的分页搜索,避免全量数据遍历 优化并发:减少锁持有时间,提高并发性能 在日志条目的多个字段中进行全文搜索,支持HTTP记录和进程记录的关键词检索 该方法提供不区分大小写的搜索功能,适用于快速查找特定内容的日志记录

参数:

keyword: 搜索关键词,支持在进程名称、URL、请求体、响应体、错误信息等字段中搜索
page: 页码(从1开始)
pageSize: 每页显示数量
filters: 过滤条件映射,支持record_type、method、status_code、url、process_name、process_id等字段

返回值:

[]*LogEntry: 包含关键词且符合过滤条件的日志条目列表(按时间倒序排列)
int: 包含关键词且符合过滤条件的总条目数
error: 如果搜索过程中发生错误返回错误信息,否则返回nil

优化逻辑:

  • 首先收集所有有效的日志条目(非nil)
  • 搜索符合条件的条目
  • 应用额外的过滤条件
  • 按时间倒序排序后,只返回当前页需要的数据
  • 减少锁持有时间,提高并发性能

搜索范围:

  • 进程名称(process_name)
  • URL路径(url)
  • 请求体(request_body)
  • 响应体(response_body)
  • 错误信息(error)
  • 请求头(request_headers)的所有值
  • 响应头(response_headers)的所有值

type Pagination

type Pagination struct {
	Page       int  // 当前页码
	PageSize   int  // 每页大小
	Total      int  // 总记录数
	TotalPages int  // 总页数
	HasPrev    bool // 是否有上一页
	HasNext    bool // 是否有下一页
	PrevPage   int  // 上一页页码
	NextPage   int  // 下一页页码
}

Pagination 分页信息

type ProcessLogger added in v0.13.3

type ProcessLogger struct {
	// contains filtered or unexported fields
}

ProcessLogger 进程级日志记录器 用于在进程中记录不同级别的debugger日志,所有日志属于同一条进程记录 该记录器适用于后台任务、批处理作业、定时任务等非HTTP进程场景

func NewProcessLogger added in v0.13.3

func NewProcessLogger(debugger *Debugger, processName, processType string) *ProcessLogger

NewProcessLogger 创建新的进程级日志记录器 该方法会创建进程记录并初始化进程级日志记录器,适用于需要监控的非HTTP进程

参数:

debugger: 调试器实例,用于存储和配置管理
processName: 进程名称,用于标识进程用途(如"数据同步任务")
processType: 进程类型,可选值:background/worker/cron/batch等

返回值:

*ProcessLogger: 进程级日志记录器实例

示例:

logger := NewProcessLogger(dbg, "数据同步任务", "batch")
defer logger.EndProcess("completed")

func (*ProcessLogger) ClearLogs added in v0.13.19

func (p *ProcessLogger) ClearLogs()

ClearLogs 清空收集的日志信息 委托给内部DefaultLogger实现

func (*ProcessLogger) EndProcess added in v0.13.3

func (p *ProcessLogger) EndProcess(status string) error

EndProcess 结束进程记录 结束当前进程记录,记录进程的结束时间、状态和所有收集的日志 该方法应在进程执行完成时调用,以确保记录完整的执行时间线

参数:

status: 进程结束状态,使用预定义的常量:ProcessStatusCompleted、ProcessStatusFailed、ProcessStatusCancelled

返回值:

error: 错误信息,当进程记录不存在或保存失败时返回错误

示例:

err := logger.EndProcess(ProcessStatusCompleted)
if err != nil {
    // 处理错误
}

func (*ProcessLogger) Error added in v0.13.3

func (p *ProcessLogger) Error(msg any, fields ...map[string]interface{})

Error 记录错误级别日志 记录进程执行过程中发生的错误信息

参数:

msg: 日志消息,可以是字符串、结构体或实现了Stringer接口的类型
fields: 可选的附加字段,用于记录错误相关的详细信息

示例:

logger.Error("数据库连接失败", map[string]interface{}{"error": err.Error()})

func (*ProcessLogger) GetLevel added in v0.13.3

func (p *ProcessLogger) GetLevel() LogLevel

GetLevel 获取当前日志记录器的日志级别 返回当前调试器配置的日志级别

返回值:

LogLevel: 日志级别(LevelInfo/LevelWarn/LevelError/LevelSilent)

func (*ProcessLogger) GetLogs added in v0.13.19

func (p *ProcessLogger) GetLogs() []LoggerLog

GetLogs 获取收集的日志信息 委托给内部DefaultLogger实现

返回值:

[]LoggerLog: 日志条目切片

func (*ProcessLogger) GetProcessID added in v0.13.3

func (p *ProcessLogger) GetProcessID() string

GetProcessID 获取进程ID 返回当前进程的唯一标识符,可用于后续查询和监控

返回值:

string: 进程ID

示例:

processID := logger.GetProcessID()

func (*ProcessLogger) GetProcessName added in v0.13.3

func (p *ProcessLogger) GetProcessName() string

GetProcessName 获取进程名称 返回当前进程的名称,用于标识进程用途

返回值:

string: 进程名称

func (*ProcessLogger) GetProcessType added in v0.13.3

func (p *ProcessLogger) GetProcessType() string

GetProcessType 获取进程类型 返回当前进程的类型,如background/worker/cron等

返回值:

string: 进程类型

func (*ProcessLogger) GetStartTime added in v0.13.23

func (p *ProcessLogger) GetStartTime() time.Time

GetStartTime 获取进程开始时间 返回进程记录器创建时的时间戳,用于计算进程执行耗时

返回值:

time.Time: 进程开始时间

func (*ProcessLogger) Info added in v0.13.3

func (p *ProcessLogger) Info(msg any, fields ...map[string]interface{})

Info 记录信息级别日志 记录进程执行的关键信息,适用于监控和状态跟踪

参数:

msg: 日志消息,可以是字符串、结构体或实现了Stringer接口的类型
fields: 可选的附加字段,用于记录额外的状态信息

示例:

logger.Info("数据同步完成", map[string]interface{}{"processed": 1000})

func (*ProcessLogger) SetProcessInfo added in v0.13.3

func (p *ProcessLogger) SetProcessInfo(info map[string]interface{})

SetProcessInfo 设置进程信息 动态更新进程的附加信息,适用于进程执行过程中需要记录额外上下文信息的场景

参数:

info: 进程信息映射,可以包含任意键值对

示例:

logger.SetProcessInfo(map[string]interface{}{"progress": "50%", "current_file": "data.csv"})

func (*ProcessLogger) Warn added in v0.13.3

func (p *ProcessLogger) Warn(msg any, fields ...map[string]interface{})

Warn 记录警告级别日志 记录可能影响进程正常执行的警告信息

参数:

msg: 日志消息,可以是字符串、结构体或实现了Stringer接口的类型
fields: 可选的附加字段,用于记录警告相关的上下文信息

示例:

logger.Warn("磁盘空间不足", map[string]interface{}{"available": "1GB"})

func (*ProcessLogger) WithFields added in v0.13.3

func (p *ProcessLogger) WithFields(fields map[string]interface{}) LoggerInterface

WithFields 创建带有字段的日志记录器 创建一个新的日志记录器实例,继承当前记录器的所有字段并添加新字段

参数:

fields: 要添加的字段映射

返回值:

LoggerInterface: 新的日志记录器实例

示例:

subLogger := logger.WithFields(map[string]interface{}{"module": "data_processor"})

type ProcessLoggerInterface added in v0.13.3

type ProcessLoggerInterface interface {
	LoggerInterface // 继承基础日志接口

	// GetProcessID 获取进程ID
	GetProcessID() string

	// GetProcessName 获取进程名称
	GetProcessName() string

	// GetProcessType 获取进程类型
	GetProcessType() string

	// GetStartTime 获取进程开始时间
	GetStartTime() time.Time

	// SetProcessInfo 设置进程信息
	SetProcessInfo(info map[string]interface{})

	// EndProcess 结束进程记录
	EndProcess(status string) error
}

ProcessLoggerInterface 进程级日志记录器接口 提供进程级日志记录功能,继承基础日志接口并添加进程管理方法

type QueryManager

type QueryManager struct {
	// contains filtered or unexported fields
}

QueryManager 日志查询管理器 提供丰富的查询和过滤功能,支持多种查询条件组合

func NewQueryManager

func NewQueryManager(storage Storage) *QueryManager

NewQueryManager 创建新的查询管理器 storage: 存储接口实例

func (*QueryManager) Cleanup

func (qm *QueryManager) Cleanup(before time.Time) error

Cleanup 清理过期日志 before: 清理此时间之前的日志

func (*QueryManager) Export

func (qm *QueryManager) Export(format string, options QueryOptions) ([]byte, error)

Export 导出日志数据 format: 导出格式(json, csv等)

func (*QueryManager) GetActiveStreamingRequests added in v0.13.5

func (qm *QueryManager) GetActiveStreamingRequests(page, pageSize int) (*QueryResult, error)

GetActiveStreamingRequests 获取活跃的流式请求日志

func (*QueryManager) GetByID

func (qm *QueryManager) GetByID(id string) (*LogEntry, error)

GetByID 根据ID获取日志条目

func (*QueryManager) GetByIsStreaming added in v0.13.5

func (qm *QueryManager) GetByIsStreaming(isStreaming bool, page, pageSize int) (*QueryResult, error)

GetByIsStreaming 根据流式请求状态查询日志 isStreaming: 是否为流式请求(true/false)

func (*QueryManager) GetByMethod

func (qm *QueryManager) GetByMethod(method string, page, pageSize int) (*QueryResult, error)

GetByMethod 根据HTTP方法查询日志

func (*QueryManager) GetByStatusCode

func (qm *QueryManager) GetByStatusCode(statusCode int, page, pageSize int) (*QueryResult, error)

GetByStatusCode 根据状态码查询日志

func (*QueryManager) GetByStreamingStatus added in v0.13.5

func (qm *QueryManager) GetByStreamingStatus(streamingStatus string, page, pageSize int) (*QueryResult, error)

GetByStreamingStatus 根据流式请求活跃状态查询日志 streamingStatus: 流式请求状态("active" - 活跃, "inactive" - 非活跃)

func (*QueryManager) GetByTimeRange

func (qm *QueryManager) GetByTimeRange(startTime, endTime time.Time, page, pageSize int) (*QueryResult, error)

GetByTimeRange 根据时间范围查询日志 startTime: 开始时间 endTime: 结束时间

func (*QueryManager) GetByURL

func (qm *QueryManager) GetByURL(urlPattern string, page, pageSize int) (*QueryResult, error)

GetByURL 根据URL查询日志(模糊匹配)

func (*QueryManager) GetErrors

func (qm *QueryManager) GetErrors(page, pageSize int) (*QueryResult, error)

GetErrors 获取包含错误的日志

func (*QueryManager) GetFilterOptions

func (qm *QueryManager) GetFilterOptions() map[string]interface{}

GetFilterOptions 获取可用的过滤选项

func (*QueryManager) GetInactiveStreamingRequests added in v0.13.5

func (qm *QueryManager) GetInactiveStreamingRequests(page, pageSize int) (*QueryResult, error)

GetInactiveStreamingRequests 获取非活跃的流式请求日志

func (*QueryManager) GetNonStreamingRequests added in v0.13.5

func (qm *QueryManager) GetNonStreamingRequests(page, pageSize int) (*QueryResult, error)

GetNonStreamingRequests 获取非流式请求日志

func (*QueryManager) GetRecent

func (qm *QueryManager) GetRecent(limit int) ([]*LogEntry, error)

GetRecent 获取最近的日志条目 limit: 限制返回的条目数量

func (*QueryManager) GetSlowRequests

func (qm *QueryManager) GetSlowRequests(threshold time.Duration, page, pageSize int) (*QueryResult, error)

GetSlowRequests 获取慢请求日志 threshold: 慢请求阈值

func (*QueryManager) GetStats

func (qm *QueryManager) GetStats() (map[string]interface{}, error)

GetStats 获取统计信息

func (*QueryManager) GetStreamingRequests added in v0.13.5

func (qm *QueryManager) GetStreamingRequests(page, pageSize int) (*QueryResult, error)

GetStreamingRequests 获取流式请求日志

func (*QueryManager) Query

func (qm *QueryManager) Query(options QueryOptions) (*QueryResult, error)

Query 执行查询 根据查询选项获取日志条目

func (*QueryManager) Search

func (qm *QueryManager) Search(keyword string, page, pageSize int, filters map[string]interface{}) (*QueryResult, error)

Search 执行搜索 根据关键词搜索日志内容,支持筛选条件

type QueryOptions

type QueryOptions struct {
	Page      int                    `json:"page"`       // 页码,从1开始
	PageSize  int                    `json:"page_size"`  // 每页大小
	Filters   map[string]interface{} `json:"filters"`    // 过滤条件
	SortBy    string                 `json:"sort_by"`    // 排序字段
	SortOrder string                 `json:"sort_order"` // 排序方向:asc/desc
}

QueryOptions 查询选项 定义查询的各种过滤条件和分页参数

type QueryResult

type QueryResult struct {
	Entries    []*LogEntry `json:"entries"`     // 日志条目列表
	Total      int         `json:"total"`       // 总记录数
	Page       int         `json:"page"`        // 当前页码
	PageSize   int         `json:"page_size"`   // 每页大小
	TotalPages int         `json:"total_pages"` // 总页数
}

QueryResult 查询结果 包含查询到的日志条目和分页信息

type Storage

type Storage interface {
	// Save 保存日志条目
	Save(entry *LogEntry) error

	// FindByID 根据ID查找日志条目
	FindByID(id string) (*LogEntry, error)

	// FindAll 查找所有日志条目,支持分页和过滤
	FindAll(page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

	// Search 搜索日志内容,支持分页和过滤
	Search(keyword string, page, pageSize int, filters map[string]interface{}) ([]*LogEntry, int, error)

	// Cleanup 清理过期日志
	Cleanup(before time.Time) error

	// GetStats 获取统计信息
	GetStats() (map[string]interface{}, error)

	// GetMethods 获取HTTP方法统计
	GetMethods() (map[string]int, error)

	// GetStatusCodes 获取状态码统计
	GetStatusCodes() (map[int]int, error)

	// GetServices 获取服务标识统计(多服务共享存储时用于区分日志来源)
	GetServices() (map[string]int, error)

	// Close 关闭存储
	Close() error
}

Storage 存储接口定义 支持多种存储方式:文件、内存、数据库

type StreamingChunk added in v0.13.5

type StreamingChunk struct {
	Timestamp time.Time `json:"timestamp"` // 分块接收时间
	Size      int       `json:"size"`      // 分块大小
	Data      string    `json:"data"`      // 分块数据(截断后)
	IsBinary  bool      `json:"is_binary"` // 是否为二进制数据
}

StreamingChunk 流式响应分块记录 用于记录流式响应的分块数据,避免内存溢出

type TemplateData

type TemplateData struct {
	Title      string
	BasePath   string
	Entries    []*LogEntry
	Entry      *LogEntry
	Pagination *Pagination
	Filters    map[string]string
	Keyword    string
	Stats      map[string]interface{}
}

TemplateData 模板数据

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL