README

此包将监控您的 Laravel 计划。每次计划任务启动、结束、失败或跳过时，都会在数据库的日志表中写入一条记录。使用 list 命令，您可以检查计划任务何时已执行。

此包还可以将您的计划与 Oh Dear 同步。Oh Dear 会在计划任务未按时运行或失败时向您发送通知。

支持我们

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄来明信片，说明您正在使用我们的哪个包。您可以在我们的联系页面上找到我们的地址。我们将在我们的虚拟明信片墙上发布所有收到的明信片。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-schedule-monitor

如果您需要 Laravel 8 支持，您可以使用 composer require spatie/laravel-schedule-monitor:^2 安装包的 v2 版本。

准备数据库

您必须发布并运行迁移

php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-migrations"
php artisan migrate

发布配置文件

您可以使用以下方式发布配置文件

php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-config"

这是发布配置文件的内容

return [
    /*
     * The schedule monitor will log each start, finish and failure of all scheduled jobs.
     * After a while the `monitored_scheduled_task_log_items` might become big.
     * Here you can specify the amount of days log items should be kept.
     *
     * Use Laravel's pruning command to delete old `MonitoredScheduledTaskLogItem` models.
     * More info: https://laravel.net.cn/docs/9.x/eloquent#mass-assignment
     */
    'delete_log_items_older_than_days' => 30,

    /*
     * The date format used for all dates displayed on the output of commands
     * provided by this package.
     */
    'date_format' => 'Y-m-d H:i:s',

    'models' => [
        /*
         * The model you want to use as a MonitoredScheduledTask model needs to extend the
         * `Spatie\ScheduleMonitor\Models\MonitoredScheduledTask` Model.
         */
        'monitored_scheduled_task' => Spatie\ScheduleMonitor\Models\MonitoredScheduledTask::class,

        /*
         * The model you want to use as a MonitoredScheduledTaskLogItem model needs to extend the
         * `Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem` Model.
         */
        'monitored_scheduled_log_item' => Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem::class,
    ],

    /*
     * Oh Dear can notify you via Mail, Slack, SMS, web hooks, ... when a
     * scheduled task does not run on time.
     *
     * More info: https://ohdear.app/cron-checks
     */
    'oh_dear' => [
        /*
         * You can generate an API token at the Oh Dear user settings screen
         *
         * https://ohdear.app/user/api-tokens
         */
        'api_token' => env('OH_DEAR_API_TOKEN', ''),

        /*
         *  The id of the site you want to sync the schedule with.
         *
         * You'll find this id on the settings page of a site at Oh Dear.
         */
        'site_id' => env('OH_DEAR_SITE_ID'),

        /*
         * To keep scheduled jobs as short as possible, Oh Dear will be pinged
         * via a queued job. Here you can specify the name of the queue you wish to use.
         */
        'queue' => env('OH_DEAR_QUEUE'),

        /*
         * `PingOhDearJob`s will automatically be skipped if they've been queued for
         * longer than the time configured here.
         */
        'retry_job_for_minutes' => 10,
    ],
];

清理数据库

调度监控器将记录所有计划任务的每个启动、完成和失败。过了一段时间后，monitored_scheduled_task_log_items 可能会变得很大。

使用 Laravel 的模型修剪功能，您可以通过删除旧的 MonitoredScheduledTaskLogItem 模型来清理。在 schedule-monitor 配置文件中配置的 delete_log_items_older_than_days 天数之前的模型将被删除。

// app/Console/Kernel.php

use Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule)
    {
        $schedule->command('model:prune', ['--model' => MonitoredScheduledTaskLogItem::class])->daily();
    }
}

同步计划

每次部署您的应用程序时，您都应该执行 schedule-monitor:sync 命令

php artisan schedule-monitor:sync

此命令负责将您的计划与数据库和可选的 Oh Dear 同步。我们强烈建议将此命令添加到部署您的生产环境的脚本中。

在非生产环境中，您应该手动运行 schedule-monitor:sync。您可以使用 schedule-monitor:list 来验证是否已正确同步。

注意：运行同步命令将删除除了应用程序计划之外的所有其他 cron 监控器。

如果您希望使用非破坏性同步到 Oh Dear，以便您可以在 Laravel 之外监控其他 cron 任务，您可以使用 --keep-old 标志。这将仅向 Oh Dear 推送新任务，而不是进行完整同步。请注意，这将不会从 Oh Dear 中删除不再在您的计划中的任何任务。

用法

要监控您的计划，您应该首先运行 schedule-monitor:sync。此命令将检查您的计划，并在 monitored_scheduled_tasks 表中为每个任务创建一个条目。

