SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

آموزش نصب و میزبانی Langfuse روی سرور شخصی

راهنمای کامل خودمیزبانی Langfuse روی VPS. تنظیم دقیق ClickHouse برای جلوگیری از پر شدن دیسک، استفاده از تگ‌های ثابت Docker، پیکربندی TLS و روش‌های بک‌آپ‌گیری مطمئن.

چرا باید یک عامل هوش مصنوعی را ردیابی (Trace) کرد

شما Langfuse را به‌صورت self-host اجرا می‌کنید تا ببینید عامل (agent) شما در یک اجرا واقعاً چه کاری انجام داده است. Langfuse یک ابزار متن‌باز برای مشاهده‌پذیری (observability) مدل‌های زبانی بزرگ (LLM) است. این ابزار هر prompt، هر پاسخ مدل، هر فراخوانی ابزار و هر token را ثبت کرده و آن‌ها را در یک trace واحد دسته‌بندی می‌کند تا بتوانید آن را باز کرده و مطالعه کنید. اجرای آن روی VPS شخصی به این معناست که آن promptها هرگز از سروری که تحت کنترل شماست خارج نمی‌شوند.

دلیل اهمیت این موضوع روشن است. شما نمی‌توانید مشکل هزینه یا کیفیت را که قادر به دیدن آن نیستید، برطرف کنید. صورت‌حساب ارائه‌دهنده به شما می‌گوید که هزینهٔ روز سه‌شنبه چهار برابر روز دوشنبه بوده است. اما یک trace به شما می‌گوید کدام اجرای عامل باعث این هزینه شده، کدام prompt به 40,000 توکن رسیده و کدام حلقهٔ تلاش مجدد (retry loop) نه بار اجرا شده و سپس متوقف شده است. صورت‌حساب فقط عدد را به شما می‌دهد، اما trace کدی را که آن عدد را تولید کرده است، نشان می‌دهد.

در این راهنما از سه اصطلاح استفاده شده است. یک trace به معنای یک اجرای کامل و سرتاسری از عامل شماست. یک observation یک گام در داخل آن اجراست: یک span برای کدهای معمولی و یک generation برای فراخوانی یک مدل. یک score عددی است که به یک trace اختصاص داده می‌شود و از طریق بازبینی انسانی یا یک ارزیاب خودکار به‌دست می‌آید. Langfuse از OpenTelemetry (OTel) پشتیبانی می‌کند که استاندارد خنثی و مستقل از فروشنده برای ردیابی توزیع‌شده است؛ بنابراین ابزارهای اندازه‌گیری (instrumentation) که هم‌اکنون در اختیار دارید، می‌توانند به آن متصل شوند.

آنچه self-hosting مربوط به Langfuse واقعاً اجرا می‌کند

Langfuse v4 یک container واحد نیست. این سامانه از دو container برنامه و چهار سرویس ذخیره‌سازی تشکیل می‌شود و در یک VPS، هر شش مورد روی سرور شما اجرا می‌شوند.

  • langfuse-web رابط وب و ingestion API را ارائه می‌کند.
  • langfuse-worker صف را در پس‌زمینه تخلیه می‌کند. این سرویس batchهای ingestion را parse می‌کند، هزینه را محاسبه می‌کند و job شبانه retention را اجرا می‌کند.
  • Postgres داده‌های تراکنشی مانند کاربران، سازمان‌ها، پروژه‌ها، API keyها و promptها را نگه می‌دارد.
  • ClickHouse خودِ داده‌های trace، یعنی observationها و scoreها، را نگه می‌دارد. این سرویس یک column store برای queryهای تحلیلی است؛ به همین دلیل dashboard روی بیش از صد میلیون ردیف همچنان سریع پاسخ می‌دهد.
  • Redis صف و cache میان web و worker است.
  • MinIO، object storage سازگار با S3 را روی همان سرور فراهم می‌کند. این سرویس همه eventهای خام ورودی و هر media پیوست‌شده را نگه می‌دارد.

Langfuse حداقل منابع موردنیاز هر component را که اجرا می‌کند منتشر کرده است. نمودار، سه componentی را نشان می‌دهد که کار اصلی را انجام می‌دهند.

