Laravel 5.5 Laravel Horizon

イントロダクションIntroduction

Horizon（水平線、展望）は、Laravelで動作するRedisキューのための、美しいダッシュボードとコード駆動による設定を提供します。Horizonにより、ジョブのスループット、ランタイム、実行の失敗など、キューシステムのキーメトリックを簡単に監視できます。Horizon provides a beautiful dashboard and code-driven configuration for your Laravel powered Redis queues. Horizon allows you to easily monitor key metrics of your queue system such as job throughput, runtime, and job failures.

一つのシンプルな設定ファイルにすべてのワーカ設定を保存するため、チーム全体がコラボレート可能なソースコントロール下に、設定を保持できます。All of your worker configuration is stored in a single, simple configuration file, allowing your configuration to stay in source control where your entire team can collaborate.

インストールInstallation

Note: note 非同期のプロセスシグナルを活用しているため、Horizonを動作させるにはPHP7.1以上が必要です。{note} Due to its usage of async process signals, Horizon requires PHP 7.1+.

Composerを使い、LaravelプロジェクトにHorizonをインストールします。You may use Composer to install Horizon into your Laravel project:

composer require laravel/horizon

Horizonをインストールしたら、vendor:publish Artisanコマンドを使用し、アセットを公開します。After installing Horizon, publish its assets using the vendor:publish Artisan command:

php artisan vendor:publish --provider="Laravel\Horizon\HorizonServiceProvider"

設定Configuration

Horizonのアセットを公開すると、config/horizon.phpに一番重要な設定ファイルが設置されます。この設定ファイルにより、ワーカのオプションを設置します。各オプションにはその目的が説明されていますので、ファイル全体をしっかりと確認してください。After publishing Horizon's assets, its primary configuration file will be located at config/horizon.php. This configuration file allows you to configure your worker options and each configuration option includes a description of its purpose, so be sure to thoroughly explore this file.

バランスオプションBalance Options

Horizonでは３つのバランシング戦略が選択できます。simpleとauto、falseです。simple戦略はデフォルトであり、投入されたジョブをプロセス間に均等に割り当てます。Horizon allows you to choose from three balancing strategies: simple, auto, and false. The simple strategy, which is the default, splits incoming jobs evenly between processes:

'balance' => 'simple',

auto戦略は、現在のキュー負荷に基づき、それぞれのキューへ割り当てるワーカプロセス数を調整します。たとえば、notificationsキューに１，０００ジョブが溜まっており、一方でrenderキューが空の場合、Horizonは空になるまでnotificationsキューにより多くのワーカを割り当てます。balanceオプションへfalseを設定すると、設定にリストした順番でキューが処理される、Laravelデフォルトの振る舞いが使われます。The auto strategy adjusts the number of worker processes per queue based on the current workload of the queue. For example, if your notifications queue has 1,000 waiting jobs while your render queue is empty, Horizon will allocate more workers to your notifications queue until it is empty. When the balance option is set to false, the default Laravel behavior will be used, which processes queues in the order they are listed in your configuration.

ダッシュボードの認可Dashboard Authentication

Horizonは、/horizonでダッシュボードを表示します。デフォルトでは、local環境でのみ、このダッシュボードへアクセスできます。ダッシュボードへ更に多くのアクセスポリシーを割り当てるには、Horizon::authメソッドを使用する必要があります。authメソッドは、trueかfalseを返すコールバックを引数に取り、そのユーザーがHorizonダッシュボードへアクセスできるかどうかを指示します。Horizon exposes a dashboard at /horizon. By default, you will only be able to access this dashboard in the local environment. To define a more specific access policy for the dashboard, you should use the Horizon::auth method. The auth method accepts a callback which should return true or false, indicating whether the user should have access to the Horizon dashboard:

Horizon::auth(function ($request) {
    // trueかfalseを返す
});

Horizonの実行Running Horizon

config/horizon.php設定ファイルでワーカの設定を済ませたら、horizon Artisanコマンドを使用し、Horizonを使用開始します。このコマンド一つで、設定済みのワーカ全部を起動できます。Once you have configured your workers in the config/horizon.php configuration file, you may start Horizon using the horizon Artisan command. This single command will start all of your configured workers:

php artisan horizon

Horizonプロセスをhorizon:pause Artisanコマンドで一時停止したり、horizon:continueコマンドで処理を続行したりできます。You may pause the Horizon process and instruct it to continue processing jobs using the horizon:pause and horizon:continue Artisan commands:

php artisan horizon:pause

php artisan horizon:continue

マシン上のマスタHorizonプロセスを穏やかに終了させたい場合は、horizon:terminate Artisanコマンドを使用します。現在処理中のジョブが完了した後に、Horizonは停止します。You may gracefully terminate the master Horizon process on your machine using the horizon:terminate Artisan command. Any jobs that Horizon is currently processing will be completed and then Horizon will exit:

php artisan horizon:terminate

HorizonのデプロイDeploying Horizon

Horizonを実働サーバにデプロイする場合、php artisan horizonコマンドをプロセスモニタで監視し、予期せず終了した場合には再起動をかけるように設定する必要があります。サーバに新しいコードをデプロイしたときに、Horizonプロセスを停止指示する必要があります。その結果、プロセスモニタにより再起動され、コードの変更が反映されます。If you are deploying Horizon to a live server, you should configure a process monitor to monitor the php artisan horizon command and restart it if it quits unexpectedly. When deploying fresh code to your server, you will need to instruct the master Horizon process to terminate so it can be restarted by your process monitor and receive your code changes.

