Search by

jason / laravel-logtail

jasonencode

Logtail (Better Stack) log driver for Laravel with call-site origin tracking.

Package info

github.com/jasonencode/laravel-logtail

pkg:composer/jason/laravel-logtail

Statistics

Installs: 3

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.1.0 2026-11-16 08:18 UTC

This package is auto-updated.

Last update: 2026-11-16 08:18:44 UTC


README

把 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 只能得到 {}(属性私有),堆栈全丢;按 Monolog NormalizerFormatter 的惯例转成字符串,与 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(...)。

注意事项 / 已知限制

  1. 上报失败是静默的:驱动不写本地文件,也不抛异常。LOG_CHANNEL=logtail 时 laravel.log 不会有记录,所以「Logtail 查不到」≠「没有异常」。要留底就用 stack。
  2. 同步阻塞:write() 在请求线程里同步发 HTTP,源地址不可达时该请求最坏多等 2s。高并发场景建议改为队列/批量上报。
  3. level 是本地过滤:低于通道级别的记录连 HTTP 都不发,不做服务端过滤。
  4. path / days 无效:driver => logtail 时不写本地文件,这两个键是从 daily 配置抄过来残留的,可以删。
  5. Authorization: Bearer 后为空:LOGTAIL_SECRET 没填时请求头仍然会发,服务端拒绝且异常被吞,只表现为「日志没到」。
  6. 敏感数据:Log::info($request->all()) 这类调用会把密码、token、支付报文原样上报到第三方,写日志前先过滤。

从复制文件版迁移

之前手动复制 app/Support/Logging/LogtailHandler.php 的项目:

  1. 删除 app/Support/Logging/LogtailHandler.php。
  2. 删除 AppServiceProvider::register() 里的 LogtailHandler::registerDriver()。
  3. 把 config/services.php 里的 logtail 配置(url / secret)迁移到 .env 的同名变量。
  4. composer require jason/laravel-logtail,必要时 php artisan vendor:publish --tag=logtail-config。
  5. config/logging.php 里原有的 logtail 通道保留即可(包不会自动创建通道)。
  6. php artisan config:clear。

测试

composer install
composer test

License

MIT