תיעוד מובנה

Triggerfish משתמש בתיעוד מובנה עם רמות חומרה, סיבוב קבצים ופלט ניתן להגדרה. כל רכיב -- השער, האורקסטרטור, לקוח MCP, ספקי LLM, מנוע המדיניות -- מתעד דרך logger מאוחד. משמעות הדבר שמקבלים זרם יומן יחיד ועקבי ללא קשר למקור האירוע.

רמות יומן

הגדרת logging.level שולטת בכמות הפירוט שנלכד:

ערך תצורה	חומרה	מה מתועד
quiet	ERROR בלבד	קריסות וכשלים קריטיים
normal (ברירת מחדל)	INFO ומעלה	אתחול, חיבורים, אירועים משמעותיים
verbose	DEBUG ומעלה	קריאות כלים, החלטות מדיניות, בקשות ספק
debug	TRACE (הכל)	עומסי בקשה/תגובה מלאים, הזרמה ברמת token

כל רמה כוללת את כל מה שמעליה. הגדרת verbose נותנת DEBUG, INFO ו-ERROR. הגדרת quiet משתיקה הכל חוץ משגיאות.

תצורה

הגדירו את רמת היומן ב-triggerfish.yaml:

logging:
  level: normal

זו התצורה היחידה הנדרשת. ברירות המחדל סבירות לרוב המשתמשים -- normal לוכד מספיק כדי להבין מה הסוכן עושה מבלי להציף את היומן ברעש.

פלט יומן

יומנים נכתבים לשני יעדים בו-זמנית:

• stderr -- ללכידת journalctl כאשר רצים כשירות systemd, או פלט טרמינל ישיר בפיתוח
• קובץ -- ~/.triggerfish/logs/triggerfish.log

כל שורת יומן עוקבת אחר פורמט מובנה:

[2026-02-17T14:30:45.123Z] [INFO] [gateway] WebSocket client connected
[2026-02-17T14:30:45.456Z] [DEBUG] [orch] Tool call: web_search {query: "deno sqlite"}
[2026-02-17T14:30:46.789Z] [ERROR] [provider] Anthropic API returned 529: overloaded

תגיות רכיב

התגית בסוגריים מזהה איזה תת-מערכת הפיקה את רשומת היומן:

תגית	רכיב
[gateway]	מישור בקרה WebSocket
[orch]	אורקסטרטור סוכן ושיגור כלים
[mcp]	לקוח MCP ופרוקסי שער
[provider]	קריאות ספק LLM
[policy]	מנוע מדיניות והערכת ווים
[session]	מחזור חיי סשן ושינויי זיהום
[channel]	מתאמי ערוצים (Telegram, Slack, וכו')
[scheduler]	משימות cron, טריגרים, webhooks
[memory]	פעולות מאגר זיכרון
[browser]	אוטומציית דפדפן (CDP)

סיבוב קבצים

קובצי יומן מסובבים אוטומטית למניעת שימוש בלתי מוגבל בדיסק:

• סף סיבוב: 1 MB לקובץ
• קבצים נשמרים: 10 קבצים מסובבים (סה"כ ~10 MB מקסימום)
• בדיקת סיבוב: בכל כתיבה
• שמות: triggerfish.1.log, triggerfish.2.log, ..., triggerfish.10.log

כאשר triggerfish.log מגיע ל-1 MB, הוא משתנה ל-triggerfish.1.log, triggerfish.1.log הקודם הופך ל-triggerfish.2.log, וכן הלאה. הקובץ הישן ביותר (triggerfish.10.log) נמחק.

כתיבות fire-and-forget

כתיבות קובץ אינן חוסמות. ה-logger לעולם אינו מעכב עיבוד בקשות כדי לחכות שכתיבת דיסק תושלם. אם כתיבה נכשלת -- דיסק מלא, שגיאת הרשאות, קובץ נעול -- השגיאה נבלעת בשקט.

זה מכוון. תיעוד לעולם לא צריך להפיל את האפליקציה או להאט את הסוכן. פלט stderr משמש כחלופה אם כתיבות קובץ נכשלות.

כלי קריאת יומן

כלי log_read נותן לסוכן גישה ישירה להיסטוריית יומנים מובנית. הסוכן יכול לקרוא רשומות יומן אחרונות, לסנן לפי תגית רכיב או חומרה ולאבחן בעיות מבלי לעזוב את השיחה.

פרמטר	סוג	נדרש	תיאור
lines	number	לא	מספר שורות יומן אחרונות להחזרה (ברירת מחדל: 100)
level	string	לא	סינון חומרה מינימלית (error, warn, info, debug)
component	string	לא	סינון לפי תגית רכיב (למשל, gateway, orch, provider)

שאלו את הסוכן שלכם "אילו שגיאות קרו היום" או "הראה לי יומני שער

אחרונים" -- כלי log_read מטפל בסינון ואחזור. :::

צפייה ביומנים

פקודות CLI

# צפייה ביומנים אחרונים
triggerfish logs

# הזרמה בזמן אמת
triggerfish logs --tail

# גישה ישירה לקובץ
cat ~/.triggerfish/logs/triggerfish.log

עם journalctl

כאשר Triggerfish רץ כשירות systemd, יומנים נלכדים גם ביומן:

journalctl --user -u triggerfish -f

Debug מול תיעוד מובנה

משתנה הסביבה TRIGGERFISH_DEBUG=1 עדיין נתמך לתאימות לאחור אך

תצורת logging.level: debug מועדפת. שניהם מייצרים פלט שקול -- תיעוד מלא ברמת TRACE של כל עומסי בקשה/תגובה ומצב פנימי. :::

קשור

• פקודות CLI -- הפניית פקודת triggerfish logs
• תצורה -- סכמת triggerfish.yaml מלאה