نمودار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 حافظه نیاز دارد. container مربوط به web و worker هرکدام به 4 GiB نیاز دارند. این اعداد، حداقل‌های اعلام‌شده برای 3 component موجود در نمودار هستند. در همان صفحه، نیاز Postgres برابر 4 GiB، نیاز Redis یا Valkey برابر 1.5 GiB و نیاز MinIO برابر 4 GiB اعلام شده است؛ بنابراین حداقل موردنیاز هر شش سرویس در مجموع به 25.5 GiB می‌رسد. راهنمای Docker Compose خود پروژه برای یک ماشین، حداقل 4 core، حافظه 16 GiB و حدود 100 GiB فضای ذخیره‌سازی را توصیه می‌کند. این مقدار از مجموع حداقل‌های componentها کمتر است؛ بنابراین 16 GiB را کمترین مقدار لازم برای یک سرور Compose مشترک در نظر بگیرید، نه فضای آزاد کافی.

این setup را روی planهای 2 GiB امتحان نکنید. ClickHouse اجرا می‌شود و مدتی writeها را می‌پذیرد، اما هنگام یک merge در پس‌زمینه از کار می‌افتد؛ زیرا merge بخش‌های بزرگی از یک table را در حافظه بارگذاری می‌کند. در لاگ، docker compose ps را می‌بینید که container مربوط به clickhouse را به‌صورت restarting گزارش می‌کند، dmesg خطی مانند Out of memory: Killed process 1234 (clickhouse-serv) ثبت می‌کند و همه dashboardهای Langfuse پاسخ 500 برمی‌گردانند. در فشار کمتر، ClickHouse به‌جای آن query را رد می‌کند و خطای DB::Exception: Memory limit (total) exceeded را در لاگ می‌نویسد. برای برنامه‌ریزی، عدد 16 را در نظر بگیرید. اگر قرار است همین VPS سرویس‌های دیگری را نیز اجرا کند، منابع آن‌ها را جداگانه محاسبه کنید؛ زیرا حتی یک stack نسبتاً سبک مانند یک workspace خودمیزبان AFFiNE به چند GiB فضای اختصاصی نیاز دارد و ClickHouse هیچ بخشی از منابع خود را پس نمی‌دهد.

استقرار Langfuse با Docker Compose

مخزن را clone کنید. stack، اتصال سرویس‌ها و environment پیش‌فرض همگی در docker-compose.yml قرار دارند.

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

تمام مقادیری که باید تغییر دهید، در این فایل با # CHANGEME مشخص شده‌اند. ابتدا سه application secret را تولید کنید.

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

ENCRYPTION_KEY باید 256 بیت باشد و به‌صورت 64 کاراکتر hex نوشته شود؛ دقیقاً همان چیزی که openssl rand -hex 32 چاپ می‌کند. این مقدار، مقادیر حساس را در حالت at rest رمزنگاری می‌کند؛ از جمله کلیدهای LLM provider که در instance ذخیره می‌کنید. اگر پس از ایجاد داده آن را تغییر دهید، دیگر نمی‌توان آن ردیف‌ها را رمزگشایی کرد. بنابراین از اولین boot با آن مانند مقداری دائمی رفتار کنید. SALT برای hash کردن Langfuse API keyها استفاده می‌شود؛ بنابراین تغییر آن همه keyهایی را که agentهای شما اکنون استفاده می‌کنند، نامعتبر می‌کند.

سپس 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 آن client را با SignatureDoesNotMatch رد می‌کند. این خطا در worker log ثبت می‌شود، در حالی که web interface همچنان سالم به نظر می‌رسد. نگه‌داشتن این مقادیر در یک env file، به‌جای قرار دادن آن‌ها در compose file تحت version control، همان الگویی است که در env fileها و secretها در Docker Compose پوشش داده شده است.

پیش از شروع، image tagها را ثابت کنید

