TaskMonkey Handbuch

Logging in Handlern

Eigene Log-Einträge und Metriken aus deinen Tool-Handlern.

Jeder Tool-Aufruf wird automatisch als Ausführungs-Eintrag gespeichert: Tool-Name, Args, Dauer, Status, Memory-Verbrauch, Token-Nutzung. Das passiert ohne dein Zutun.

Zusätzlich kannst du in deinen Handlern eigene Log-Zeilen und Metriken schreiben — sie landen im selben Eintrag und sind später im UI und in tm monitor / tm logs zu sehen.

Logger im Kontext

Im Handler bekommst du einen Logger als Teil von $ctx:

'handler' => function (array $results, array $args, array $ctx): array {
    $logger = $ctx['logger'];

    $logger->info('Suche Bestellung ' . $args['id']);

    if (empty($args['id'])) {
        $logger->error('Keine ID angegeben');
        return ['error' => 'id required'];
    }

    $logger->success('Bestellung gefunden');
    return ['id' => $args['id'], /* … */];
},

Log-Methoden

Methode Wofür
$logger->info('…') Normale Status-Meldung
$logger->success('…') Erfolgsmeldung
$logger->warning('…') Etwas ist nicht ideal, aber kein Fehler
$logger->error('…') Fehler — Handler kann trotzdem weiterlaufen

Alle Zeilen landen im Log-Buffer des Tool-Aufrufs und werden zusammen mit dem Eintrag gespeichert.

Geschäftliche Metriken

Wenn dein Tool Zahlen produziert, die dich später interessieren (importierte Datensätze, gefundene Treffer, Fehler-Anzahl …), nutze Metriken — sie sind besser durchsuchbar als Log-Text.

$logger->addMetric('imported_orders', count($orders));
$logger->addMetric('skipped', $skippedCount);

// oder mehrere auf einmal:
$logger->addMetrics([
    'imported_orders' => count($orders),
    'skipped' => $skippedCount,
    'duration_per_item_ms' => $perItem,
]);

Metriken landen als JSON im business_metrics-Feld des Eintrags und sind in der Ausführungs-Übersicht filterbar.

Was wird automatisch geloggt

Pro Tool-Aufruf — du musst nichts tun:

Feld Inhalt
tool_name Name des Tools
tenant, chat_id Workspace und Chat-Kontext
entry_type chat, scheduled_task, monkey, email
started_at, completed_at Zeitstempel mit µs-Präzision
duration_ms Laufzeit
status running, success, error, timeout
error_message bei Fehlern
tokens_prompt, tokens_completion, tokens_total LLM-Token-Verbrauch (bei chat/monkey)
memory_peak_mb Spitzenwert während des Calls
api_calls_count Anzahl HTTP-Calls aus dem Tool

Wo sehe ich die Logs?

Drei Wege:

Wo Wofür
Manage-UI unter /manage/tasks Klick auf einen Task → Reiter „Ausführungen" zeigt alle historischen Runs mit Logs und Metriken
tm monitor Live-Stream aller Tool-Ausführungen, strukturiert pro Tool. Siehe tm monitor
tm logs Roher Log-Stream inklusive deiner info/error-Zeilen. Siehe tm logs

Tipps

  • Keine Geheimnisse loggen. Token, Passwörter, Personendaten gehören nicht ins Log
  • Nicht jeden Schritt loggen — drei Zeilen pro Aufruf reichen meistens (Start, Schlüssel-Entscheidung, Ergebnis)
  • Bei Schleifen mit addMetric statt eine Log-Zeile pro Iteration — sonst läuft der Buffer voll
  • Fehler verlieren keine Logs — auch wenn dein Handler eine Exception wirft, bleiben die zuvor geloggten Zeilen erhalten

Aufbewahrung

  • Detail-Log-Buffer (Text der einzelnen Zeilen): 3 Tage
  • Eintrags-Metadaten + Metriken: 90 Tage

Danach werden die Einträge automatisch aufgeräumt. Wichtige geschäftliche Metriken (Import-Zahlen, Erfolgsraten) gehörten in deine eigene DB, wenn du sie länger brauchst.

Zuletzt aktualisiert: 2026-04-19