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

# Logging

> Erfahren Sie, wie Sie mit dem Logging-System von Laravel das Verhalten Ihrer Anwendung in Dateien, Slack oder externe Dienste protokollieren.

## Was ist Logging?

Das Logging von Laravel ist rund um das Konzept **Channels** aufgebaut.
Ein Channel definiert, wohin und wie Logs geschrieben werden. Dateien, Slack, Syslog und viele weitere Ausgabeziele lassen sich kombinieren.

Unter der Haube kommt [Monolog](https://github.com/Seldaek/monolog) zum Einsatz – mit einer Vielzahl an Handlern und Formattern.

<Info>
  Standardmäßig kommt der Channel `stack` zum Einsatz. `stack` ist ein übergeordneter Channel, der mehrere Channels bündelt.
</Info>

## Konfiguration

Die Logging-Konfiguration liegt zentral in `config/logging.php`. Den Standard-Channel wechseln Sie über die Umgebungsvariable `LOG_CHANNEL`.

```php theme={null}
// config/logging.php
'default' => env('LOG_CHANNEL', 'stack'),
```

### Verfügbare Channel-Treiber

| Treiber    | Beschreibung                                             |
| ---------- | -------------------------------------------------------- |
| `single`   | Schreibt alle Logs in eine einzige Datei                 |
| `daily`    | Rotiert pro Tag in separate Dateien                      |
| `slack`    | Sendet Nachrichten an einen Slack-Incoming-Webhook       |
| `stack`    | Elternteil, der mehrere Channels bündelt                 |
| `syslog`   | Schreibt in das System-Syslog                            |
| `errorlog` | Schreibt in das PHP-Error-Log                            |
| `monolog`  | Verwendet direkt einen Monolog-Handler                   |
| `custom`   | Vollständig anpassbarer Channel über eine Factory-Klasse |

### Log-Level

Laravel unterstützt die acht Log-Level aus [RFC 5424](https://tools.ietf.org/html/rfc5424).
Nach absteigender Schwere sortiert:

| Level       | Beispielverwendung                                                               |
| ----------- | -------------------------------------------------------------------------------- |
| `emergency` | Das gesamte System ist nicht mehr verwendbar; sofortiges Eingreifen erforderlich |
| `alert`     | Sofortiges Eingreifen nötig (z. B. Datenbank nicht erreichbar)                   |
| `critical`  | Kritische Störung, bei der zentrale Funktionen ausfallen                         |
| `error`     | Laufzeitfehler; Handlung erforderlich, oft aber nicht sofort                     |
| `warning`   | Potenzielles Problem, veraltete APIs, unerwartete Daten                          |
| `notice`    | Normalbetrieb, aber bemerkenswert                                                |
| `info`      | Reguläre Aktionen wie Login oder Bestellabschluss                                |
| `debug`     | Detaillierte Debug-Informationen während der Entwicklung                         |

Die Option `level` eines Channels beschreibt den **Mindest-Log-Level**.
Bei `level = error` werden nur `error` und höher (`critical`, `alert`, `emergency`) geschrieben.

## Grundlegende Verwendung

### Die Log-Facade

Verwenden Sie die Facade `Illuminate\Support\Facades\Log`, um pro Level zu loggen.

```php theme={null}
use Illuminate\Support\Facades\Log;

Log::emergency('Das System ist ausgefallen.');
Log::alert('Die Datenbankverbindung wurde unterbrochen.');
Log::critical('Der Zahlungsdienst antwortet nicht.');
Log::error('Die Aktualisierung der Nutzerdaten ist fehlgeschlagen.');
Log::warning('Eine veraltete Methode wurde aufgerufen.');
Log::notice('Die Konfigurationsdatei wurde neu geladen.');
Log::info('Ein Nutzer hat sich angemeldet.');
Log::debug('Ausführungszeit der Query: 42 ms');
```

Beispiel in einem Controller:

```php theme={null}
<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;

class UserController extends Controller
{
    public function show(string $id): View
    {
        Log::info('Nutzerprofil wird angezeigt.', ['user_id' => $id]);

        return view('user.profile', [
            'user' => User::findOrFail($id),
        ]);
    }
}
```

### Helper `log()`

Der Helper `log()` funktioniert ohne den Import der Facade.

```php theme={null}
log('Log-Eintrag über den Helper.');

// Auch Level und Kontext können angegeben werden
log('Nutzer wurde angelegt.', 'info', ['user_id' => $user->id]);
```

### Kontextinformationen hinzufügen

Übergeben Sie zusätzlich zu Nachricht ein Kontext-Array, um zusammengehörige Informationen zu erfassen.

```php theme={null}
Log::info('Login fehlgeschlagen.', [
    'user_id' => $user->id,
    'ip'      => $request->ip(),
    'reason'  => 'Passwort stimmt nicht überein',
]);
```

#### withContext() – gemeinsamen Kontext für einen Channel

Wenn Sie für einen bestimmten Channel jeden folgenden Log-Eintrag mit gemeinsamen Informationen versehen möchten, verwenden Sie `withContext()`. Gut geeignet für z. B. eine Request-ID.

```php theme={null}
Log::withContext(['request-id' => (string) Str::uuid()]);

// Alle folgenden Logs enthalten automatisch request-id
Log::info('Verarbeitung beginnt.');
Log::error('Es ist ein Fehler aufgetreten.');
```

#### shareContext() – gemeinsamen Kontext für alle Channels

`withContext()` wirkt nur auf einen Channel. `shareContext()` verteilt den Kontext auf alle Channels.

```php theme={null}
Log::shareContext(['app-version' => config('app.version')]);
```

## Channels konfigurieren

### Der stack-Channel – gleichzeitig in mehrere Ziele schreiben

Mit `stack` schreibt ein einziger Log-Aufruf in mehrere Channels.

```php theme={null}
// config/logging.php
'channels' => [
    'stack' => [
        'driver'   => 'stack',
        'channels' => ['daily', 'slack'],
    ],

    'daily' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/laravel.log'),
        'level'  => env('LOG_LEVEL', 'debug'),
        'days'   => 14,
    ],

    'slack' => [
        'driver'   => 'slack',
        'url'      => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji'    => env('LOG_SLACK_EMOJI', ':boom:'),
        'level'    => 'critical',
    ],
],
```

Mit dieser Konfiguration landen alle Logs ab `debug` in `daily`, und nur `critical` oder schlimmer geht zusätzlich an `slack`.

<Tip>
  In der Produktion empfiehlt sich für den `slack`-Channel das Level `error` oder `critical`.
  Werden zu triviale Meldungen nach Slack gesendet, verschwinden wichtige Alarme in der Nachrichtenflut.
</Tip>

### daily – Log-Rotation

Der `daily`-Channel rotiert Logs pro Tag und löscht ältere Dateien automatisch.

```php theme={null}
'daily' => [
    'driver' => 'daily',
    'path'   => storage_path('logs/laravel.log'),
    'level'  => env('LOG_LEVEL', 'debug'),
    'days'   => env('LOG_DAILY_DAYS', 14), // 14 Tage vorhalten
],
```

<Warning>
  Ein kleiner Wert bei `days` lässt Logs früh verschwinden.
  Sorgen Sie in der Produktion für eine ausreichende Aufbewahrungszeit zur Fehleranalyse.
</Warning>

### Fehlerbenachrichtigungen an Slack

Erstellen Sie eine [Incoming Webhook URL](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) in Slack und hinterlegen Sie sie in der `.env`.

```ini theme={null}
LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
```

```php theme={null}
// config/logging.php
'slack' => [
    'driver'   => 'slack',
    'url'      => env('LOG_SLACK_WEBHOOK_URL'),
    'username' => 'Laravel Error Bot',
    'emoji'    => ':fire:',
    'level'    => 'error',
],
```

Ergänzen Sie den `slack`-Channel im `stack`-Channel und setzen Sie `LOG_CHANNEL=stack`, um bei Fehlern automatische Benachrichtigungen zu erhalten.

### In einen bestimmten Channel schreiben

Mit `Log::channel()` wählen Sie den Ziel-Channel explizit aus.

```php theme={null}
// Nur an slack schreiben
Log::channel('slack')->error('Der Zahlungsdienst antwortet nicht.');

// Gleichzeitig an mehrere Channels
Log::stack(['daily', 'slack'])->critical('Verbindung zur Datenbank fehlgeschlagen.');
```

## On-Demand-Channels

Mit `Log::build()` erzeugen Sie einen Channel spontan, ohne ihn in der Konfigurationsdatei zu definieren.
Praktisch für Tests oder temporäre Log-Ziele.

```php theme={null}
use Illuminate\Support\Facades\Log;

$channel = Log::build([
    'driver' => 'single',
    'path'   => storage_path('logs/import-' . now()->format('Ymd') . '.log'),
]);

Log::stack([$channel])->info('CSV-Import beginnt.');
```

## Praxisbeispiele

### Middleware mit Request-ID

Wenn Sie allen Logs eine gemeinsame Request-ID hinzufügen, lässt sich der Verlauf einer einzelnen Anfrage leicht nachvollziehen.

<Steps>
  <Step title="Middleware erzeugen">
    ```shell theme={null}
    php artisan make:middleware AssignRequestId
    ```
  </Step>

  <Step title="handle() implementieren">
    ```php theme={null}
    <?php

    namespace App\Http\Middleware;

    use Closure;
    use Illuminate\Http\Request;
    use Illuminate\Support\Facades\Log;
    use Illuminate\Support\Str;
    use Symfony\Component\HttpFoundation\Response;

    class AssignRequestId
    {
        public function handle(Request $request, Closure $next): Response
        {
            $requestId = (string) Str::uuid();

            Log::withContext(['request-id' => $requestId]);

            $response = $next($request);

            $response->headers->set('X-Request-Id', $requestId);

            return $response;
        }
    }
    ```
  </Step>

  <Step title="Middleware registrieren">
    Als globale Middleware in `bootstrap/app.php` registrieren.

    ```php theme={null}
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(\App\Http\Middleware\AssignRequestId::class);
    })
    ```
  </Step>
</Steps>

Ab jetzt enthalten alle Log-Einträge automatisch die `request-id`.

```
[2026-03-01 12:00:00] local.INFO: Nutzer hat sich angemeldet. {"request-id":"550e8400-...","user_id":1}
[2026-03-01 12:00:00] local.INFO: Dashboard wird angezeigt. {"request-id":"550e8400-..."}
```

### Deprecation-Warnungen loggen

Sie können Warnungen zu veralteten PHP- oder Laravel-Funktionen protokollieren.

```php theme={null}
// config/logging.php
'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace'   => env('LOG_DEPRECATIONS_TRACE', false),
],
```

In der `.env` legen Sie den Channel fest.

```ini theme={null}
LOG_DEPRECATIONS_CHANNEL=daily
```

## Laravel Pail – Logs in Echtzeit anzeigen

[Laravel Pail](https://github.com/laravel/pail) ist ein Entwicklungs-Tool, das Application-Logs live im Terminal darstellt.

<Info>
  Für Pail benötigen Sie die PHP-Erweiterung [PCNTL](https://www.php.net/manual/de/book.pcntl.php).
</Info>

### Installation

```shell theme={null}
composer require --dev laravel/pail
```

### Grundlegende Nutzung

```shell theme={null}
# Logs live verfolgen
php artisan pail

# Ausführliche Anzeige (ohne Kürzung)
php artisan pail -v

# Inklusive Stacktrace
php artisan pail -vv
```

### Logs filtern

```shell theme={null}
# Nach Stichwort filtern
php artisan pail --filter="QueryException"

# Nur nach Nachrichtentext filtern
php artisan pail --message="Login"

# Nach Log-Level filtern
php artisan pail --level=error

# Nur Logs eines bestimmten Nutzers
php artisan pail --user=1
```

## Zusammenfassung

<AccordionGroup>
  <Accordion title="Log-Level richtig wählen">
    | Level       | Wann verwenden?                                                |
    | ----------- | -------------------------------------------------------------- |
    | `emergency` | Kritischer Ausfall, das gesamte System ist unbrauchbar         |
    | `alert`     | Ein Mensch muss sofort eingreifen                              |
    | `critical`  | Zentrale Funktionen sind ausgefallen                           |
    | `error`     | Unerwarteter Laufzeitfehler, Reaktion erforderlich             |
    | `warning`   | Veraltete Nutzung oder unerwartete Daten – zu beachten         |
    | `notice`    | Normal, aber protokollierenswert                               |
    | `info`      | Nutzeraktionen und Business-Events                             |
    | `debug`     | Detaillierte Debug-Infos (in der Produktion meist nicht nötig) |
  </Accordion>

  <Accordion title="Wahl des Channels">
    * **Entwicklungsumgebung**: `single` oder `daily` in Dateien schreiben.
    * **Produktion**: `stack` mit `daily` (Dateipersistenz) und `slack` (Fehlermeldungen) kombinieren.
    * **Spezielle Logs**: Mit `Log::build()` einen On-Demand-Channel für eine separate Datei anlegen.
    * **Echtzeit-Monitoring**: `php artisan pail` im Terminal.
  </Accordion>

  <Accordion title="Hinweise für die Produktion">
    * `debug`-Logs können sensible Informationen enthalten. In der Produktion empfiehlt sich `LOG_LEVEL=error` oder höher.
    * Rotieren Sie Log-Dateien regelmäßig, damit die Festplatte nicht volläuft (Option `days` des `daily`-Channels).
    * Achten Sie bei Slack o. Ä. auf Rate Limits. Legen Sie den Level so, dass nur wichtige Fehler benachrichtigen.
  </Accordion>
</AccordionGroup>


## Related topics

- [Einen MCP-Server mit Laravel bauen](/de/advanced/mcp-server.md)
- [Einführung in Laravel Nightwatch](/de/blog/nightwatch-introduction.md)
- [Laravel Pulse](/de/pulse.md)
- [Events](/de/packages/laravel-copilot-sdk/events.md)
- [Fehlerbehandlung](/de/error-handling.md)