Pin

外观

日志 ​

Pin 基于 Laravel 日志体系扩展，提供统一的结构化日志支持。

日志通道 ​

Pin 默认提供结构化 JSON 单文件日志通道。

通道说明
app应用日志、异常日志以及框架运行日志
apiAPI 请求日志
sqlSQL 执行日志

通道配置 ​

Pin 提供 Pin\Log\Config 用于创建日志通道配置。

单文件通道 ​

Config::single() 创建单文件日志通道：

php
use Pin\Log\Config;

'app' => Config::single('app'),

默认根据通道名称生成日志文件：

text
storage/logs/{name}.log

例如：

php
Config::single('app')

对应：

text
storage/logs/app.log

按天滚动通道 ​

Config::daily() 创建按天滚动日志通道：

php
Config::daily('app')

默认保留最近 14 天日志：

php
[
    'driver' => 'daily',
    'days' => 14,
]

可以通过参数覆盖默认配置：

php
Config::daily('app', [
    'days' => 30,
]);

环境隔离 ​

testing 环境使用独立日志目录，避免测试日志与其他环境日志混合：

text
storage/testing-logs/{name}.log

日志级别 ​

日志级别默认为 debug，可通过环境变量配置：

ini
LOG_{NAME}_LEVEL

例如：

ini
LOG_APP_LEVEL=warning

对应：

php
Config::single('app')

仅记录 warning 及以上级别日志。

日志格式 ​

Pin 默认使用 JSON 格式输出日志，主要包含以下字段：

字段说明
datetime日志时间
message日志消息
context日志上下文数据
level日志级别
level_code日志级别编号
channel日志通道名称
extra请求上下文等附加信息

示例：

json
{
  "datetime": "2026-06-27 10:00:00",
  "message": "请求成功",
  "context": {
    "category": "api",
    "status": 200,
    "time": 32
  },
  "level": "DEBUG",
  "level_code": 100,
  "channel": "api",
  "extra": {
    "request_id": "16cb517-918e-48cf-9ddb-1879a4d22fbc",
    "route": "users"
  }
}

异常日志会额外包含异常信息：

json
{
  "context": {
    "exception": {
      "class": "App\\Exceptions\\ExampleException",
      "message": "发生异常",
      "code": 10001,
      "file": "/app/Example.php",
      "line": 10
    }
  }
}

异常堆栈记录规则参见异常堆栈。

日志格式化器 ​

可通过 formatter 配置自定义日志格式化器：

php
'app' => Config::single('app', [
    'formatter' => App\Log\CustomFormatter::class,,
])

Laravel 默认日志格式：

php
'app' => Config::single('app', [
    'formatter' => null,
])

更多日志通道配置请参考 Laravel 日志文档

异常堆栈 ​

Pin 支持记录异常堆栈，并可根据异常类型和调用帧规则控制堆栈内容。

配置 ​

异常堆栈配置位于 config/logging.php：

php
'stack_trace' => [
    'enabled' => env('LOG_STACK_TRACE_ENABLED', false),
    'include_exceptions' => [],
    'exclude_exceptions' => [],
    'max_frames' => 10,
    'include_frames' => [],
    'exclude_frames' => [
        'Illuminate' => 'Illuminate',
    ],
],

配置示例：

php
'stack_trace' => [
    'enabled' => true,
    'max_frames' => 20,
    'include_frames' => [
        '/app/',
    ],
    'exclude_frames' => [
        'vendor',
    ],
],
php
'stack_trace' => [
    'enabled' => true,
    'include_exceptions' => [
        App\Exceptions\PaymentException::class,
    ],
],
php
// 该配置仅保留匹配 `/app/Services/` 或 `/app/Actions/` 的调用帧。

'stack_trace' => [
    'enabled' => true,
    'include_frames' => [
        '#/app/(Services|Actions)/#',
    ],
],

记录规则 ​

异常堆栈默认关闭：

php
'enabled' => env('LOG_STACK_TRACE_ENABLED', false)

启用后：

  • 实现 SkipTrace 的异常不会记录堆栈；
  • 命中 exclude_exceptions 的异常不会记录堆栈；
  • include_exceptions 为空时，记录所有未排除的异常；
  • include_exceptions 不为空时，仅记录指定异常类型。

例如：

php
'stack_trace' => [
    'enabled' => true,
    'include_exceptions' => [
        App\Exceptions\PaymentException::class,
    ],
    'exclude_exceptions' => [
        Illuminate\Validation\ValidationException::class,
    ],
],

表示仅记录 PaymentException 及其子类的堆栈信息，ValidationException 会被排除。

TIP

当异常同时匹配 include_exceptions 和 exclude_exceptions 时，以排除规则为准。

跳过堆栈记录 ​

对于无需记录堆栈的异常，可以实现 SkipTrace 接口：

php
use Pin\Log\SkipTrace;
use RuntimeException;

class BusinessNoticeException extends RuntimeException implements SkipTrace
{
}

调用帧 ​

调用帧示例：

text
#0/25 /path/app/Services/UserService.php:42 App\Services\UserService->create
内容说明
#0/25当前调用帧序号 / 总帧数
file:line文件路径和行号
class->method调用类和方法

保留数量由 max_frames 控制：

php
'max_frames' => 10

调用帧过滤 ​

可以通过 include_frames 和 exclude_frames 控制保留的调用帧：

php
'include_frames' => [],
'exclude_frames' => [
    'Illuminate' => 'Illuminate',
],

过滤匹配以下字段：

字段说明
file文件路径
class调用类名
function方法名

规则支持：

类型说明
普通字符串对字段内容进行包含匹配
# 开头使用正则表达式匹配

API 响应日志 ​

Pin 提供 API 响应日志，用于记录请求结果、异常响应和慢请求信息。

API 响应日志由 Pin\Http\Middleware\LogApiResponse 中间件负责，默认已开启。

配置 ​

API 响应日志配置位于：

php
config/logging.php


'response' => [
    //
],

慢请求 ​

logging.response.slow_threshold 支持秒和毫秒：

配置阈值
22000ms
0.5500ms
500500ms

规则：

  • <=10 按秒解析；
  • >10 按毫秒解析。

默认值为 2，即 2000ms。

记录规则 ​

API 响应日志仅记录符合标准响应结构且未被排除的请求。

记录逻辑如下：

条件是否记录
非标准 JSON 响应否
命中排除路由否
调试模式开启记录
logging.response.enabled=true记录
业务失败记录
慢请求记录
普通成功请求不记录

INFO

当调试模式或 logging.response.enabled 开启时，会记录所有符合条件的 API 响应。

默认情况下，仅记录业务失败和慢请求。

日志内容 ​

API 响应日志写入 api channel。

日志级别 ​

条件级别
HTTP 5xxerror
业务失败info
慢请求notice
普通请求debug

请求数据 ​

请求数据默认不会记录。

以下情况会记录请求数据：

  • 调试模式；
  • 业务失败；
  • 开启 include_request_payload。

WARNING

生产环境开启请求数据记录时，应注意过滤密码、Token 等敏感信息。

响应数据 ​

响应数据默认会写入日志。

可以通过 logging.response.ignore_response_data 配置不记录响应数据的路由。

当响应数据超过 logging.response.max_length 时会自动截断。

响应数据写入日志前会经过敏感字段脱敏。

基于 MIT 许可发布

版权所有 © 2026 Pin