فایل ارائه‌شده از docker.langfuse.com/langfuse/langfuse:4 و docker.langfuse.com/langfuse/langfuse-worker:4 استفاده می‌کند. این tagها تغییر می‌کنند. Langfuse migrationهای Postgres و ClickHouse را هنگام start به‌طور خودکار اجرا می‌کند. بنابراین یک docker compose pull معمولی چند ماه بعد، روی databaseای که همان صبح از آن backup نگرفته‌اید، به migration پیش‌بینی‌نشدهٔ schema تبدیل می‌شود. هر دو را در یک docker-compose.override.yml روی یک release ثابت کنید. Compose این فایل را روی فایل ارائه‌شده merge می‌کند؛ در نتیجه یک git pull بعدی تغییرات شما را بازنویسی نمی‌کند. همین imageها در 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 تا August 2026 نسخه فعلی شاخه 4.3 بود. پس از آن releaseها با سرعت زیادی منتشر شدند و v4.56.0 تا October 11, 2026 جدیدترین نسخه در GitHub بود. override بالا از v4.72.0 استفاده می‌کند که تا October 31, 2026 جدیدترین نسخه در GitHub بود. صفحه releaseهای پروژه در GitHub را بررسی کنید، در روز deployment هر نسخه‌ای را که فعلی است pin کنید و سپس این شماره را آگاهانه ارتقا دهید. بعضی imageهای storage در فایل ارائه‌شده نیز به همین رسیدگی نیاز دارند، چون tagهای آن‌ها هم تغییر می‌کنند. postgres:17، که مقدار پیش‌فرض متغیر POSTGRES_VERSION است، و redis:7 از یک major version پیروی می‌کنند. فایل ارائه‌شده اکنون برای docker.io/clickhouse/clickhouse-server از tag نسخه دقیق استفاده می‌کند و نسخه دقیق ClickHouse را pin می‌کند. این قاعده مخصوص Langfuse نیست: یک tracker خودمیزبان برای تمرین‌های openGym تنها بخشی از این stack را اجرا می‌کند، اما همچنان به یک git tag نام‌گذاری‌شده نیاز دارد؛ زیرا هر چیزی که database خود را هنگام start migrate کند، می‌تواند یک pull معمولی را به تغییر schema تبدیل کند.

stack را بالا بیاورید.

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

در اولین boot، migrationها اجرا می‌شوند؛ بنابراین پیش از آن‌که هر endpointی پاسخ دهد، دو یا سه دقیقه صبر کنید. container وب پس از آماده‌شدن، Ready را در log ثبت می‌کند. docker compose ps باید شش service را در وضعیت running نشان دهد. اگر container در یک loop دوباره start شود، log آن علت را نشان می‌دهد. migrationهای ClickHouse هنگام start شدن container وب اعمال می‌شوند؛ بنابراین یک CLICKHOUSE_MIGRATION_URL نادرست در docker compose logs langfuse-web دیده می‌شود، نه در worker logی که در حال tail کردن آن هستید. این متغیر از protocol بومی ClickHouse روی port 9000 استفاده می‌کند، نه port HTTP یعنی 8123. اشاره‌دادن آن به 8123، migrationهای startup مربوط به container وب را مختل می‌کند. worker migrationهای پس‌زمینهٔ کندتر را اجرا می‌کند؛ بنابراین گزارش آن migrationها در log worker ثبت می‌شود.

سلامت stack را از خود server بررسی کنید.

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 process را ثابت می‌کند، زیرا به‌طور پیش‌فرض database را بررسی نمی‌کند. فرم failIfDatabaseUnavailable=true همان گزینه‌ای است که باید monitor را به آن متصل کنید و هنگام دسترس‌ناپذیر بودن database، کد 503 برمی‌گرداند. /api/public/ready زمانی که container وب آماده دریافت traffic است، کد 200 برمی‌گرداند و پس از آن‌که به آن فرمان shutdown داده شود، کد 500 برمی‌گرداند. هر دو check معمولی HTTP هستند؛ بنابراین صفحهٔ وضعیت Uptime Kuma می‌تواند آن‌ها را monitor کند و پیش از agentهای شما اطلاع دهد که stack از دسترس خارج شده است.

TLS را در جلوی سرویس قرار دهید و پورت‌های اضافی را ببندید

