trustgraph/docs/tech-specs/logging-strategy.he.md

layout	title	parent
default	אסטרטגיית רישום (לוגינג) של TrustGraph	Hebrew (Beta)

אסטרטגיית רישום (לוגינג) של TrustGraph

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

סקירה כללית

TrustGraph משתמש במודול logging המובנה של Python עבור כל פעולות הרישום, עם תצורה מרכזית ושילוב אופציונלי של Loki לאיסוף יומנים. זה מספק גישה סטנדרטית וגמישה לרישום בכל רכיבי המערכת.

תצורה ברירת מחדל

רמת רישום

רמה ברירת מחדל: INFO ניתן להגדרה באמצעות: ארגומנט שורת הפקודה --log-level אפשרויות: DEBUG, INFO, WARNING, ERROR, CRITICAL

יעדי פלט

1. קונסולה (stdout): תמיד מופעלת - מבטיחה תאימות עם סביבות מבוססות קונטיינרים
2. Loki: איסוף יומנים מרכזי אופציונלי (מופעל כברירת מחדל, ניתן לביטול)

מודול רישום מרכזי

כל תצורת הרישום מנוהלת על ידי המודול trustgraph.base.logging, המספק: add_logging_args(parser) - מוסיף ארגומנטי שורת פקודה סטנדרטיים לרישום setup_logging(args) - מגדיר רישום מארגומנטים מנותחים

מודול זה משמש את כל רכיבי הצד-שרת: שירותים מבוססי AsyncProcessor API Gateway MCP Server

הנחיות יישום

1. אתחול רשומות

כל מודול צריך ליצור את הרשומות שלו באמצעות המודול __name__:

import logging

logger = logging.getLogger(__name__)

שם ה-logger משמש באופן אוטומטי כתווית ב-Loki לצורך סינון וחיפוש.

2. אתחול שירות

כל השירותים בצד השרת מקבלים באופן אוטומטי הגדרות רישום דרך המודול המרכזי:

from trustgraph.base import add_logging_args, setup_logging
import argparse

def main():
    parser = argparse.ArgumentParser()

    # Add standard logging arguments (includes Loki configuration)
    add_logging_args(parser)

    # Add your service-specific arguments
    parser.add_argument('--port', type=int, default=8080)

    args = parser.parse_args()
    args = vars(args)

    # Setup logging early in startup
    setup_logging(args)

    # Rest of your service initialization
    logger = logging.getLogger(__name__)
    logger.info("Service starting...")

3. ארגומנטים של שורת הפקודה

כל השירותים תומכים בארגומנטים אלה של רישום:

רמת רישום:

--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}

תצורת לוקי:

--loki-enabled              # Enable Loki (default)
--no-loki-enabled           # Disable Loki
--loki-url URL              # Loki push URL (default: http://loki:3100/loki/api/v1/push)
--loki-username USERNAME    # Optional authentication
--loki-password PASSWORD    # Optional authentication

דוגמאות:

# Default - INFO level, Loki enabled
./my-service

# Debug mode, console only
./my-service --log-level DEBUG --no-loki-enabled

# Custom Loki server with auth
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
             --loki-username admin --loki-password secret

4. משתני סביבה

תצורת Loki תומכת באפשרויות ברירת מחדל עבור משתני סביבה:

export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
export LOKI_USERNAME=admin
export LOKI_PASSWORD=secret

ארגומנטים משורת הפקודה גוברים על משתני סביבה.

5. שיטות עבודה מומלצות לרישום נתונים

שימוש ברמות רישום

DEBUG: מידע מפורט לצורך אבחון בעיות (ערכי משתנים, כניסה/יציאה מפונקציות) INFO: הודעות מידע כלליות (השירות התחיל, תצורה נטענה, נקודות ציון בעיבוד) WARNING: הודעות אזהרה למצבים שעלולים להיות מזיקים (תכונות מיושנות, שגיאות שניתן להתאושש מהן) ERROR: הודעות שגיאה לבעיות חמורות (פעולות שנכשלו, חריגות) CRITICAL: הודעות קריטיות לכשלים במערכת הדורשים התייחסות מיידית

פורמט ההודעה

# Good - includes context
logger.info(f"Processing document: {doc_id}, size: {doc_size} bytes")
logger.error(f"Failed to connect to database: {error}", exc_info=True)

# Avoid - lacks context
logger.info("Processing document")
logger.error("Connection failed")

שיקולי ביצועים

# Use lazy formatting for expensive operations
logger.debug("Expensive operation result: %s", expensive_function())

# Check log level for very expensive debug operations
if logger.isEnabledFor(logging.DEBUG):
    debug_data = compute_expensive_debug_info()
    logger.debug(f"Debug data: {debug_data}")

6. רישום מובנה עם לוקי

עבור נתונים מורכבים, השתמש ברישום מובנה עם תגיות נוספות עבור לוקי:

logger.info("Request processed", extra={
    'tags': {
        'request_id': request_id,
        'user_id': user_id,
        'status': 'success'
    }
})

תגיות אלו הופכות לתויות הניתנות לחיפוש ב-Loki, בנוסף לתויות אוטומטיות: severity - רמת לוג (DEBUG, INFO, WARNING, ERROR, CRITICAL) logger - שם מודול (מתוך __name__)

7. רישום חריגות

תמיד כללו עקבות מחסנית עבור חריגות:

try:
    process_data()
except Exception as e:
    logger.error(f"Failed to process data: {e}", exc_info=True)
    raise

8. שיקולים בנושא רישום אסינכרוני

