Laravel Monolog 链式异常堆栈追踪问题解决

1. 问题背景与现象

在 Laravel 应用开发中，当异常被捕获并重新抛出时，通常会形成一个“链式异常”（Chained Exceptions），即新的异常会包含前一个异常作为其 previous 属性。这种机制有助于在异常发生时，通过追溯整个调用链来获取更丰富的上下文信息。

Laravel 在控制台输出异常时，通常会利用 nunomaduro/collision 包，该包能够智能地合并并展示链式异常的所有堆栈追踪信息，这对于调试而言极其有用。然而，在日志输出方面，Laravel 默认使用的是 Monolog 库。Monolog 1.x 版本在处理链式异常时，默认的 LineFormatter 行为存在一个显著的局限性：它只会输出链中最后一个被抛出的异常（即最外层异常）的堆栈追踪，而只会显示前一个异常的错误信息，却不包含其堆栈追踪。

这意味着，如果一个深层函数抛出了原始异常，然后该异常层层被捕获并包装成新的异常抛出，最终 Monolog 日志中你看到的堆栈追踪将是离你最近的那个包装异常的，而非导致问题的原始异常的堆栈。这使得追溯问题的真正根源变得困难。

考虑以下示例代码：

getCode(), $e);
    }
}

function method2()
{
    try {
        method3();
    } catch (\Exception $e) {
        throw new \Exception('调用 method2 失败，因为出现问题', $e->getCode(), $e);
    }
}

function method3()
{
    // 这是原始异常，我们希望在日志中看到它的堆栈追踪，
    // 或者更好的是，所有三个异常的合并堆栈追踪。
    throw new \Exception('糟糕，一个错误发生了！');
}

在上述场景中，我们最希望在日志中看到 method3 抛出异常的堆栈追踪，因为它指示了问题的原始发生地。

2. 问题根源分析

经过深入研究，该问题主要存在于 Monolog 1.x 版本的 LineFormatter 中。这个格式化器在处理异常时，没有充分考虑链式异常的 previous 属性并递归地提取所有堆栈信息。Monolog 2.x 版本已经通过相关的 Pull Request 解决了 LineFormatter 的这一缺陷，使其能够正确处理并输出链式异常的完整堆栈追踪。

3. 解决方案

针对此问题，主要有两种推荐的解决方案。

3.1 方案一：升级 Monolog 到 2.x 版本 (推荐)

最直接且推荐的解决方案是将 Monolog 升级到 2.x 版本。Laravel 6.x 及更高版本已经支持 Monolog 2.x，因此升级通常不会引入兼容性问题。

升级步骤：

1. 打开项目的 composer.json 文件。
2. 找到 require 或 require-dev 部分，将 monolog/monolog 的版本约束更新为 ^2.0 或更高。例如：

   "require": {
       "php": "^7.2",
       "fideloper/proxy": "^4.2",
       "laravel/framework": "^6.20",
       "laravel/tinker": "^2.0",
       "monolog/monolog": "^2.0" // 更新此行
   },

3. 运行 Composer 更新命令：

   composer update monolog/monolog --with-dependencies

   或者直接：

   composer update

   此命令会下载并安装 Monolog 2.x 版本及其兼容的依赖项。

升级到 Monolog 2.x 后，其内置的 LineFormatter 将能够正确处理链式异常，并在日志中输出完整的堆栈追踪信息，无需额外配置。

3.2 方案二：使用其他格式化器或自定义格式化器 (Monolog 1.x 兼容性需求)

如果由于项目中的其他依赖项限制，无法将 Monolog 升级到 2.x 版本，那么可以考虑使用 Monolog 1.x 中其他支持链式异常的格式化器，或者编写一个自定义的 Monolog 格式化器。

3.2.1 使用其他内置格式化器

Monolog 提供了多种内置的格式化器，例如 HtmlFormatter 或 JsonFormatter。虽然 LineFormatter 有问题，但其他格式化器可能已经正确处理了链式异常。你可以尝试在 Laravel 的日志配置中切换到这些格式化器。