فایل compose ارائه‌شده، 3000:3000 را برای web container و 9090:9000 را برای MinIO منتشر می‌کند. هر دو روی همهٔ interfaceها bind می‌شوند. روی یک IP عمومی، این یعنی هرکس پورت 3000 را scan کند به صفحهٔ ثبت‌نام شما می‌رسد و هرکس پورت 9090 را scan کند با bucket حاوی promptهای خام شما ارتباط برقرار می‌کند.

یک قانون firewall به‌تنهایی آن‌ها را نمی‌بندد. Docker قوانین DNAT خود را در جدول nat می‌نویسد و این قوانین پیش از آن‌که قوانین filter مربوط به ufw بسته را ببینند، ارزیابی می‌شوند؛ بنابراین ufw deny 3000 پورت منتشرشده را باز نگه می‌دارد. این مسئله آن‌قدر رایج است که راهنمای مستقلی برای آن وجود دارد: چرا پورت‌های منتشرشدهٔ Docker از ufw عبور می‌کنند. در فایل override خود، به‌جای آن روی loopback bind کنید. برای جایگزین‌کردن پورت‌های منتشرشده از !override همراه با Docker Compose 2.24.4 یا جدیدتر استفاده کنید؛ یک list ساده با bindingهای اصلی merge می‌شود.

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، باشد؛ زیرا login flow، URL مربوط به callback را از این مقدار می‌سازد. اگر Langfuse پشت یک proxy از نوع HTTPS قرار دارد، مقدار را روی http://localhost:3000 نگذارید؛ در غیر این صورت رفت‌وبرگشت sign in، مرورگر را به نشانی‌ای می‌فرستد که نمی‌تواند به آن دسترسی پیدا کند.

اکنون یک reverse proxy را به 127.0.0.1:3000 هدایت کنید و نگهداری certificate را به آن بسپارید. برای Traefik در همان پروژهٔ Compose، با استفاده از labelهایی که در اجرای چند برنامه پشت یک reverse proxy از نوع Traefik توضیح داده شده‌اند، از طریق شبکهٔ Compose به langfuse-web:3000 route کنید. اگر Langfuse تنها سرویس روی سرور است، Caddy همین کار را با دو خط انجام می‌دهد. با curl -sI https://langfuse.example.com/api/public/ready بررسی کنید و سپس از یک ماشین دوم تأیید کنید که curl http://YOUR_IP:3000 نمی‌تواند متصل شود.

یک نکته دربارهٔ MinIO وجود دارد. Langfuse، هم برای SDKهایی که media را upload می‌کنند و هم برای مرورگری که آن را بارگذاری می‌کند، URLهای presigned را به آن S3 endpoint می‌دهد. بنابراین اگر از traceهای multi-modal حاوی تصویر یا audio استفاده می‌کنید، MinIO که فقط روی loopback قرار دارد باعث می‌شود این attachmentها از ماشین‌های دیگر upload نشوند یا در مرورگر شما بارگذاری نشوند. پیش از proxy کردن آن، صفحهٔ پیکربندی blob storage را بخوانید؛ زیرا endpoint نوشته‌شده در URL presigned، یعنی LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT، باید با چیزی که منتشر می‌کنید مطابقت داشته باشد. traceهای plain text تحت تأثیر قرار نمی‌گیرند.

در اولین بازدید حساب خود را ایجاد کنید و سپس instance را در اختیار خود نگه دارید. پس از ایجاد حساب، یک‌بار AUTH_DISABLE_SIGNUP=true را تنظیم کنید تا فرد غریبه‌ای که به صفحه دسترسی پیدا می‌کند، نتواند اصلاً ثبت‌نام کند. Langfuse همچنین LANGFUSE_ALLOWED_ORGANIZATION_CREATORS را دارد که تعیین می‌کند چه کسانی می‌توانند organisation ایجاد کنند؛ اما این قابلیت Enterprise Edition است و فقط با license key فعال می‌شود. اگر از قبل Authentik را به‌عنوان identity provider خود اجرا می‌کنید، Langfuse یک اتصال استاندارد OIDC می‌پذیرد؛ بنابراین حساب‌ها همراه با سایر برنامه‌های شما ایجاد و حذف می‌شوند، نه این‌که فقط در فهرست passwordهایی باشند که این سرور از آن اطلاع دارد.