מערכת הרישום משתמשת במטפלים (handlers) בתור לא חוסמים עבור Loki: פלט לקונסולה הוא סינכרוני (מהיר) פלט ל-Loki מוצג בתור עם מאגר של 500 הודעות ניתוב רקע מטפל בהעברת נתונים ל-Loki אין חסימה של קוד האפליקציה הראשי

import asyncio
import logging

async def async_operation():
    logger = logging.getLogger(__name__)
    # Logging is thread-safe and won't block async operations
    logger.info(f"Starting async operation in task: {asyncio.current_task().get_name()}")

אינטגרציה עם לוקי

ארכיטקטורה

מערכת הרישום משתמשת בפונקציות המובנות של Python, QueueHandler ו-QueueListener, עבור אינטגרציה לא חוסמת עם לוקי:

1. QueueHandler: הודעות רישום מוכנסות לתור של 500 הודעות (לא חוסם).
2. Background Thread: QueueListener שולח הודעות רישום ללוקי באופן אסינכרוני.
3. Graceful Degradation: אם לוקי אינו זמין, רישום לקונסולה ממשיך.

תגיות אוטומטיות

כל הודעת רישום שנשלחת ללוקי כוללת: processor: זהות המעבד (לדוגמה, config-svc, text-completion, embeddings). severity: רמת הרישום (DEBUG, INFO, וכו'). logger: שם המודול (לדוגמה, trustgraph.gateway.service, trustgraph.agent.react.service).

תגיות מותאמות אישית

הוספת תגיות מותאמות אישית באמצעות הפרמטר extra:

logger.info("User action", extra={
    'tags': {
        'user_id': user_id,
        'action': 'document_upload',
        'collection': collection_name
    }
})

שאילתת יומנים ב-Loki

# All logs from a specific processor (recommended - matches Prometheus metrics)
{processor="config-svc"}
{processor="text-completion"}
{processor="embeddings"}

# Error logs from a specific processor
{processor="config-svc", severity="ERROR"}

# Error logs from all processors
{severity="ERROR"}

# Logs from a specific processor with text filter
{processor="text-completion"} |= "Processing"

# All logs from API gateway
{processor="api-gateway"}

# Logs from processors matching pattern
{processor=~".*-completion"}

# Logs with custom tags
{processor="api-gateway"} | json | user_id="12345"

ניוון מבוקר (Graceful Degradation)

אם Loki אינו זמין או python-logging-loki אינו מותקן: הודעת אזהרה מוצגת לקונסולה רישום לקונסולה ממשיך כרגיל היישום ממשיך לפעול אין לוגיקה של ניסיון חוזר לחיבור ל-Loki (כשל מהיר, ניוון מבוקר)

בדיקות (Testing)

במהלך הבדיקות, שקלו להשתמש בתצורת רישום שונה:

# In test setup
import logging

# Reduce noise during tests
logging.getLogger().setLevel(logging.WARNING)

# Or disable Loki for tests
setup_logging({'log_level': 'WARNING', 'loki_enabled': False})

אינטגרציה של ניטור

פורמט סטנדרטי

כל הרישומים משתמשים בפורמט עקבי:

2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed

מרכיבי פורמט: חותמת זמן (פורמט ISO עם מילישניות) שם הלוגר (נתיב מודול) רמת לוג הודעה

שאילתות לוקי לניטור

שאילתות ניטור נפוצות:

# Error rate by processor
rate({severity="ERROR"}[5m]) by (processor)

# Top error-producing processors
topk(5, count_over_time({severity="ERROR"}[1h]) by (processor))

# Recent errors with processor name
{severity="ERROR"} | line_format "{{.processor}}: {{.message}}"

# All agent processors
{processor=~".*agent.*"} |= "exception"

# Specific processor error count
count_over_time({processor="config-svc", severity="ERROR"}[1h])

שיקולי אבטחה

לעולם אין לרשום מידע רגיש (סיסמאות, מפתחות API, נתונים אישיים, טוקנים) לנקות קלט משתמש לפני רישום להשתמש במחזירי מקום עבור שדות רגישים: user_id=****1234 אימות לוקי: השתמשו ב---loki-username ו---loki-password עבור פריסות מאובטחות העברה מאובטחת: השתמשו ב-HTTPS עבור כתובת ה-URL של לוקי בסביבת ייצור: https://loki.prod:3100/loki/api/v1/push

תלויות

מודול הרישום המרכזי דורש: python-logging-loki - עבור אינטגרציה עם לוקי (אופציונלי, ירידה הדרגתית אם חסר)

כלול כבר ב-trustgraph-base/pyproject.toml ו-requirements.txt.

נתיב מעבר

עבור קוד קיים:

1. שירותים שכבר משתמשים ב-AsyncProcessor: אין צורך בשינויים, תמיכה בלוקי היא אוטומטית
2. שירותים שאינם משתמשים ב-AsyncProcessor (api-gateway, mcp-server): כבר עודכנו
3. כלי שורת פקודה: מחוץ לתחום - המשיכו להשתמש ב-print() או ברישום פשוט

מ-print() לרישום:

# Before
print(f"Processing document {doc_id}")

# After
logger = logging.getLogger(__name__)
logger.info(f"Processing document {doc_id}")

סיכום הגדרות

ארגומנט	ברירת מחדל	משתנה סביבה	תיאור
--log-level	INFO	-	רמת רישום עבור קונסולה ו-Loki
--loki-enabled	True	-	הפעלת רישום Loki
--loki-url	http://loki:3100/loki/api/v1/push	LOKI_URL	נקודת קצה (endpoint) של Loki לשליחה
--loki-username	None	LOKI_USERNAME	שם משתמש לאימות ב-Loki
--loki-password	None	LOKI_PASSWORD	סיסמה לאימות ב-Loki