laravel-logtail maintained by jason
Laravel Logtail
把 Laravel 的 Monolog 记录直接 POST 到 Logtail(Better Stack) 源地址的日志驱动。
支持 Laravel 自动发现,安装后配置环境变量、在 config/logging.php 添加通道即可使用,并额外附带日志调用点定位(extra.origin)与异常堆栈字符串化。
要求
- PHP 8.3+
- Laravel 12 / 13
guzzlehttp/guzzle:^7.15.2 || ^8.0.1- Monolog 3(Laravel 12 起默认)
安装
composer require jason/laravel-logtail
Laravel 会自动发现 Jason\Logtail\LogtailServiceProvider,无需手动注册。
需要修改默认配置时再发布配置文件:
php artisan vendor:publish --tag=logtail-config
发布后得到 config/logtail.php。不发布也能用,包内自带同样的默认值。
配置
.env 追加:
# 默认日志通道切到 logtail(也可保留 daily,只让指定通道走 logtail)
LOG_CHANNEL=logtail
# Logtail 源地址 + 源 token(Better Stack 控制台 Sources 页可见)
LOGTAIL_URL=https://logtail.example.com/log/xxxxxxxxxxxx
LOGTAIL_SECRET=
# 最低上报级别(debug/info/warning/error/...)
LOGTAIL_LEVEL=debug
# 可选:HTTP 超时(秒),默认 2
LOGTAIL_TIMEOUT=2
LOGTAIL_CONNECT_TIMEOUT=2
改完 .env 或配置后清缓存:
php artisan config:clear
日志通道
包只注册 logtail 驱动,不会自动创建通道。需要在 config/logging.php 的 channels 里显式添加:
'logtail' => [
'driver' => 'logtail',
'name' => 'logtail', // 出现在上报数据的 channel 字段
'level' => env('LOGTAIL_LEVEL', 'debug'),
// 以下均可选,未填时回落到 config/logtail.php
// 'url' => env('LOGTAIL_URL'),
// 'secret' => env('LOGTAIL_SECRET'),
// 'timeout' => 2,
// 'connect_timeout' => 2,
],
然后设置 LOG_CHANNEL=logtail(或按需放进 stack)。
本地留底 + 远程上报
驱动本身不写本地文件。需要 storage/logs 留底时用 stack:
'stack' => [
'driver' => 'stack',
'channels' => ['daily', 'logtail'],
'ignore_exceptions' => false,
],
然后把 LOG_CHANNEL 设为 stack。
多源 / 按业务分流
给不同业务各开一条源(不同 URL/token),每个通道用不同的 name:
'jd' => [
'driver' => 'logtail',
'name' => 'jd',
'url' => env('LOGTAIL_JD_URL'),
'secret' => env('LOGTAIL_JD_SECRET'),
'level' => env('LOGTAIL_LEVEL', 'debug'),
],
日志里用 Log::channel('jd')->info(...) 写入,Logtail 侧可按 channel 字段分流。
使用
Log::info('hello', ['order_id' => 1]);
try {
// ...
} catch (\Throwable $e) {
Log::error('支付失败', ['exception' => $e]);
}
验证连通性:
php artisan tinker --execute="Log::channel('logtail')->info('logtail 连通性测试', ['at' => now()->toDateTimeString()]);"
Logtail 控制台能看到这条记录即通。也可以故意 throw new Exception('test') 走一次未捕获异常,确认堆栈和 extra.origin 都有值。
上报数据结构
实际发出的 body(LogRecord::toArray() + extra.origin):
{
"message": "hello",
"context": { "order_id": 1 },
"level": 200,
"level_name": "INFO",
"channel": "logtail",
"datetime": "2026-11-16T10:00:00.000000+08:00",
"extra": {
"origin": {
"class": "App\\Services\\OrderService",
"function": "pay",
"file": "app/Services/OrderService.php",
"line": 88
}
}
}
设计要点
extra.origin定位调用点:origin塞在extra里而不是顶层,是 handler/processor 附加数据的惯例位置,Logtail 只渲染约定字段,顶层自定义键不显示。- 普通日志:
debug_backtrace()跳过本类与vendor/帧,取第一个业务帧;file/line取调用Log::xxx()那一行,class/function取其外层方法。 - 未捕获异常 / PHP warning:栈已经退到接住异常的中间件,所以以异常自身的
file/line为准,class/function取异常栈里第一个业务帧;ErrorException的file/line正好是 warning 行。
- 普通日志:
- 异常对象转字符串:
context.exception里是 Throwable 对象,直接json_encode只能得到{}(属性私有),堆栈全丢;按 MonologNormalizerFormatter的惯例转成字符串,与storage/logs本地日志同格式。 datetime是 ISO 8601 字符串:Monolog 3 用的是JsonSerializableDateTimeImmutable,序列化后形如2026-11-16T10:00:00.000000+08:00。- 绝不阻塞业务:
write()里catch (Throwable) {}全吞;HTTP 超时 2s(连接 2s),http_errors => false不抛 4xx/5xx。 - 没配 URL 直接跳过:省掉一次注定失败的请求。
- 注册闭包的两个绑定陷阱(改驱动时最容易踩):
- 不能用
static闭包:LogManager::extend()会bindTo($this),直接抛Cannot bind an instance to a static closure。 - 闭包体里不能用
new self:闭包被bindTo后作用域变成LogManager,self解析成LogManager而不是本类,报pushHandler(): Argument #1 must be of type HandlerInterface, Illuminate\Log\LogManager given。用完整类名new LogtailHandler(...)。
- 不能用
注意事项 / 已知限制
- 上报失败是静默的:驱动不写本地文件,也不抛异常。
LOG_CHANNEL=logtail时laravel.log不会有记录,所以「Logtail 查不到」≠「没有异常」。要留底就用stack。 - 同步阻塞:
write()在请求线程里同步发 HTTP,源地址不可达时该请求最坏多等 2s。高并发场景建议改为队列/批量上报。 level是本地过滤:低于通道级别的记录连 HTTP 都不发,不做服务端过滤。path/days无效:driver => logtail时不写本地文件,这两个键是从daily配置抄过来残留的,可以删。Authorization: Bearer后为空:LOGTAIL_SECRET没填时请求头仍然会发,服务端拒绝且异常被吞,只表现为「日志没到」。- 敏感数据:
Log::info($request->all())这类调用会把密码、token、支付报文原样上报到第三方,写日志前先过滤。
从复制文件版迁移
之前手动复制 app/Support/Logging/LogtailHandler.php 的项目:
- 删除
app/Support/Logging/LogtailHandler.php。 - 删除
AppServiceProvider::register()里的LogtailHandler::registerDriver()。 - 把
config/services.php里的logtail配置(url/secret)迁移到.env的同名变量。 composer require jason/laravel-logtail,必要时php artisan vendor:publish --tag=logtail-config。config/logging.php里原有的logtail通道保留即可(包不会自动创建通道)。php artisan config:clear。
测试
composer install
composer test
License
MIT