配置示例 (config/logging.php)：

 [
        'stack' => [
            'driver' => 'stack',
            'channels' => ['single'],
            'ignore_exceptions' => false,
        ],

        'single' => [
            'driver' => 'single',
            'path' => storage_path('logs/laravel.log'),
            'level' => 'debug',
            'days' => 14,
            'tap' => [App\Logging\CustomizeFormatter::class], // 如果使用自定义格式化器
            // 'formatter' => HtmlFormatter::class, // 或者直接在这里指定内置格式化器
            // 'formatter_with' => [ // 如果格式化器需要构造参数
            //     'dateFormat' => 'Y-m-d H:i:s.u',
            //     'includeStacktraces' => true,
            // ],
        ],

        // ... 其他通道
    ],

    // ...
];

在 config/logging.php 中，你可以通过 formatter 键指定要使用的格式化器类。

3.2.2 编写自定义格式化器

如果内置格式化器不满足需求，或者你希望在 Monolog 1.x 环境下复刻 Monolog 2.x LineFormatter 的行为，你可以编写一个继承自 Monolog\Formatter\LineFormatter 的自定义格式化器，并重写其 format 方法，以递归处理链式异常。

自定义格式化器示例 (app/Logging/CustomLineFormatter.php)：

formatException($exception);
                $exception = $exception->getPrevious();
            } while ($exception);

            // 将完整的堆栈信息添加到输出中
            // 你需要根据你的需求调整输出格式
            $output .= "\n--- Full Exception Trace ---\n" . $fullTrace;
        }

        return $output;
    }

    /**
     * 格式化单个异常的堆栈信息。
     * 这个方法需要根据 Monolog 的内部逻辑来更精细地实现，
     * 以便与 LineFormatter 的默认输出保持一致或更优。
     */
    protected function formatException(Throwable $e): string
    {
        // 这是一个非常简化的示例，Monolog 内部有更复杂的异常格式化逻辑
        return sprintf(
            "%s: %s in %s:%s\nStack trace:\n%s\n",
            get_class($e),
            $e->getMessage(),
            $e->getFile(),
            $e->getLine(),
            $e->getTraceAsString()
        );
    }
}

在 config/logging.php 中使用自定义格式化器：

 [
        'single' => [
            'driver' => 'single',
            'path' => storage_path('logs/laravel.log'),
            'level' => 'debug',
            'formatter' => App\Logging\CustomLineFormatter::class, // 指定你的自定义格式化器
            'formatter_with' => [
                'dateFormat' => 'Y-m-d H:i:s.u',
                'includeStacktraces' => true, // 确保包含堆栈追踪
            ],
        ],
        // ...
    ],
];

请注意，自定义 formatException 方法的实现可能需要更深入地理解 Monolog LineFormatter 内部处理异常的逻辑，以确保输出格式和完整性符合预期。上述示例仅为概念性代码，实际应用中可能需要更健壮的实现。

4. 注意事项与总结

• 首选升级： 强烈建议将 Monolog 升级到 2.x 版本。这是最简单、最可靠的解决方案，因为 Monolog 官方已经解决了 LineFormatter 的问题。
• 兼容性： 在升级 Monolog 或更改格式化器之前，务必在开发或测试环境中进行充分测试，确保没有引入新的兼容性问题。
• 日志可读性： 完整的链式异常堆栈追踪虽然信息量大，但也可能使日志文件变得非常冗长。在生产环境中，请根据实际需求权衡日志的详细程度和文件大小。
• 调试效率： 确保日志中包含完整的链式异常堆栈追踪，将极大地提升问题排查和调试的效率，帮助开发者快速定位到错误的原始根源。

通过上述方法，你可以确保 Laravel 应用的 Monolog 日志能够完整、准确地输出链式异常的堆栈追踪信息，从而为应用的稳定运行提供更强有力的支持。