اولین trace خود را ارسال کنید

در رابط وب یک project ایجاد کنید و public key و secret key آن را از project settings کپی کنید. Python SDK سه متغیر محیطی را می‌خواند.

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 است که در March 2026 منتشر شد. کدها و راهنماهای قدیمی‌تر از LANGFUSE_HOST استفاده می‌کنند. اگر traceهای شما به‌جای سرور خودتان به Langfuse Cloud می‌رسند، علت unset بودن base URL است، چون مقدار پیش‌فرض به نمونه میزبانی‌شده اشاره می‌کند.

Python SDK v5 فعلی به Python 3.11 یا جدیدتر و self-hosted 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 ابزار instrumentation مربوط به OpenTelemetry برای client مربوط به Anthropic است و هر فراخوانی messages.create را به یک generation تبدیل می‌کند که نام مدل، میزان مصرف token و latency را در خود دارد؛ بدون آن‌که محل فراخوانی تغییری کند.

دو فراخوانی بررسی‌ها را برای شما انجام می‌دهند. langfuse.auth_check() در صورت نامعتبر بودن keyها یا نادرست بودن base URL مقدار False برمی‌گرداند؛ این کار سریع‌تر از حدس‌زدن درباره خالی بودن dashboard است. langfuse.flush() تا ارسال spanهای در صف منتظر می‌ماند. این فراخوانی برای processهای کوتاه‌عمر ضروری است، چون SDK داده‌ها را در پس‌زمینه به‌صورت batch ارسال می‌کند و scriptی که بلافاصله خارج شود، batch ارسال‌نشده را نیز با خود از بین می‌برد. اگر یک تیم کامل به‌جای یک script در حال ارسال trace است، این سه متغیر را یک‌بار در gatewayای تنظیم کنید که agentهای همه افراد از قبل از طریق آن اجرا می‌شوند، نه در shell هر شخص؛ به این ترتیب یک harness خودمیزبان OneCLI اجرای هر همکار را instrumented نگه می‌دارد و keyها در یک محل باقی می‌مانند.

چرا ClickHouse مدام بزرگ‌تر می‌شود؟

Traceها سریع‌ترین نوع داده‌ای هستند که بیشتر افراد در self-hosting تولید می‌کنند. هر اجرای agent برای هر گام یک ردیف می‌نویسد و ورودی‌ها و خروجی‌ها نیز به‌طور کامل ذخیره می‌شوند؛ بنابراین یک agent پرحرف با promptهای طولانی، در هر روز بسیار بیشتر از برنامه‌ای که تحت نظارت دارد داده تولید می‌کند. اگر اقدامی انجام ندهید، ClickHouse دیسک را پر می‌کند و پرشدن دیسک به‌جای کندکردن ingestion، آن را متوقف می‌کند.

در اینجا 2 مورد جداگانه رشد می‌کنند و هرکدام به راه‌حل جداگانه‌ای نیاز دارند.

مورد اول، داده‌های trace خودتان است و راه‌حل آن تنظیم retention است. در یک instance خودمیزبان، نگه‌داری داده‌ها قابلیتی از Enterprise Edition است و به license key نیاز دارد. بدون license، Langfuse، traceها، observationها، scoreها و media را به‌صورت نامحدود نگه می‌دارد؛ بنابراین دیسک را بر همین اساس اندازه‌گیری کنید و به disk alert در پایان این بخش متکی باشید. با داشتن license، ownerهای پروژه و administratorها وارد project settings می‌شوند و دوره نگه‌داری داده را بر اساس تعداد روز تنظیم می‌کنند. Langfuse حداقل 3 روز را می‌پذیرد. سپس یک job شبانه، traceها، observationها، scoreها و media assetهایی را که از این بازه قدیمی‌تر هستند انتخاب می‌کند و آن‌ها را از ClickHouse و blob storage حذف می‌کند؛ به‌جز media مرتبط با dataset itemهای ذخیره‌شده. این job به مجوز DeleteObject روی bucket نیاز دارد که credentialهای root مربوط به MinIO در فایل compose پیش‌فرض از قبل آن را دارند. حذف دائمی است؛ بنابراین اگر به سابقه بلندمدت نیاز دارید، ابتدا یک blob storage export پیکربندی کنید. عبارت‌های TTL را برای tableهای خود Langfuse دستی ننویسید: این retention job است که ClickHouse و bucket را همگام نگه می‌دارد و یک TTL دستی فقط یکی از این دو طرف را حذف می‌کند.

