编辑“︁Gin日志系统详解”︁（章节）

= Gin日志系统详解 =

== 介绍 ==  
Gin是一个高性能的Go语言Web框架，其内置的日志系统帮助开发者记录HTTP请求、错误信息和其他运行时数据。日志是应用程序可观测性的核心组成部分，用于调试、监控和审计。本章将深入讲解Gin的日志系统，包括默认日志配置、自定义日志中间件、日志格式化和第三方日志库集成。

== 默认日志中间件 ==  
Gin默认使用`Logger()`中间件记录HTTP请求的基本信息，如请求方法、路径、响应状态和耗时。以下是一个简单示例：  

<syntaxhighlight lang="go">
package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default() // 默认包含Logger和Recovery中间件
    r.GET("/ping", func(c *gin.Context) {
        c.String(200, "pong")
    })
    r.Run(":8080")
}
</syntaxhighlight>

**输出示例**：  
<pre>
[GIN] 2024/01/01 - 12:00:00 | 200 |     1.2ms |        ::1 | GET     "/ping"
</pre>

字段说明：  
* `200`：HTTP状态码  
* `1.2ms`：请求处理耗时  
* `::1`：客户端IP  
* `GET "/ping"`：请求方法和路径  

== 自定义日志格式 ==  
通过`gin.LoggerWithFormatter`可自定义日志格式。例如，添加请求ID和用户代理：  

<syntaxhighlight lang="go">
r := gin.New()
r.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    return fmt.Sprintf("[%s] %s | %d | %s | %s | %s\n",
        param.ClientIP,
        param.TimeStamp.Format(time.RFC1123),
        param.StatusCode,
        param.Latency,
        param.Request.UserAgent(),
        param.Path,
    )
}))
</syntaxhighlight>

**输出示例**：  
<pre>
[::1] Mon, 01 Jan 2024 12:00:00 UTC | 200 | 1.2ms | Mozilla/5.0 | /ping
</pre>

== 日志级别与输出控制 ==  
Gin支持通过环境变量`GIN_MODE`控制日志级别：  
* `debug`：输出彩色详细日志（默认）  
* `release`：禁用调试日志  

<syntaxhighlight lang="bash">
export GIN_MODE=release
</syntaxhighlight>

== 第三方日志库集成 ==  
Gin可与流行的日志库（如Zap、Logrus）集成。以下是使用Zap的示例：  

<syntaxhighlight lang="go">
import (
    "go.uber.org/zap"
    "github.com/gin-gonic/gin"
)

func main() {
    logger, _ := zap.NewProduction()
    r := gin.New()
    r.Use(func(c *gin.Context) {
        logger.Info("Request",
            zap.String("path", c.Request.URL.Path),
            zap.String("method", c.Request.Method),
        )
        c.Next()
    })
    r.GET("/health", func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "ok"})
    })
    r.Run(":8080")
}
</syntaxhighlight>

**输出示例**：  
<pre>
{"level":"info","ts":1672531200,"msg":"Request","path":"/health","method":"GET"}
</pre>

== 日志文件与轮转 ==  
使用`lumberjack`实现日志文件轮转：  

<syntaxhighlight lang="go">
import "gopkg.in/natefinch/lumberjack.v2"

func setupLogging() {
    logFile := &lumberjack.Logger{
        Filename:   "gin.log",
        MaxSize:    100, // MB
        MaxBackups: 3,
    }
    gin.DefaultWriter = io.MultiWriter(logFile, os.Stdout)
}
</syntaxhighlight>

== 实际案例：错误日志收集 ==  
在微服务架构中，通常需要集中收集错误日志。以下示例将错误日志发送至Sentry：  

<syntaxhighlight lang="go">
import (
    "github.com/getsentry/sentry-go"
    sentrygin "github.com/getsentry/sentry-go/gin"
)

func main() {
    _ = sentry.Init(sentry.ClientOptions{Dsn: "YOUR_DSN"})
    r := gin.Default()
    r.Use(sentrygin.New(sentrygin.Options{}))
    r.GET("/fail", func(c *gin.Context) {
        panic("模拟错误")
    })
    r.Run(":8080")
}
</syntaxhighlight>

== 性能考虑 ==  
日志操作可能影响性能，建议：  
1. 在生产环境使用异步日志（如通过Zap的`zapcore.AddSync`）  
2. 避免在高频请求中记录完整请求体  
3. 使用采样率控制日志量  

=== 数学表达 ===  
日志采样率公式（当采样率为<math>p</math>时）：  
<math>
P(\text{记录}) = \begin{cases} 
p & \text{如果 } \text{rand}() < p \\
0 & \text{否则}
\end{cases}
</math>

== 总结 ==  
Gin的日志系统提供了灵活的配置选项，从简单的请求记录到企业级日志聚合均可支持。开发者应根据实际需求选择适当的日志策略，平衡可观测性与性能。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin日志与监控]]