> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Horizon

> Erläutert, wie Sie Redis-Queues mit Laravel Horizon visuell verwalten und überwachen. Enthält Dashboard, Balance-Strategien, Supervisor-Einrichtung und Benachrichtigungen.

## Was ist Horizon?

[Laravel Horizon](https://github.com/laravel/horizon) ist ein Überwachungs-Dashboard **speziell für Redis-Queues** in Laravel. Es visualisiert Job-Durchsatz, Laufzeiten und Fehler in Echtzeit und ermöglicht es, Worker-Einstellungen im Code zu verwalten.

<Info>
  Horizon erweitert die Basisfunktionalität der Queue. Machen Sie sich zunächst mit den Grundlagen zu [Queues und Jobs](/de/queues) vertraut. Als Backend ist zwingend [Redis](/de/redis) erforderlich.
</Info>

```mermaid theme={null}
flowchart LR
    Browser["Browser"] -->|"/horizon"| Dashboard["Horizon-<br>Dashboard"]
    Dashboard -->|"Überwachen und Steuern"| Horizon["Horizon-<br>Prozess"]
    Horizon -->|"Jobs verwalten"| Redis["Redis-<br>Queue"]
    Redis -->|"Job abholen"| Worker1["Worker 1"]
    Redis -->|"Job abholen"| Worker2["Worker 2"]
    Redis -->|"Job abholen"| Worker3["Worker 3"]
```

## Installation

<Warning>
  Horizon nutzt Redis als Queue-Backend. Stellen Sie sicher, dass `QUEUE_CONNECTION` in `config/queue.php` auf `redis` gesetzt ist. Redis Cluster wird derzeit nicht unterstützt.
</Warning>

Installation via Composer:

```shell theme={null}
composer require laravel/horizon
```

Veröffentlichen Sie anschließend die Assets und die Konfigurationsdatei.

```shell theme={null}
php artisan horizon:install
```

Dabei werden `config/horizon.php` und `app/Providers/HorizonServiceProvider.php` erzeugt.

## Konfiguration

### Aufbau der Datei config/horizon.php

`config/horizon.php` bündelt sämtliche Worker-Einstellungen. Kern ist die Option `environments`.

```php theme={null}
'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            // Weitere Werte werden aus dem defaults-Bereich übernommen
            'maxProcesses' => 3,
        ],
    ],
],
```

<Info>
  Horizon nutzt intern eine Redis-Verbindung namens `horizon`. Vergeben Sie diesen Namen in `config/database.php` nicht an eine andere Verbindung.
</Info>

### Supervisor

Jede Umgebung kann einen oder mehrere „Supervisor" enthalten. Ein Supervisor ist die Verwaltungseinheit für eine Worker-Gruppe; Sie können pro Umgebung mehrere Supervisor mit unterschiedlichen Queues, Balance-Strategien und Prozessanzahlen betreiben.

### Standardwerte

In `defaults` legen Sie Standardwerte fest, die für alle Supervisor gelten.

```php theme={null}
'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],
```

### Wartungsmodus

Ist die Anwendung im Wartungsmodus, verarbeitet Horizon standardmäßig keine Jobs. Um die Verarbeitung dennoch zu erzwingen, verwenden Sie die Option `force`.

```php theme={null}
'environments' => [
    'production' => [
        'supervisor-1' => [
            'force' => true,
        ],
    ],
],
```

### Maximale Anzahl an Versuchen

```php theme={null}
'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],
```

Mit `tries` auf `0` erlauben Sie unbegrenzte Wiederholungen.

### Job-Timeout

```php theme={null}
'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],
```

<Warning>
  Setzen Sie `timeout` einige Sekunden kürzer als `retry_after` in `config/queue.php`. Mit der Balance-Strategie `auto` beendet Horizon zudem Jobs, die diesen Wert überschreiten, gegebenenfalls zwangsweise.
</Warning>

### Backoff (Wartezeit vor Wiederholung)

Wartezeit in Sekunden nach einer Ausnahme bis zum nächsten Versuch.

```php theme={null}
// Fester Wert
'backoff' => 10,

// Gestaffelt (exponentielles Backoff)
'backoff' => [1, 5, 10],
```

## Balance-Strategien

Horizon kennt drei Strategien zur Worker-Balancierung.

<AccordionGroup>
  <Accordion title="auto (Standard)">
    Passt die Worker-Anzahl automatisch an die Queue-Auslastung an. Über `minProcesses` und `maxProcesses` bestimmen Sie den Rahmen.

    ```php theme={null}
    'supervisor-1' => [
        'balance' => 'auto',
        'autoScalingStrategy' => 'time', // oder 'size'
        'minProcesses' => 1,
        'maxProcesses' => 10,
        'balanceMaxShift' => 1,
        'balanceCooldown' => 3,
    ],
    ```

    * `time` – Skalierung nach geschätzter Zeit bis zur Leerung der Queue
    * `size` – Skalierung nach Anzahl der Jobs in der Queue

    <Info>
      Bei der Strategie `auto` bestimmt die Reihenfolge der Queues nicht deren Priorität. Für strikte Prioritäten verwenden Sie mehrere Supervisor.
    </Info>
  </Accordion>

  <Accordion title="simple">
    Legt eine feste Anzahl Worker fest und verteilt sie gleichmäßig auf die angegebenen Queues.

    ```php theme={null}
    'supervisor-1' => [
        'balance' => 'simple',
        'processes' => 10,
        'queue' => ['default', 'notifications'],
    ],
    ```

    Im Beispiel erhalten `default` und `notifications` jeweils fünf Prozesse.
  </Accordion>

  <Accordion title="false (keine Balancierung)">
    Priorisiert die Queues strikt in der angegebenen Reihenfolge. Das Verhalten entspricht dem Standard-Queue-System, skaliert die Worker-Anzahl aber dennoch bedarfsabhängig.

    ```php theme={null}
    'supervisor-1' => [
        'balance' => false,
        'queue' => ['default', 'notifications'],
        'minProcesses' => 1,
        'maxProcesses' => 10,
    ],
    ```

    Jobs der Queue `default` werden immer vor denen der Queue `notifications` verarbeitet.
  </Accordion>
</AccordionGroup>

## Autorisierung des Dashboards

Das Horizon-Dashboard ist unter der Route `/horizon` erreichbar. Lokal ist es standardmäßig für alle zugänglich; in der **Produktion** schränken Sie den Zugriff über ein Gate ein.

Passen Sie die Methode `gate()` in `app/Providers/HorizonServiceProvider.php` an.

```php theme={null}
use App\Models\User;
use Illuminate\Support\Facades\Gate;

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            'admin@example.com',
        ]);
    });
}
```

Ist keine Authentifizierung erforderlich (weil Sie z. B. IP-Einschränkungen nutzen), machen Sie das Argument optional.

```php theme={null}
Gate::define('viewHorizon', function (User $user = null) {
    // Wenn der Zugriff z. B. per IP-Adresse eingeschränkt wird
    return true;
});
```

## Horizon starten

### Grundlegende Befehle

```shell theme={null}
# Starten
php artisan horizon

# Pausieren / fortsetzen
php artisan horizon:pause
php artisan horizon:continue

# Bestimmten Supervisor pausieren / fortsetzen
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# Status abfragen
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# Sauber beenden
php artisan horizon:terminate
```

### Lokale Entwicklung: automatisches Neustarten

Um Horizon bei Änderungen an Quellcode automatisch neu zu starten, verwenden Sie `horizon:listen`.

```shell theme={null}
npm install --save-dev chokidar
php artisan horizon:listen

# In Docker- / Vagrant-Umgebungen
php artisan horizon:listen --poll
```

### Dauerbetrieb mit Supervisor

In der Produktion betreiben Sie Horizon mit Supervisor dauerhaft.

#### Supervisor installieren

```shell theme={null}
sudo apt-get install supervisor
```

#### Konfigurationsdatei anlegen

Legen Sie `/etc/supervisor/conf.d/horizon.conf` an.

```ini theme={null}
[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600
```

<Warning>
  Setzen Sie `stopwaitsecs` höher als die längste erwartete Jobdauer. Ist der Wert zu klein, kann Supervisor Jobs abbrechen, bevor sie fertig sind.
</Warning>

#### Supervisor starten

```shell theme={null}
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon
```

#### Beim Deployment

Starten Sie Horizon nach jedem Deployment neu, damit Änderungen greifen.

```shell theme={null}
php artisan horizon:terminate
```

Sofern Supervisor mit `autostart=true` und `autorestart=true` konfiguriert ist, startet Horizon anschließend automatisch neu.

## Jobs verwalten

### Tags

Horizon erkennt Eloquent-Modelle, die einem Job übergeben werden, automatisch und versieht Jobs mit passenden Tags.

```php theme={null}
// Job mit Video-Modell (id=1) → automatischer Tag "App\Models\Video:1"
RenderVideo::dispatch(Video::find(1));
```

Um Tags manuell zu definieren, implementieren Sie die Methode `tags()`.

```php theme={null}
class RenderVideo implements ShouldQueue
{
    /**
     * @return array<int, string>
     */
    public function tags(): array
    {
        return ['render', 'video:'.$this->video->id];
    }
}
```

Bei Event-Listenern wird der Methode `tags()` die Event-Instanz übergeben.

```php theme={null}
class SendRenderNotifications implements ShouldQueue
{
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}
```

### Ausblenden (Silence)

Jobs, die nicht in der Liste „abgeschlossener Jobs" im Dashboard erscheinen sollen, können Sie in `config/horizon.php` ausblenden.

```php theme={null}
'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

// Nach Tags ausblenden
'silenced_tags' => [
    'notifications',
],
```

Alternativ implementieren Sie das Interface `Silenced`.

```php theme={null}
use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}
```

## Metriken und Monitoring

Das Metrik-Dashboard von Horizon zeigt den Durchsatz und die Laufzeit von Jobs und Queues. Damit die Daten fortlaufend aktualisiert werden, richten Sie einen Snapshot-Zeitplan ein.

```php theme={null}
// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();
```

Um alle Metrikdaten zu löschen, führen Sie folgenden Befehl aus:

```shell theme={null}
php artisan horizon:clear-metrics
```

## Benachrichtigungen zu Job-Fehlern

Bei langen Wartezeiten in der Queue können Sie sich benachrichtigen lassen. Konfigurieren Sie dies in der `boot()`-Methode von `app/Providers/HorizonServiceProvider.php`.

```php theme={null}
use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

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

### Schwellenwerte für Wartezeiten

In `config/horizon.php` legen Sie mit der Option `waits` die Wartezeit fest, ab der Benachrichtigungen gesendet werden.

```php theme={null}
'waits' => [
    'redis:critical' => 30,  // Benachrichtigen ab 30 Sekunden Wartezeit
    'redis:default' => 60,
    'redis:batch' => 120,
],
```

Der Wert `0` deaktiviert die Benachrichtigung für die betreffende Queue.

## Umgang mit fehlgeschlagenen Jobs

Fehlgeschlagene Jobs können Sie über ID oder UUID löschen.

```shell theme={null}
# Bestimmten fehlgeschlagenen Job löschen
php artisan horizon:forget 5

# Alle fehlgeschlagenen Jobs löschen
php artisan horizon:forget --all
```

Um alle Jobs einer Queue zu löschen, verwenden Sie:

```shell theme={null}
# Standard-Queue leeren
php artisan horizon:clear

# Bestimmte Queue leeren
php artisan horizon:clear --queue=emails
```

## Upgrades

Vor einem Major-Update von Horizon sollten Sie stets die [Upgrade-Anleitung](https://github.com/laravel/horizon/blob/master/UPGRADE.md) lesen.

## Verwandte Seiten

<CardGroup cols={2}>
  <Card title="Queues und Jobs" href="/de/queues">
    Grundlagen der Laravel-Queue: Job-Erstellung, Dispatchen, Batches und Fehlerbehandlung.
  </Card>

  <Card title="Redis" href="/de/redis">
    Konfiguration und Nutzung von Redis als Backend für Horizon.
  </Card>
</CardGroup>


## Related topics

- [Cache](/de/cache.md)
- [Versionskompatibilität von Paketen verwalten](/de/advanced/package-versioning.md)
- [Queues und Jobs](/de/queues.md)
- [Laravel Sentinel – Analyse der Route-Schutz-Middleware](/de/blog/sentinel-introduction.md)
- [Laravel-Updates April 2026](/de/blog/changelog/202604.md)