マシン上のマスターHorizonプロセスは、horizon:terminate Artisanコマンドで穏やかに終了できます。現在処理中のジョブを完了させた後に、Horizonは停止します。You may gracefully terminate the master Horizon process on your machine using the horizon:terminate Artisan command. Any jobs that Horizon is currently processing will be completed and then Horizon will exit:

php artisan horizon:terminate

Supervisor設定Supervisor Configuration

horizonプロセスを管理するため、Supervisorプロセスモニタを使用する場合は、以下の設定ファイルが利用できるでしょう。If you are using the Supervisor process monitor to manage your horizon process, the following configuration file should suffice:

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/app.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/app.com/horizon.log

lightbulb">Tip!! サーバ管理に自信がない場合は、Laravel Forgeの利用を考慮してください。ForgeはHorizonを利用する、モダンで堅牢なLaravelアプリケーションに必要なすべてをPHP7以上のサーバにプロビションします。{tip} If you are uncomfortable managing your own servers, consider using Laravel Forge[https://forge.laravel.com]. Forge provisions PHP 7+ servers with everything you need to run modern, robust Laravel applications with Horizon.

タグTags

Horizonでは、mailableやイベントブロードキャスト、通知、キューイベントリスナなどを含むジョブに「タグ」を割り付けられます。実際、ジョブに割り付けられたEloquentモデルに基づいて、ほとんどのジョブでは賢く自動的にHorizonがタグ付けします。例として、以下のジョブをご覧ください。Horizon allows you to assign “tags” to jobs, including mailables, event broadcasts, notifications, and queued event listeners. In fact, Horizon will intelligently and automatically tag most jobs depending on the Eloquent models that are attached to the job. For example, take a look at the following job:

<?php

namespace App\Jobs;

use App\Video;
use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;

class RenderVideo implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * ビデオインスタンス
     *
     * @var \App\Video
     */
    public $video;

    /**
     * 新しいジョブインスタンスの生成
     *
     * @param  \App\Video  $video
     * @return void
     */
    public function __construct(Video $video)
    {
        $this->video = $video;
    }

    /**
     * ジョブの実行
     *
     * @return void
     */
    public function handle()
    {
        //
    }
}

idが1のApp\Videoインスタンスを持つジョブがキューされると、自動的にApp\Video:1タグが付けられます。HorizonはジョブのプロパティがEloquentモデルであるかを確認するからです。Eloquentモデルが見つかると、Horizonはモデルのクラス名と主キーを使用し、賢くタグ付けします。If this job is queued with an App\Video instance that has an id of 1, it will automatically receive the tag App\Video:1. This is because Horizon will examine the job's properties for any Eloquent models. If Eloquent models are found, Horizon will intelligently tag the job using the model's class name and primary key:

$video = App\Video::find(1);

App\Jobs\RenderVideo::dispatch($video);

手動のタグ付けManually Tagging

queueableオブジェクトのタグを任意に定義したい場合は、そのクラスでtagsメソッドを定義してください。If you would like to manually define the tags for one of your queueable objects, you may define a tags method on the class:

class RenderVideo implements ShouldQueue
{
    /**
     * ジョブに割り付けるタグの取得
     *
     * @return array
     */
    public function tags()
    {
        return ['render', 'video:'.$this->video->id];
    }
}

通知Notifications

注意： 通知を利用する前に、プロジェクトへguzzlehttp/guzzle Composerパッケージを追加してください。HorizonでSMSを通知する設定の場合は、Nexmo通知ドライバーの動作要件についても、確認する必要があります。Note: Before using notifications, you should add the guzzlehttp/guzzle Composer package to your project. When configuring Horizon to send SMS notifications, you should also review the prerequisites for the Nexmo notification driver[https://laravel.com/docs/5.5/notifications#sms-notifications].

あるキューが長時間waitしている時に、通知を受け取りたい場合は、Horizon::routeSlackNotificationsToや、Horizon::routeSlackNotificationsTo、Horizon::routeSmsNotificationsToメソッドを利用してください。これらのメソッドは、AppServiceProviderから呼び出すのが良いでしょう。If you would like to be notified when one of your queues has a long wait time, you may use the Horizon::routeMailNotificationsTo, Horizon::routeSlackNotificationsTo, and Horizon::routeSmsNotificationsTo methods. You may call these methods from your application's AppServiceProvider:

Horizon::routeMailNotificationsTo('example@example.com');
Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
Horizon::routeSmsNotificationsTo('15556667777');

通知wait時間のシュレッドホールド設定Configuring Notification Wait Time Thresholds

何秒を「長時間」と考えるかは、config/horizon.php設定ファイルで指定できます。このファイルのwaits設定オプションで、接続／キューの組み合わせごとに、長時間と判定するシュレッドホールドをコントロールできます。You may configure how many seconds are considered a "long wait" within your config/horizon.php configuration file. The waits configuration option within this file allows you to control the long wait threshold for each connection / queue combination:

'waits' => [
    'redis:default' => 60,
],

メトリックスMetrics

Horizonはジョブとキューの待ち時間とスループットの情報をダッシュボードに表示します。このダッシュボードを表示するために、アプリケーションのスケジューラで、５分毎にsnapshot Artisanコマンドを実行する設定を行う必要があります。Horizon includes a metrics dashboard which provides information on your job and queue wait times and throughput. In order to populate this dashboard, you should configure Horizon's snapshot Artisan command to run every five minutes via your application's scheduler[/docs/{{version}}/scheduling]:

/**
 * アプリケーションのコマンドスケジュールの定義
 *
 * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
 * @return void
 */
protected function schedule(Schedule $schedule)
{
    $schedule->command('horizon:snapshot')->everyFiveMinutes();
}