SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor

אירוח עצמי של Langfuse: מדריך מלא לניטור סוכני AI

למדו איך להריץ Langfuse על שרת פרטי. המדריך מפרט הגדרות זיכרון מינימליות, שימוש ב-pinned image tags, הגדרת TLS, ניהול ClickHouse למניעת מילוי דיסק וביצוע גיבויים תקינים.

למה בכלל לבצע מעקב (trace) אחר סוכן AI

אתם מארחים את Langfuse באופן עצמאי כדי לראות מה הסוכן שלכם באמת עשה במהלך הרצה. Langfuse הוא כלי בקוד פתוח לניטור (observability) של מודלי שפה גדולים (LLM). הוא מתעד כל prompt, כל תגובה של המודל, כל קריאה לכלי וכל token, ולאחר מכן מקבץ אותם תחת trace אחד שניתן לפתוח ולקרוא. הרצת הכלי על גבי ה-VPS שלכם מבטיחה שה-prompts הללו לעולם לא עוזבים שרת שנמצא בשליטתכם.

הסיבה להשקיע בכך ברורה. לא ניתן לתקן בעיית עלות או בעיית איכות שאינכם יכולים לראות. חשבונית מספק השירות תגיד לכם שיום שלישי עלה פי ארבעה מיום שני. ה-trace יגיד לכם איזו הרצה של הסוכן גרמה לכך, איזה prompt תפח ל-40,000 tokens, ואיזו לולאת ניסיונות חוזרים (retry loop) רצה תשע פעמים לפני שוויתרה. החשבונית נותנת לכם את המספר. ה-trace נותן לכם את הקוד שיצר אותו.

במדריך זה נעשה שימוש בשלושה מונחים. trace הוא הרצה מקצה לקצה של הסוכן שלכם. observation הוא צעד בודד בתוך אותה הרצה: span עבור קוד רגיל, או generation עבור קריאה למודל. score הוא מספר המוצמד ל-trace, שניתן על ידי סקירה אנושית או מעריך אוטומטי. Langfuse תומך ב-OpenTelemetry (OTel), התקן הניטרלי לניטור מבוזר, כך שכל כלי אינסטרומנטציה שכבר קיים אצלכם יכול להצביע עליו.

מה באמת פועל ב־self-hosting של Langfuse

Langfuse v4 אינו container יחיד. הוא מורכב משני application containers ומארבעה שירותי אחסון, וב־VPS יחיד כל השישה פועלים אצלכם.

  • langfuse-web מספק את ממשק האינטרנט ואת API הקליטה.
  • langfuse-worker מרוקן את התור ברקע. הוא מנתח קבוצות קליטה, מחשב עלויות ומפעיל את משימת השמירה הלילית.
  • Postgres שומר נתונים טרנזקציוניים, כגון משתמשים, ארגונים, פרויקטים, מפתחות API ו־prompts.
  • ClickHouse שומר את נתוני ה־trace עצמם, כלומר observations ו־scores. זהו column store שנבנה עבור שאילתות אנליטיות, ולכן dashboard על יותר ממאה מיליון שורות עדיין מחזיר תשובה במהירות.
  • Redis הוא התור וה־cache שנמצאים בין ה־web ל־worker.
  • MinIO מספק object storage תואם S3 על השרת. הוא שומר כל אירוע גולמי נכנס, וכן כל מדיה שמצורפת אליו.

Langfuse מפרסם משאבי מינימום עבור כל רכיב שהוא מפעיל. התרשים מציג את שלושת הרכיבים שמבצעים את העבודה.