بازه را بر اساس استفاده واقعی خود انتخاب کنید. بررسی هزینه و کیفیت روی داده‌های چندروزه انجام می‌شود، نه داده‌های چندماهه. برای یک تیم کوچک، 30 روز شروع مناسبی است و اگر فقط هنگام بروز مشکل یک trace را باز می‌کنید، 14 روز کافی است.

مورد دوم، tableهای system log خود ClickHouse هستند. این مورد بسیاری از افراد را غافلگیر می‌کند، زیرا پس از پیکربندی retention نیز دیسک همچنان پر می‌شود. ClickHouse برای diagnosticهای خودش trace_log، text_log، opentelemetry_span_log، metric_log، asynchronous_metric_log و latency_log را می‌نویسد. این tableها بدون 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" اجرا کنید. اگر tableهای system در صدر فهرست قرار دارند، با یک config overlay آن‌ها را غیرفعال کنید، زیرا ClickHouse هنگام شروع، هر فایل موجود در /etc/clickhouse-server/config.d/ را روی configuration اصلی merge می‌کند.

<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 را restart کنید.

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

این کار writeهای جدید را متوقف می‌کند. ردیف‌هایی که از قبل روی دیسک هستند باقی می‌مانند؛ بنابراین با DROP TABLE IF EXISTS system.trace_log و همین‌طور با اجرای معادل آن برای هر table حذف‌شده، فضا را به‌طور صریح آزاد کنید. اگر ترجیح می‌دهید diagnosticها را نگه دارید، راه‌حل جایگزین این است که به‌جای remove="1" روی هر table یک TTL تهاجمی تنظیم کنید؛ مستندات scaling مربوط به Langfuse این روش را به‌طور کامل توضیح می‌دهند. این directiveهای TTL فقط هنگام ایجاد اولیه یک system table اعمال می‌شوند؛ بنابراین همان مستندات در یک installation موجود، مراحل اعمال آن‌ها روی tableهای فعلی را نیز توضیح می‌دهند.

یک table دیگر نیز ارزش شناختن دارد. blob_storage_file_log فایل‌های event بارگذاری‌شده در bucket شما را ردیابی می‌کند. اگر برای bucket یک lifecycle policy نیز تنظیم کرده‌اید، برای این table یک TTL متناظر قرار دهید تا این دو از یکدیگر فاصله نگیرند.

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

برای data disk نیز یک alert ساده df -h تنظیم کنید. Traceها به‌صورت یکنواخت رشد نمی‌کنند. رشد آن‌ها معمولاً در روزی رخ می‌دهد که یک agent جدید را deploy می‌کنید؛ نخستین نشانه این موضوع نباید شکست ingestion باشد.

از Postgres و ClickHouse نسخه پشتیبان بگیرید

تهیه نسخه پشتیبان از Langfuse سه بخش دارد. Postgres کاربران، سازمان‌ها، پروژه‌ها و API keyها را نگه می‌دارد. ClickHouse traceها را نگه می‌دارد. 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 به دقت بیشتری نیاز دارد، زیرا کپی‌کردن یک data directory فعال هنگام اجرای mergeها، نسخه پشتیبان سازگاری ایجاد نمی‌کند. روش ساده در یک سرور، متوقف‌کردن container و archive کردن 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 خالی جدید می‌سازد و archive شما چیزی دربر نخواهد داشت.