要查看所有监视的计划任务，您可以运行schedule-monitor:list。此命令将列出所有监视的计划任务。它将显示计划任务上次开始、完成或失败的时间。

每次计划任务开始、结束、失败或跳过时，包都会在数据库中的monitored_scheduled_task_log_items表中写入一个条目。如果您想了解计划任务何时以及如何执行，请查看该表的内容。日志项还包含其他有趣的指标，如内存使用、执行时间等。

任务命名

计划监视器将尝试自动确定计划任务的名称。对于命令，这是命令名称；对于匿名作业，将使用第一个参数的类名。对于某些任务，如计划关闭，无法自动确定名称。

要手动设置计划任务的名称，您可以在其上附加monitorName()。

以下是一个示例。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->monitorName('a-custom-name');
   $schedule->call(fn () => 1 + 1)->hourly()->monitorName('addition-closure');
}

当您更改任务的名称时，计划监视器将删除具有旧名称的监视器的所有日志项，并使用任务的新名称创建一个新的监视器。

设置宽限期

当包检测到计划任务的最后运行未按时完成时，schedule-monitor列表将以红色背景色显示该任务。在此屏幕截图中，名为your-command的任务运行过晚。

如果任务未在预定运行时间加上宽限期结束时完成，包将确定任务运行过晚。您可以将宽限期视为任务在正常情况下完成所需的分钟数。默认情况下，包为每个任务提供5分钟的宽限期。

您可以通过在任务上使用graceTimeInMinutes方法来自定义宽限期。在此示例中，为your-command任务使用了10分钟的宽限期。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->graceTimeInMinutes(10);
}

忽略计划任务

在安排任务时附加doNotMonitor，您可以避免监视计划任务。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->doNotMonitor();
}

将输出存储在数据库中

在安排任务时附加storeOutputInDb，您可以存储输出。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->storeOutputInDb();
}

输出将存储在monitored_scheduled_task_log_items表的meta列的output键中。

多租户

如果您使用spatie/laravel-multitenancy，您应在config/multitenancy.php中的not_tenant_aware_jobs数组中添加PingOhDearJob。

'not_tenant_aware_jobs' => [
    // ...
    \Spatie\ScheduleMonitor\Jobs\PingOhDearJob::class,
]

如果没有它，PingOhDearJob将失败，因为没有设置任何租户。

当计划任务未按时完成时收到通知

此包可以将您的计划与Oh Dear的cron检查同步。Oh Dear将在计划任务未按时完成时向您发送通知。

要开始使用，您首先需要安装Oh Dear SDK。

composer require ohdearapp/ohdear-php-sdk

接下来，您需要确保schedule-monitor的api_token和site_id键填充了API令牌和Oh Dear站点ID。要验证这些值是否正确，您可以运行此命令。

php artisan schedule-monitor:verify

要同步您的计划与Oh Dear，请运行此命令

php artisan schedule-monitor:sync

之后，list命令应显示您的应用程序中所有计划任务都已注册在Oh Dear上。

为了使计划作业尽可能短，Oh Dear将通过队列作业进行ping。为了确保快速交付给Oh Dear，并避免假阳性通知，我们强烈建议为这些作业创建一个专用的队列。您可以将该队列的名称放在配置文件的queue键中。

Oh Dear 将等待特定数量的分钟以完成调度任务。这被称为宽限期。默认情况下，所有调度任务都将有5分钟的宽限期。要自定义此值，您可以将 graceTimeInMinutes 添加到您的调度任务中。

以下是一个示例，Oh Dear 将在任务在00:10之前未完成时发送通知。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->graceTimeInMinutes(10);
}

禁用Oh Dear的单独任务

如果您想要由调度监控器监控任务，但不是由Oh Dear监控，您可以将 doMonitorAtOhDear 添加到您的调度任务中。

// in app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
   $schedule->command('your-command')->daily()->doNotMonitorAtOhDear();
}

不受支持的方法

目前，此包不支持使用以下方法的任务

between
unlessBetween
when
skip

第三方调度任务监控器

我们假设，当您的调度任务运行不正常时，一个发送通知的调度任务可能也不会运行。这就是为什么这个包不会自己发送通知。

这些服务可以在调度任务运行不正常时通知您

测试

composer test

变更日志

请参阅变更日志了解最近更改的更多信息。

贡献

请参阅贡献指南了解详细信息。

安全

如果您发现有关安全性的错误，请通过 security@spatie.be 邮件发送，而不是使用问题跟踪器。

致谢

许可证

MIT许可证（MIT）。请参阅许可证文件了解更多信息。

spatie / laravel-schedule-monitor

维护者

详情