תרשיםLangfuse published minimum resources per component
הנתונים שמאחורי התרשים
[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

ClickHouse לבדו דורש 8 GiB של זיכרון. ה־web container וה־worker דורשים 4 GiB כל אחד. אלה ערכי המינימום שפורסמו עבור 3 הרכיבים בתרשים. באותו עמוד מצוינים גם 4 GiB עבור Postgres, ‏1.5 GiB עבור Redis או Valkey ו־4 GiB עבור MinIO, ולכן דרישות המינימום של כל ששת הרכיבים מסתכמות ב־25.5 GiB. המדריך הרשמי של הפרויקט ל־Docker Compose ממליץ על לפחות 4 ליבות, 16 GiB של זיכרון וכ־100 GiB של אחסון למכונה יחידה. זה פחות מסכום דרישות המינימום של הרכיבים, ולכן יש להתייחס ל־16 GiB כדרישה המזערית לשרת Compose משותף, ולא כמרווח פנוי.

אל תנסו להפעיל זאת בתוכנית של 2 GiB. ClickHouse עולה, מקבל כתיבות במשך זמן מה, ולאחר מכן קורס במהלך מיזוג ברקע, משום שמיזוג טוען חלקים גדולים של טבלה לזיכרון. תראו את docker compose ps מדווח על container של clickhouse כ־restarting, את dmesg עם שורה כגון Out of memory: Killed process 1234 (clickhouse-serv), וכל dashboard של Langfuse יחזיר 500. בעומס נמוך יותר ClickHouse מסרב לשאילתה במקום זאת ומתעד DB::Exception: Memory limit (total) exceeded. יש לתכנן לפי 16 GiB. אם אותו VPS אמור להפעיל שירותים נוספים, הקצו להם משאבים בנפרד, משום שגם stack קל יחסית כמו סביבת עבודה עצמית של AFFiNE דורש כמה GiB משלו, ו־ClickHouse לא יפנה עבורכם זיכרון.

פריסת Langfuse באמצעות Docker Compose

שכפלו את המאגר. המחסנית, החיבורים בין השירותים וסביבת ברירת המחדל נמצאים כולם ב־docker-compose.yml.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

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

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY חייב להיות באורך 256 סיביות, כשהוא כתוב כ־64 תווי hexadecimal. זה בדיוק הפלט של openssl rand -hex 32. הוא מצפין ערכים רגישים במנוחה, כולל מפתחות של ספקי LLM שאתם שומרים במופע. אם תשנו אותו לאחר שכבר קיימים נתונים, לא יהיה ניתן לפענח עוד את הרשומות האלה. לכן יש להתייחס אליו כאל ערך קבוע כבר מהאתחול הראשון. SALT משמש לגיבוב מפתחות ה־API של Langfuse, ולכן שינוי שלו מבטל כל מפתח שהסוכנים שלכם כבר משתמשים בו.

לאחר מכן הגדירו את POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH ו־MINIO_ROOT_PASSWORD. הסיסמה של MinIO מופיעה בארבעה מקומות: פעם אחת בתור MINIO_ROOT_PASSWORD, ולאחר מכן שוב בתור LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY ו־LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. אם תפספסו אחד מהם, MinIO ידחה את הלקוח באמצעות SignatureDoesNotMatch. השגיאה תופיע בלוג של ה־worker, אף שממשק האינטרנט עדיין ייראה תקין. שמירת הערכים האלה בקובץ env במקום בקובץ compose שנמצא במעקב היא התבנית המתוארת ב־קובצי env וסודות ב־Docker Compose.

קיבוע תגיות התמונות לפני ההתחלה

הקובץ שסופק משתמש ב־docker.langfuse.com/langfuse/langfuse:4 וב־docker.langfuse.com/langfuse/langfuse-worker:4. תגיות אלה משתנות. Langfuse מפעיל אוטומטית את הגירות של Postgres ושל ClickHouse בעת האתחול. לכן docker compose pull שגרתי כעבור כמה חודשים הופך לגירת סכימה לא מתוכננת במסד נתונים שלא גיביתם באותו בוקר. קבעו את שתי התמונות לאותה גרסה ב־docker-compose.override.yml. Compose ממזג קובץ זה מעל הקובץ שסופק, כך ש־git pull מאוחר יותר לא ידרוס את השינויים שלכם. אותן תמונות מפורסמות גם ב־Docker Hub, ומשם קובץ ה־override שלהלן מושך אותן.

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.72.0
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.72.0

גרסה 4.3.1 הייתה גרסת 4.3 הנוכחית באוגוסט 2026. מאז פורסמו גרסאות בקצב מהיר, ו־v4.56.0 הייתה הגרסה האחרונה ב־GitHub נכון ל־11 באוקטובר 2026. קובץ ה־override שלמעלה משתמש ב־v4.72.0, שהייתה הגרסה האחרונה ב־GitHub נכון ל־31 באוקטובר 2026. בדקו את דף הגרסאות של הפרויקט ב־GitHub, קבעו את הגרסה הנוכחית ביום הפריסה, ולאחר מכן עדכנו את המספר בכוונה. גם חלק מתמונות האחסון בקובץ שסופק ראויות לאותו טיפול, משום שגם התגיות שלהן משתנות. postgres:17 (ברירת המחדל של משתנה POSTGRES_VERSION) ו־redis:7 עוקבות אחר גרסה ראשית. הקובץ שסופק משתמש כעת בתגית גרסה מדויקת עבור docker.io/clickhouse/clickhouse-server, וכך מקבע גרסה מדויקת של ClickHouse. כלל זה אינו ייחודי ל־Langfuse: מעקב אימוני openGym באירוח עצמי משתמש בחלק קטן מהמחסנית הזו ועדיין דורש תגית git מוגדרת, משום שכל רכיב שמבצע הגירה של מסד הנתונים שלו בעת האתחול עלול להפוך משיכת עדכונים רגילה לשינוי סכימה.

הפעילו את המחסנית.

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

באתחול הראשון מתבצעות הגירות, לכן המתינו שתיים או שלוש דקות לפני שתצפו למענה כלשהו. קונטיינר האינטרנט רושם Ready לאחר שהוא עולה. docker compose ps אמור להציג שישה שירותים במצב running. אם קונטיינר מופעל מחדש בלולאה, הסיבה תופיע בלוג שלו. הגירות ClickHouse מתבצעות בעת הפעלת קונטיינר האינטרנט, לכן CLICKHOUSE_MIGRATION_URL שגוי יופיע ב־docker compose logs langfuse-web ולא בלוג של ה־worker שאתם מנטרים. משתנה זה משתמש בפרוטוקול ClickHouse native בפורט 9000, ולא בפורט HTTP 8123. הפנייתו ל־8123 מונעת מקונטיינר האינטרנט להשלים את הגירות האתחול. ה־worker מפעיל את הגירות הרקע האיטיות יותר, ולכן הדיווחים עליהן נמצאים בלוג שלו.

בדקו את תקינות השירות מהמחשב עצמו.

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

קריאת /api/public/health פשוטה מוכיחה רק שתהליך ה־API פעיל, משום שכברירת מחדל היא אינה בודקת את מסד הנתונים. הצורה failIfDatabaseUnavailable=true היא זו שכדאי להפנות אליה מערכת ניטור, והיא מחזירה 503 כאשר מסד הנתונים אינו נגיש. /api/public/ready מחזירה 200 כאשר קונטיינר האינטרנט מוכן לקבל תעבורה, ו־500 לאחר שנמסר לו שעליו להיסגר. שתיהן בדיקות HTTP רגילות, ולכן דף סטטוס של Uptime Kuma יכול לנטר אותן ולהודיע לכם שהמחסנית מושבתת לפני שהסוכנים שלכם יבחינו בכך.

הציבו TLS לפני השירות וסגרו את הפורטים הנוספים

קובץ ה־compose שסופק מפרסם את 3000:3000 עבור קונטיינר ה־web ואת 9090:9000 עבור MinIO. שניהם מאזינים בכל הממשקים. בכתובת IP ציבורית, המשמעות היא שכל מי שסורק את פורט 3000 מגיע לדף ההרשמה שלכם, וכל מי שסורק את פורט 9090 מתקשר עם ה־bucket שמכיל את ה־prompts הגולמיים שלכם.

כלל firewall לבדו אינו סוגר אותם. Docker כותב כללי DNAT משלו בטבלת nat, וכללים אלה נבדקים לפני שכללי הסינון של ufw רואים את החבילה. לכן ufw deny 3000 משאיר את הפורט המפורסם פתוח. הבעיה נפוצה מספיק כדי שיש לה מדריך משלה: מדוע פורטים שפורסמו על ידי Docker עוקפים את ufw. הגדירו bind ל־loopback בקובץ ה־override שלכם. השתמשו ב־!override עם Docker Compose 2.24.4 או גרסה מאוחרת יותר כדי להחליף את הפורטים המפורסמים; רשימה רגילה מתמזגת עם ה־bindings המקוריים.

services:
  langfuse-web:
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports: !override
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL חייב להיות הכתובת הציבורית המדויקת, כולל ה־scheme, משום שתהליך ההתחברות בונה את כתובת ה־callback מתוך הערך הזה. השאירו אותו כ־http://localhost:3000 מאחורי proxy עם HTTPS, ותהליך ההתחברות הלוך ושוב ישלח את הדפדפן לכתובת שאינו יכול להגיע אליה.

כעת הגדירו reverse proxy שיפנה אל 127.0.0.1:3000, ותנו לו לנהל את התעודה. עבור Traefik באותו פרויקט Compose, נַתבו אל langfuse-web:3000 דרך רשת ה־Compose, באמצעות ה־labels המוסברים ב־הפעלת כמה יישומים מאחורי reverse proxy יחיד של Traefik. Caddy מבצע את אותה משימה בשתי שורות אם Langfuse הוא השירות היחיד בשרת. אמתו באמצעות curl -sI https://langfuse.example.com/api/public/ready, ולאחר מכן ודאו ממחשב נוסף ש־curl http://YOUR_IP:3000 אינו יכול להתחבר.

יש הסתייגות אחת בנוגע ל־MinIO. Langfuse מוסר כתובות URL חתומות מראש המצביעות על נקודת הקצה הזו של S3, הן ל־SDK שמעלה מדיה והן לדפדפן שטוען אותה. לכן, אם אתם משתמשים ב־traces מולטימודליים הכוללים תמונות או שמע, MinIO שמוגבל ל־loopback ימנע העלאה של קבצים מצורפים ממחשבים אחרים או טעינה שלהם בדפדפן. קראו את דף התצורה של אחסון ה־blob לפני שתגדירו לו proxy, משום שנקודת הקצה שנכתבת ב־URL החתום מראש, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, חייבת להתאים לכתובת שאתם מפרסמים. Traces של טקסט רגיל אינם מושפעים.

צרו את החשבון בביקור הראשון, ולאחר מכן השאירו את המופע בשליטתכם. הגדירו את AUTH_DISABLE_SIGNUP=true לאחר יצירת החשבון, כדי שאדם זר שיגיע לדף לא יוכל להירשם כלל. ל־Langfuse יש גם LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, שמגביל את הגורמים שיכולים ליצור ארגונים, אך זו תכונה של Enterprise Edition והיא נכנסת לתוקף רק עם מפתח רישיון. אם אתם כבר מפעילים את Authentik כספק הזהויות העצמאי שלכם, Langfuse מקבל חיבור OIDC תקני, ולכן החשבונות נוצרים ונמחקים יחד עם שאר היישומים שלכם במקום להישמר ברשימת סיסמאות שמוכרת רק לשרת הזה.

שלחו את ה-trace הראשון

צרו פרויקט בממשק האינטרנט והעתיקו את המפתחות הציבורי והסודי שלו מהגדרות הפרויקט. ה-SDK של Python קורא 3 משתני סביבה.

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL הוא שם המשתנה ב-SDK v4, שפורסם במרץ 2026. קוד ישן ומדריכים ישנים משתמשים ב-LANGFUSE_HOST. אם ה-traces שלכם מגיעים אל Langfuse Cloud במקום אל השרת שלכם, הסיבה היא שכתובת הבסיס לא הוגדרה, משום שברירת המחדל מפנה אל המופע המתארח.

ה-SDK הנוכחי של Python v5 דורש Python 3.11 או גרסה מאוחרת יותר ו-Langfuse בגרסה v4.59.0 או גרסה מאוחרת יותר, והשרת המקובע לעיל עומד בדרישה זו.

pip install langfuse opentelemetry-instrumentation-anthropic anthropic
import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

הדקורטור @observe פותח observation סביב הפונקציה, לוכד את הארגומנטים ואת ערך ההחזרה שלה, ומקנן אותו תחת ה-observation שכבר פעיל, אם יש כזה. AnthropicInstrumentor הוא האינסטרומנטציה של OpenTelemetry עבור הלקוח של Anthropic, והוא הופך כל קריאה ל-messages.create ל-generation הכולל את שם המודל, את צריכת הטוקנים ואת זמן ההשהיה, ללא שינוי באתר הקריאה.

2 קריאות מבצעות את הבדיקות עבורכם. langfuse.auth_check() מחזירה False כאשר המפתחות שגויים או כאשר כתובת הבסיס שגויה. כך קל יותר לאתר את הבעיה במקום לתהות מדוע לוח הבקרה ריק. langfuse.flush() ממתינה עד שכל ה-spans שבתור נשלחים. תהליכים קצרי-חיים זקוקים לה, משום שה-SDK מאגד את הנתונים ברקע, וסקריפט שמסתיים מיד לוקח איתו את האצווה שטרם נשלחה. אם צוות שלם שולח traces ולא רק סקריפט אחד, הגדירו את 3 המשתנים האלה פעם אחת ב-gateway שדרכו כבר עוברים כל ה-agents, במקום להגדיר אותם ב-shell של כל אדם. כך מתקן OneCLI באירוח עצמי שומר על אינסטרומנטציה של ההרצות של כל העמיתים, בעוד שהמפתחות נשארים במקום אחד.

מדוע ClickHouse ממשיך לגדול?

Traces הם הנתונים שגדלים בקצב המהיר ביותר אצל רוב מי שמארחים מערכת בעצמם. כל הרצה של agent כותבת שורה אחת לכל שלב, והקלטים והפלטים נשמרים במלואם. לכן agent שמייצר הרבה פלט, עם prompts ארוכים, מייצר ביום הרבה יותר בתים מהיישום שעליו הוא מפקח. אם לא מטפלים בכך, ClickHouse ממלא את הדיסק. דיסק מלא מפסיק את קליטת הנתונים, ולא רק מאט אותה.

כאן גדלים שני דברים נפרדים, ולכל אחד מהם נדרש תיקון נפרד.

הראשון הוא נתוני ה־trace שלכם. התיקון הוא הגדרת השמירה. במופע שמנוהל באופן עצמאי, שמירת נתונים היא תכונה של Enterprise Edition ודורשת מפתח רישיון. ללא מפתח כזה, Langfuse שומר traces, observations, scores ומדיה ללא הגבלת זמן. לכן יש להקצות לכך נפח דיסק מתאים ולהסתמך על התראת הדיסק בסוף הסעיף הזה. עם רישיון, בעלי פרויקט ומנהלי מערכת פותחים את הגדרות הפרויקט ומגדירים את תקופת שמירת הנתונים בימים. Langfuse מקבל תקופה מינימלית של 3 ימים. לאחר מכן, משימה לילית מאתרת traces, observations, scores ונכסי מדיה שגילם חורג מהתקופה ומוחקת אותם מ־ClickHouse ומאחסון ה־blob, למעט מדיה המשויכת לפריטי dataset שנשמרו. למשימה נדרשת הרשאת DeleteObject על ה־bucket. להרשאות ה־root של MinIO בקובץ compose ברירת המחדל כבר יש הרשאה זו. המחיקה בלתי הפיכה, לכן הגדירו תחילה ייצוא לאחסון blob אם אתם זקוקים להיסטוריה ארוכת טווח. אל תכתבו ידנית סעיפי TTL בטבלאות של Langfuse עצמו. משימת השמירה היא ששומרת על סנכרון בין ClickHouse לבין ה־bucket, ו־TTL ידני מוחק רק צד אחד.

בחרו את התקופה לפי אופן השימוש בפועל. בדיקת עלויות ואיכות מתבצעת על נתונים בני ימים, ולא על נתונים בני חודשים. 30 ימים הם נקודת התחלה סבירה לצוות קטן. 14 ימים מספיקים אם אתם פותחים trace רק כאשר משהו מתקלקל.

השני הוא טבלאות יומן המערכת של ClickHouse עצמו. נקודה זו מפתיעה משתמשים רבים, משום שהדיסק ממשיך להתמלא לאחר הגדרת השמירה. ClickHouse כותב את trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log ו־latency_log לצורכי אבחון פנימיים. טבלאות אלה מגיעות ללא TTL, ו־Langfuse לעולם אינו קורא אותן. תחילה בדקו לאן הדיסק באמת התמלא.

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

הריצו את הפקודה באמצעות docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". אם טבלאות המערכת נמצאות בראש הרשימה, השביתו אותן באמצעות שכבת תצורה. ClickHouse ממזג בעת האתחול כל קובץ מתוך /etc/clickhouse-server/config.d/ מעל התצורה הראשית שלו.

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
    <latency_log remove="1"/>
</clickhouse>

בצעו לה mount והפעילו מחדש את ClickHouse.

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

פעולה זו עוצרת כתיבות חדשות. שורות שכבר נמצאות בדיסק נשארות בו, לכן יש לפנות את המקום במפורש באמצעות DROP TABLE IF EXISTS system.trace_log, ולבצע את אותה פעולה עבור כל טבלה שהסרתם. אם אתם מעדיפים לשמור את נתוני האבחון, החלופה היא להגדיר TTL מחמיר בכל טבלה במקום remove="1". מסמכי קנה המידה של Langfuse מפרטים כיצד לעשות זאת. הוראות TTL אלה חלות רק כאשר טבלת מערכת נוצרת לראשונה. לכן, בהתקנה קיימת, אותם מסמכים מסבירים גם כיצד להחיל את ההגדרות על הטבלאות הקיימות.

כדאי להכיר גם טבלה נוספת. blob_storage_file_log עוקבת אחר קובצי האירועים שהועלו ל־bucket שלכם. אם הגדרתם גם מדיניות מחזור חיים על ה־bucket, הגדירו לטבלה TTL תואם, כדי ששני הצדדים לא יצאו מסנכרון.

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

הגדירו גם התראת df -h פשוטה על דיסק הנתונים. Traces אינם גדלים בקצב אחיד. הם גדלים ביום שבו אתם מעלים agent חדש, והסימן הראשון לכך לא אמור להיות כשל בקליטת הנתונים.

גיבוי Postgres ו־ClickHouse

לגיבוי של Langfuse יש שלושה חלקים. Postgres שומר את המשתמשים, הארגונים, הפרויקטים ומפתחות ה־API. ClickHouse שומר את ה־traces. MinIO שומר את האירועים הגולמיים. אם תשחזרו רק את Postgres, תקבלו התחברות תקינה ללא היסטוריה. אם תשחזרו רק את ClickHouse, תקבלו היסטוריה שאיש אינו יכול להתחבר כדי לצפות בה. ההפרדה הזו אינה ייחודית ל־Langfuse, וגם מערכת התמיכה Chatwoot באירוח עצמי בנויה באופן דומה: dump של Postgres שנלקח ללא תיקיית ה־uploads משחזר שיחות שכל הקבצים המצורפים להן חסרים.

Postgres הוא pg_dump רגיל, כפי שמשתמשים בו במסמכי הגיבוי של Langfuse להתקנת Docker.

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

יש לטפל ב־ClickHouse בזהירות רבה יותר, משום שהעתקת תיקיית נתונים פעילה בזמן שמתבצעים merge-ים אינה יוצרת גיבוי עקבי. הגישה הפשוטה בשרת יחיד היא לעצור את המכולה וליצור ארכיון של ה־volume.

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

השתמשו בשם ה־volume שמדפיס docker volume ls, ולא בשם שמופיע בקובץ ה־YAML. הקובץ מצהיר על langfuse_clickhouse_data, ו־Compose מוסיף לו את שם הפרויקט כקידומת. לכן clone בתיקייה בשם langfuse יוצר את langfuse_langfuse_clickhouse_data. אם תטעו בשם, docker run ייצור volume חדש וריק בלי להציג שגיאה, והארכיון שלכם לא יכיל דבר.

Langfuse מעלה נתוני אירועים גולמיים ל־bucket בכל בקשת ingestion, וקורא אותם מחדש כדי לנסות שוב משימות ingestion שנכשלו. לכן עצירה קצרה של ClickHouse גורמת בעיקר לכך שה־worker ינסה שוב לאחר מכן. בצעו זאת בשעה שקטה והשאירו את השירות מושבת לזמן קצר ככל האפשר. במופע עמוס יותר, פקודת BACKUP DATABASE default TO S3(...) של ClickHouse כותבת גיבוי עקבי בלי לעצור את השרת. MinIO הוא החלק השלישי, ו־mc mirror או שכפול של MinIO ל־bucket מחוץ לשרת מכסים אותו. לא משנה מה תיצרו, העבירו את הגיבוי אל מחוץ לשרת. לכך מיועדים גיבויי restic מוצפנים ב־VPS.

Redis שומר את התור ואת המטמון. אובדן שלו מבטל משימות שנמצאות בתור, גם כאשר קובצי האירועים הגולמיים עדיין נמצאים ב־bucket.

הסתייגות העקביות ממשית, וחשוב לציין אותה במפורש. הגיבוי של Postgres והגיבוי של ClickHouse נלקחים ברגעים שונים, ולכן שחזור עלול להשאיר רשומת פרויקט ללא traces, או traces השייכים לפרויקט שאינו קיים עוד. Langfuse מתמודד עם מצב כזה, אך כדאי לקחת את שני הגיבויים בסמיכות ובחלון זמן שבו התעבורה נמוכה. ה־bucket של האירועים הוא רשת הביטחון האמיתית, משום ש־Langfuse מעלה אליו נתוני אירועים גולמיים בכל בקשת ingestion.

שחזרו את הגיבוי ל־stack זמני לפחות פעם אחת. כך תגלו עכשיו שם volume שגוי, ולא בזמן השבתה.

מה לבדוק תחילה

ארבעה דברים ראויים לתשומת לב בשבוע הראשון.

  • עלות לכל trace. המערכת Langfuse מחשבת עלות לפי שם המודל וצריכת ה-tokens, לכן מומלץ למיין traces לפי עלות ולעבור על היקר ביותר מתחילתו ועד סופו. התשובה היא לרוב prompt שתפח: מסמך שלם שהודבק לתוך ה-context, או היסטוריית שיחה שאף אחד לא מקצץ. ברגע שניתן לראות זאת, שליטה בעלויות של סוכן AI הופכת למשימה הנדסית במקום לניחוש.
  • חלוקת צריכת tokens לפי קלט ופלט. tokens של קלט הם רבים וזולים, tokens של פלט הם מעטים ויקרים, וקלט שנשמר ב-cache זול עוד יותר. אותו חישוב מפורט ב-אופן החישוב של צריכת tokens ב-Claude Code, והוא תקף לכל סוכן שתפתחו בעצמכם.
  • אחוזוני שיהוי (Latency). החציון מסתיר את הבעיה. ה-p95 וה-p99 הם המקומות שבהם נמצאים ה-timeouts, ובתוך לולאת סוכן, קריאת כלי איטית ב-p95 מוכפלת במספר האיטרציות.
  • קריאות כלי שנכשלו. סננו תצפיות לפי רמה ERROR. כלי שנכשל ב-5% מהמקרים אינו מורגש בשיעור הצלחה מצטבר, אך הוא בולט מאוד ב-traces, שם ניתן לראות את המודל מנסה שוב ושוב ומבזבז tokens בניסיון לעקוף את התקלה.

הגדירו את חלון השמירה (retention) ובחרו את ה-dashboard שתבדקו מדי שבוע באותו יום שבו אתם מבצעים פריסה (deploy). כלי ניטור שאף אחד לא פותח הוא בסך הכל מסד נתונים שממלא את הדיסק.

FAQ

כמה זיכרון נדרש ל־Langfuse באירוח עצמי?

תכננו 4 ליבות CPU ו־16 GiB זיכרון, בהתאם להמלצה במדריך Docker Compose של Langfuse עבור מכונה וירטואלית יחידה, וכן כ־100 GiB שטח אחסון. דרישות המינימום שפורסמו הן 8 GiB עבור ClickHouse ו־4 GiB לכל אחד ממכולות ה־web וה־worker. באותו עמוד מצוינים גם 4 GiB עבור Postgres, ‏1.5 GiB עבור Redis ו־4 GiB עבור MinIO, ולכן כל ששת הרכיבים מסתכמים ב־25.5 GiB — יותר מההמלצה של 16 GiB עבור Compose.

מדוע הדיסק של ClickHouse ממשיך להתמלא לאחר שהגדרתי שמירת נתונים?

הגדרת השמירה חלה רק על הנתונים של Langfuse עצמו. ClickHouse כותב בנפרד את טבלאות האבחון trace_log, ‏text_log, ‏opentelemetry_span_log, ‏metric_log, ‏asynchronous_metric_log ו־latency_log, וטבלאות אלה מגיעות ללא TTL. הריצו את system.parts בקיבוץ לפי טבלה כדי לראות איזו טבלה היא הגדולה ביותר. לאחר מכן השביתו את הטבלאות שאינן בשימוש באמצעות רשומת remove="1" בקובץ תחת /etc/clickhouse-server/config.d/, הפעילו מחדש את ClickHouse, ומחקו את הטבלאות הקיימות כדי להשיב את השטח שכבר נתפס.

מהי תקופת שמירת הנתונים המינימלית ב־Langfuse?

שלושה ימים. מגדירים את השמירה לכל פרויקט בהגדרות הפרויקט, או באמצעות Organization Management API. משימה לילית מוחקת מ־ClickHouse ומאחסון ה־blob את ה־traces, ה־observations, ה־scores ונכסי המדיה שגילם חורג מהתקופה שהוגדרה, למעט מדיה המשויכת לפריטי dataset שנשמרו. במופע באירוח עצמי, זוהי תכונה של Enterprise Edition שדורשת מפתח רישיון. ללא מפתח כזה, הנתונים נשמרים ללא הגבלת זמן. אי־אפשר לבטל את המחיקה, לכן הגדירו תחילה ייצוא לאחסון blob אם אתם זקוקים להיסטוריה שמעבר לתקופה זו.

האם עליי לגבות גם את Postgres וגם את ClickHouse?

כן, משום שהם מאחסנים נתונים שונים. Postgres מאחסן משתמשים, ארגונים, פרויקטים ומפתחות API, ואילו ClickHouse מאחסן את נתוני ה־trace עצמם. שחזור של Postgres בלבד ייצור מופע שאליו ניתן להתחבר, אך לא יהיו בו נתונים. גבו גם את דלי ה־MinIO, משום שהוא מכיל את האירועים הגולמיים ש־Langfuse שומר בעת קבלתם. זהו הרכיב הקרוב ביותר ל־source of truth במחסנית.

האם אפשר להפנות הגדרת OpenTelemetry קיימת אל Langfuse באירוח עצמי?

כן. Langfuse v4 וה־SDKs הנוכחיים שלו מבוססים על OpenTelemetry, וה־instrumentations של Anthropic ושל OpenAI מייצאים נתונים ישירות אליו. ב־Python, הריצו את pip install langfuse opentelemetry-instrumentation-anthropic, קראו ל־AnthropicInstrumentor().instrument() פעם אחת בעת האתחול, והגדירו את LANGFUSE_PUBLIC_KEY, ‏LANGFUSE_SECRET_KEY ו־LANGFUSE_BASE_URL למארח שלכם. אשרו את התוצאה באמצעות langfuse.auth_check() לפני שאתם מחפשים dashboard חסר.

האם המאמר הזה היה מועיל?