Langfuse داده‌های خام رویداد را در هر درخواست ingestion در bucket بارگذاری می‌کند و برای retry کردن jobهای ناموفق ingestion دوباره آن‌ها را می‌خواند؛ بنابراین توقف کوتاه ClickHouse عمدتاً باعث می‌شود workerها بعداً jobها را دوباره تلاش کنند. این کار را در ساعتی کم‌ترافیک انجام دهید و مدت توقف را کوتاه نگه دارید. برای یک instance پرترافیک‌تر، دستور داخلی BACKUP DATABASE default TO S3(...) در ClickHouse یک نسخه پشتیبان سازگار ایجاد می‌کند، بدون آن‌که سرور متوقف شود. MinIO بخش سوم است و mc mirror یا replication در MinIO به یک bucket خارج از سرور، این بخش را پوشش می‌دهد. هر چیزی که تولید می‌کنید، آن را از سرور خارج کنید؛ پشتیبان‌های رمزنگاری‌شده restic روی VPS برای همین کار هستند.

Redis صف و cache را نگه می‌دارد. از دست‌دادن آن jobهای در صف را حذف می‌کند، حتی اگر فایل‌های خام رویداد همچنان در bucket باقی مانده باشند.

نکته مربوط به سازگاری واقعی است و باید صریح بیان شود. از Postgres و ClickHouse در زمان‌های متفاوت dump گرفته می‌شود؛ بنابراین بازیابی ممکن است ردیف یک پروژه را بدون trace باقی بگذارد، یا traceهایی را حفظ کند که به پروژه‌ای تعلق دارند که دیگر وجود ندارد. Langfuse این وضعیت را تحمل می‌کند، اما هر دو dump را در فاصله زمانی نزدیک و در یک بازه کم‌ترافیک تهیه کنید. bucket رویداد لایه اصلی ایمنی است، زیرا Langfuse داده‌های خام رویداد را در هر درخواست ingestion در آن بارگذاری می‌کند.

حداقل یک‌بار بازیابی را در یک stack آزمایشی انجام دهید. این کار باعث می‌شود همین حالا از نام اشتباه volume مطلع شوید، نه هنگام وقوع قطعی سرویس.

نخستین مواردی که باید بررسی کنید

چهار مورد زیر در هفتهٔ اول اهمیت ویژه‌ای دارند.

  • هزینه به ازای هر trace. ابزار Langfuse هزینه را بر اساس نام مدل و تعداد توکن‌های مصرفی محاسبه می‌کند؛ بنابراین traceها را بر اساس هزینه مرتب کرده و پرهزینه‌ترین آن‌ها را از ابتدا تا انتها بررسی کنید. پاسخ معمولاً در یک prompt نهفته است که بیش از حد بزرگ شده است: سندی کامل که در context کپی شده یا تاریخچهٔ گفتگویی که هیچ‌کس آن را کوتاه نمی‌کند. هنگامی که این موضوع را مشاهده کردید، کنترل هزینه‌های یک عامل هوش مصنوعی از یک حدس‌وگمان به یک وظیفهٔ مهندسی تبدیل می‌شود.
  • تفکیک مصرف توکن بر اساس ورودی و خروجی. توکن‌های ورودی تعداد زیادی دارند و ارزان هستند، توکن‌های خروجی تعداد کمی دارند و گران‌اند، و توکن‌های ورودیِ کش‌شده (cached) حتی ارزان‌تر هستند. همین حساب‌وکتاب در نحوه محاسبه مصرف توکن در Claude Code تشریح شده است و برای هر عاملی که خودتان می‌نویسید نیز صدق می‌کند.
  • صدک‌های تأخیر (Latency percentiles). مقدار میانه (median) مشکل را پنهان می‌کند. p95 و p99 نقاطی هستند که timeoutها در آنجا رخ می‌دهند و در یک حلقهٔ عامل (agent loop)، یک فراخوانی ابزار کند در p95، در تعداد تکرارها ضرب می‌شود.
  • فراخوانی‌های ناموفق ابزار. مشاهدات را بر اساس سطح ERROR فیلتر کنید. ابزاری که 5 درصد مواقع شکست می‌خورد، در نرخ موفقیت کلی دیده نمی‌شود اما در traceها کاملاً مشهود است؛ جایی که می‌بینید مدل تلاش می‌کند دوباره سعی کند و سپس توکن‌های زیادی را برای دور زدن مشکل هدر می‌دهد.

بازهٔ نگهداری (retention window) را تنظیم کنید و داشبوردی را انتخاب کنید که هر هفته در همان روزی که deploy می‌کنید، آن را بررسی خواهید کرد. ابزار مشاهده‌پذیری (observability) که هیچ‌کس آن را باز نمی‌کند، صرفاً پایگاه‌داده‌ای است که دیسک را پر می‌کند.

FAQ

یک نمونه Langfuse با میزبانی شخصی به چه مقدار حافظه نیاز دارد؟

برای 4 هسته CPU و 16 GiB حافظه برنامه‌ریزی کنید؛ این همان مقداری است که راهنمای Docker Compose مربوط به Langfuse برای یک ماشین مجازی پیشنهاد می‌کند. حدود 100 GiB فضای ذخیره‌سازی نیز در نظر بگیرید. حداقل حافظه اعلام‌شده برای ClickHouse برابر با 8 GiB و برای هرکدام از containerهای web و worker برابر با 4 GiB است. در همان صفحه، 4 GiB برای Postgres، مقدار 1.5 GiB برای Redis و 4 GiB برای MinIO ذکر شده است. بنابراین مجموع نیاز هر شش مؤلفه 25.5 GiB می‌شود که از پیشنهاد 16 GiB برای Compose بیشتر است.

چرا پس از تنظیم data retention، دیسک ClickHouse همچنان پر می‌شود؟

تنظیم retention فقط داده‌های خود 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 را restart کنید و جدول‌های موجود را حذف کنید تا فضای قبلاً مصرف‌شده آزاد شود.

حداقل دوره data retention در Langfuse چقدر است؟

3 روز. retention برای هر project در project settings یا از طریق Organization Management API تنظیم می‌شود. یک job شبانه، traceها، observationها، scoreها و media assetهای قدیمی‌تر از این بازه را هم از ClickHouse و هم از blob storage حذف می‌کند؛ media مرتبط با dataset itemهای ذخیره‌شده از این قاعده مستثنا است. در یک instance با میزبانی شخصی، این قابلیت فقط در Enterprise Edition ارائه می‌شود و به license key نیاز دارد. بدون license key، داده‌ها بدون محدودیت زمانی نگهداری می‌شوند. حذف قابل بازگردانی نیست؛ بنابراین اگر به سابقه‌ای بیش از این بازه نیاز دارید، ابتدا یک blob storage export تنظیم کنید.

آیا باید هم از Postgres و هم از ClickHouse نسخه پشتیبان تهیه کنم؟

بله، زیرا هرکدام داده‌های متفاوتی را نگهداری می‌کنند. Postgres شامل userها، organisationها، projectها و API keyها است و ClickHouse خود داده‌های trace را نگهداری می‌کند. بازیابی فقط از Postgres، instanceای ایجاد می‌کند که می‌توانید به آن وارد شوید، اما هیچ داده‌ای در آن وجود ندارد. از bucket مربوط به MinIO نیز پشتیبان تهیه کنید؛ این bucket رویدادهای خامی را نگهداری می‌کند که Langfuse هنگام دریافت persist می‌کند و در این stack نزدیک‌ترین مورد به source of truth است.

آیا می‌توانم یک setup موجود OpenTelemetry را به Langfuse با میزبانی شخصی متصل کنم؟

بله. Langfuse v4 و SDKهای فعلی آن بر پایه OpenTelemetry ساخته شده‌اند و instrumentationهای OTel مربوط به Anthropic و OpenAI مستقیماً داده‌ها را به آن export می‌کنند. در Python، pip install langfuse opentelemetry-instrumentation-anthropic را اجرا کنید، هنگام startup یک‌بار AnthropicInstrumentor().instrument() را فراخوانی کنید و LANGFUSE_PUBLIC_KEY، LANGFUSE_SECRET_KEY و LANGFUSE_BASE_URL را روی host خودتان تنظیم کنید. پیش از جست‌وجوی dashboard گمشده، اتصال را با langfuse.auth_check() تأیید کنید.

آیا این مقاله مفید بود؟