SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

Langfuse کو اپنے VPS پر self-host کرنے کا طریقہ

اپنے VPS پر Langfuse چلائیں: کم از کم resources، pinned image tags، TLS، disk بھرنے سے پہلے ClickHouse retention، اور قابلِ اعتماد backups کی عملی وضاحت۔

AI agent کی tracing کیوں کریں

آپ Langfuse کو self-host کرتے ہیں تاکہ معلوم ہو سکے کہ آپ کے agent نے کسی run میں حقیقتاً کیا کیا۔ Langfuse ایک open source LLM (large language model) observability tool ہے۔ یہ ہر prompt، ہر model response، ہر tool call اور ہر token ریکارڈ کرتا ہے، پھر انہیں ایک trace کے تحت گروپ کرتا ہے جسے آپ کھول کر پڑھ سکتے ہیں۔ اسے اپنے VPS پر چلانے سے یہ prompts کبھی بھی آپ کے زیرِ انتظام server سے باہر نہیں جاتے۔

اس کی ضرورت کی وجہ واضح ہے۔ جس cost problem یا quality problem کو آپ دیکھ نہیں سکتے، اسے حل نہیں کر سکتے۔ Provider invoice سے صرف یہ معلوم ہوتا ہے کہ Tuesday کی لاگت Monday کی لاگت سے چار گنا تھی۔ Trace بتاتا ہے کہ یہ کس agent run کی وجہ سے ہوا، کون سا prompt 40,000 tokens تک بڑھا، اور کون سا retry loop ناکام ہونے سے پہلے نو بار چلا۔ Invoice آپ کو number دیتا ہے۔ Trace آپ کو وہ code دکھاتا ہے جس نے یہ نتیجہ پیدا کیا۔

اس guide میں تین اصطلاحات استعمال ہوں گی۔ trace آپ کے agent کا ایک end to end run ہے۔ observation اس run کے اندر ایک step ہے: عام code کے لیے ایک span، اور model کو call کرنے کے لیے ایک generation۔ score کسی trace کے ساتھ منسلک number ہے، جو human review یا automated evaluator سے حاصل ہوتا ہے۔ Langfuse OpenTelemetry (OTel) استعمال کرتا ہے، جو distributed tracing کے لیے vendor neutral standard ہے، اس لیے آپ کی موجودہ instrumentation اسے target کر سکتی ہے۔

خود میزبانی Langfuse در حقیقت کیا چلاتی ہے

Langfuse v4 صرف ایک container نہیں ہے۔ یہ دو application containers اور چار storage services پر مشتمل ہے، اور single VPS پر یہ تمام چھ services آپ کے server پر چلتی ہیں۔

  • langfuse-web web interface اور ingestion API فراہم کرتا ہے۔
  • langfuse-worker پس منظر میں queue خالی کرتا ہے۔ یہ ingestion batches کو parse کرتا ہے، cost کا حساب لگاتا ہے، اور nightly retention job چلاتا ہے۔
  • Postgres transactional data محفوظ کرتا ہے، جیسے users، organisations، projects، API keys اور prompts۔
  • ClickHouse خود trace data محفوظ کرتا ہے، یعنی observations اور scores۔ یہ analytical queries کے لیے بنایا گیا column store ہے، اسی لیے ایک سو ملین سے زیادہ rows پر مشتمل dashboard بھی تیزی سے جواب دیتا ہے۔
  • Redis وہ queue اور cache ہے جو web اور worker کے درمیان ہوتا ہے۔
  • MinIO server پر S3 compatible object storage فراہم کرتا ہے۔ یہ ہر raw incoming event کے علاوہ آپ کی attach کی ہوئی media بھی محفوظ کرتا ہے۔

Langfuse اپنے ہر component کے لیے minimum resources شائع کرتا ہے۔ chart میں وہ تین components دکھائے گئے ہیں جو اصل کام کرتے ہیں۔

چارٹ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 memory درکار ہے۔ web container اور worker کو ہر ایک کے لیے 4 GiB درکار ہے۔ chart میں موجود 3 components کے لیے یہ شائع کردہ کم از کم حدود ہیں۔ اسی صفحے پر Postgres کے لیے 4 GiB، Redis یا Valkey کے لیے 1.5 GiB، اور MinIO کے لیے 4 GiB درج ہیں، لہٰذا تمام چھ services کے کم از کم تقاضے ملا کر 25.5 GiB بنتے ہیں۔ project کی اپنی Docker Compose guide ایک single machine کے لیے کم از کم 4 cores، 16 GiB memory اور تقریباً 100 GiB storage تجویز کرتی ہے۔ یہ مقدار components کی مجموعی کم از کم حدود سے کم ہے، اس لیے 16 GiB کو shared Compose server کے لیے کم از کم ضرورت سمجھیں، اضافی گنجائش نہیں۔

اسے 2 GiB plan پر چلانے کی کوشش نہ کریں۔ ClickHouse start ہو جاتا ہے اور کچھ وقت تک writes قبول کرتا ہے، پھر background merge کے دوران بند ہو جاتا ہے، کیونکہ merge table کے بڑے parts کو memory میں load کرتا ہے۔ آپ docker compose ps میں clickhouse container کی حالت restarting دیکھیں گے، dmesg میں Out of memory: Killed process 1234 (clickhouse-serv) جیسی سطر ہوگی، اور ہر Langfuse dashboard 500 واپس کرے گا۔ کم load کی صورت میں ClickHouse اس کے بجائے query مسترد کر دیتا ہے اور DB::Exception: Memory limit (total) exceeded log کرتا ہے۔ منصوبہ بندی کے لیے 16 GiB کو بنیاد بنائیں۔ اگر اسی VPS پر کوئی اور workload بھی چلانا ہے تو اس کے لیے الگ resources مختص کریں، کیونکہ نسبتاً ہلکا stack بھی، مثلاً self-hosted AFFiNE workspace، اپنی GiB memory چاہتا ہے اور ClickHouse کوئی memory واپس نہیں دے گا۔

Docker Compose کے ساتھ Langfuse تعینات کریں

Repository clone کریں۔ Stack، wiring اور default environment سب اس کی docker-compose.yml میں موجود ہیں۔

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

اس file میں ہر وہ value جسے آپ کو تبدیل کرنا ہے، # CHANGEME سے نشان زد ہے۔ پہلے application secrets کے تین values generate کریں۔

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

ENCRYPTION_KEY 256 bits کا ہونا چاہیے اور 64 hexadecimal characters کی صورت میں لکھا ہونا چاہیے۔ openssl rand -hex 32 بالکل یہی output دیتا ہے۔ یہ rest پر موجود حساس values کو encrypt کرتا ہے، جن میں instance میں محفوظ LLM provider keys بھی شامل ہیں۔ Data موجود ہونے کے بعد اسے تبدیل کرنے سے وہ rows دوبارہ decrypt نہیں ہو سکتیں۔ اس لیے پہلے boot سے اسے مستقل سمجھیں۔ SALT آپ کی Langfuse API keys کو hash کرنے کے لیے استعمال ہوتا ہے، اس لیے اسے تبدیل کرنے سے آپ کے agents کی استعمال کردہ ہر key invalid ہو جائے گی۔

اس کے بعد POSTGRES_PASSWORD، CLICKHOUSE_PASSWORD، REDIS_AUTH اور MINIO_ROOT_PASSWORD set کریں۔ MinIO password چار جگہ ظاہر ہوتا ہے: ایک بار 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 کے ساتھ reject کر دیتا ہے۔ یہ error worker log میں درج ہوتا ہے، جبکہ web interface بظاہر درست رہتا ہے۔ ان values کو tracked compose file کے بجائے env file میں رکھنا وہ pattern ہے جس کا احاطہ Docker Compose env files اور secrets میں کیا گیا ہے۔

شروع کرنے سے پہلے image tags کو pin کریں

فراہم کردہ file میں docker.langfuse.com/langfuse/langfuse:4 اور docker.langfuse.com/langfuse/langfuse-worker:4 استعمال ہوتے ہیں۔ یہ tags تبدیل ہوتے رہتے ہیں۔ Langfuse start کے وقت اپنی Postgres اور ClickHouse migrations خودکار طور پر چلاتا ہے۔ اس لیے چند ماہ بعد معمول کا docker compose pull ایسی database پر غیر منصوبہ بند schema migration بن سکتا ہے جس کا اسی صبح backup نہیں لیا گیا تھا۔ دونوں کو ایک release پر docker-compose.override.yml میں pin کریں۔ Compose اسے فراہم کردہ file کے اوپر merge کرتا ہے، اس لیے بعد کا git pull آپ کی edits سے متصادم نہیں ہوگا۔ یہی images Docker Hub پر بھی published ہیں، اور نیچے دیا گیا override وہیں سے انہیں pull کرتا ہے۔

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

August 2026 تک version 4.3.1، 4.3 release کی موجودہ version تھی۔ اس کے بعد releases تیزی سے آتی رہی ہیں، اور October 11, 2026 تک GitHub پر v4.56.0 تازہ ترین version تھی۔ اوپر دیا گیا override v4.72.0 استعمال کرتا ہے، جو October 31, 2026 تک GitHub پر تازہ ترین version تھی۔ Project کے GitHub releases page کو check کریں، deployment کے دن جو version موجودہ ہو اسے pin کریں، پھر اس number کو جان بوجھ کر آگے بڑھائیں۔ فراہم کردہ file میں کچھ storage images کے ساتھ بھی یہی کرنا چاہیے، کیونکہ ان کے tags بھی تبدیل ہوتے رہتے ہیں۔ postgres:17 (ایک POSTGRES_VERSION variable کی default value) اور redis:7 major version follow کرتے ہیں۔ فراہم کردہ file اب docker.io/clickhouse/clickhouse-server کے لیے exact version tag استعمال کرتی ہے، جس سے exact ClickHouse version pin ہوتی ہے۔ یہ rule صرف Langfuse تک محدود نہیں ہے: ایک self-hosted openGym workout tracker اس stack کا ایک حصہ استعمال کرتا ہے، پھر بھی named git tag چاہتا ہے، کیونکہ جو بھی software start کے وقت اپنی database migrate کرتا ہے وہ معمول کے pull کو schema change میں تبدیل کر سکتا ہے۔

اسے start کریں۔

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

پہلا boot migrations چلاتا ہے، اس لیے کسی بھی response سے پہلے دو یا تین منٹ انتظار کریں۔ Web container up ہونے کے بعد Ready log کرتا ہے۔ docker compose ps کو state running میں چھ services دکھانی چاہییں۔ اگر کوئی container loop میں restart ہو تو اس کے log میں وجہ موجود ہوگی۔ ClickHouse migrations web container start ہونے پر apply ہوتی ہیں، اس لیے خراب CLICKHOUSE_MIGRATION_URL، docker compose logs langfuse-web میں ظاہر ہوتا ہے، نہ کہ اس worker log میں جسے آپ tail کر رہے ہیں۔ یہ variable port 9000 پر ClickHouse native protocol استعمال کرتا ہے، HTTP port 8123 پر نہیں۔ اسے 8123 پر point کرنے سے web container کی startup migrations fail ہو جاتی ہیں۔ Worker نسبتاً سست background migrations چلاتا ہے، اس لیے ان migrations کی reports اسی کے log میں ہوتی ہیں۔

خود اسی box سے health check کریں۔

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 call صرف یہ ثابت کرتی ہے کہ API process زندہ ہے، کیونکہ default طور پر یہ database check نہیں کرتی۔ failIfDatabaseUnavailable=true والا form monitor کے لیے استعمال کرنا چاہیے، اور database unreachable ہونے پر یہ 503 return کرتا ہے۔ Web container traffic receive کرنے کے لیے ready ہو تو /api/public/ready، 200 return کرتا ہے، اور اسے shutdown کرنے کا کہا جائے تو 500 return کرتا ہے۔ دونوں معمول کے HTTP checks ہیں، اس لیے ایک Uptime Kuma status page انہیں monitor کر سکتا ہے اور آپ کے agents سے پہلے بتا سکتا ہے کہ stack down ہے۔

TLS سامنے رکھیں اور اضافی ports بند کریں

فراہم کردہ compose file web container کے لیے 3000:3000 اور MinIO کے لیے 9090:9000 شائع کرتی ہے۔ دونوں ہر network interface پر bind ہوتے ہیں۔ Public IP پر اس کا مطلب ہے کہ port 3000 scan کرنے والا ہر شخص آپ کے sign up page تک پہنچ سکتا ہے، اور port 9090 scan کرنے والا ہر شخص اس bucket سے رابطہ کر سکتا ہے جس میں آپ کے raw prompts موجود ہیں۔

صرف firewall rule کافی نہیں ہوتا۔ Docker اپنے DNAT rules کو nat table میں لکھتا ہے، اور یہ rules ufw کے filter rules تک packet پہنچنے سے پہلے ہی لاگو ہو جاتے ہیں، اس لیے ufw deny 3000 شائع شدہ port کو کھلا چھوڑ دیتا ہے۔ اس مسئلے سے اتنے لوگ دوچار ہوتے ہیں کہ اس کے لیے الگ guide موجود ہے: Docker کے شائع شدہ ports ufw کو bypass کیوں کرتے ہیں۔ اپنی override file میں اس کے بجائے loopback پر bind کریں۔ Docker Compose 2.24.4 یا اس کے بعد کے ورژن کے ساتھ شائع شدہ ports کو replace کرنے کے لیے !override استعمال کریں؛ سادہ list اصل bindings کے ساتھ 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 سمیت بالکل درست public address ہونا چاہیے، کیونکہ login flow اسی value سے callback URL بناتا ہے۔ اگر اسے HTTPS proxy کے پیچھے http://localhost:3000 رہنے دیں تو sign in کا round trip browser کو ایسے مقام پر بھیج دے گا جہاں وہ پہنچ نہیں سکتا۔

اب reverse proxy کو 127.0.0.1:3000 پر point کریں اور certificate اسی کے ذریعے manage ہونے دیں۔ اسی Compose project میں Traefik استعمال کرتے وقت ایک Traefik reverse proxy کے پیچھے متعدد ایپس چلانے میں بیان کردہ labels کے ذریعے Compose network پر langfuse-web:3000 کی طرف route کریں۔ اگر اس machine پر صرف Langfuse چل رہا ہے تو Caddy یہی کام دو lines میں کر دیتا ہے۔ curl -sI https://langfuse.example.com/api/public/ready کے ذریعے تصدیق کریں، پھر دوسری machine سے بھی تصدیق کریں کہ curl http://YOUR_IP:3000 سے connection قائم نہیں ہو سکتا۔

MinIO کے بارے میں ایک اہم بات ہے۔ Langfuse یہ S3 endpoint استعمال کرنے والے presigned URLs فراہم کرتا ہے، جو media upload کرنے والے SDKs اور اسے browser میں load کرنے کے لیے دونوں کو دیے جاتے ہیں۔ اس لیے اگر آپ images یا audio پر مشتمل multi-modal traces استعمال کرتے ہیں تو صرف loopback پر دستیاب MinIO سے یہ attachments دوسری machines سے upload نہیں ہوں گے اور browser میں load بھی نہیں ہوں گے۔ اسے proxy کرنے سے پہلے blob storage configuration page پڑھیں، کیونکہ presigned URL میں درج endpoint، LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT، آپ کے publish کیے گئے endpoint سے مطابقت رکھنا چاہیے۔ Plain text traces متاثر نہیں ہوتے۔

پہلی بار visit پر اپنا account بنائیں، پھر instance کا انتظام اپنے ہاتھ میں رکھیں۔ Account بننے کے بعد AUTH_DISABLE_SIGNUP=true set کریں، تاکہ page تک پہنچنے والا کوئی اجنبی register نہ کر سکے۔ Langfuse میں LANGFUSE_ALLOWED_ORGANIZATION_CREATORS بھی موجود ہے، جو یہ محدود کرتا ہے کہ کون organisations بنا سکتا ہے، لیکن یہ Enterprise Edition feature ہے اور صرف license key کے ساتھ مؤثر ہوتا ہے۔ اگر آپ پہلے ہی اپنے identity provider کے طور پر Authentik چلا رہے ہیں تو Langfuse standard OIDC connection قبول کرتا ہے۔ اس طرح accounts آپ کی دوسری apps کے ساتھ بنائے اور ختم کیے جا سکتے ہیں، بجائے اس کے کہ وہ صرف اس machine کو معلوم password list میں موجود رہیں۔

اپنا پہلا trace بھیجیں

Web interface میں ایک project بنائیں اور project settings سے اس کی public اور secret keys copy کریں۔ Python SDK تین environment variables پڑھتا ہے۔

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 میں variable name ہے، جو March 2026 میں release ہوا تھا۔ پرانا code اور پرانی guides LANGFUSE_HOST استعمال کرتی ہیں۔ اگر آپ کے traces آپ کے server کے بجائے Langfuse Cloud میں پہنچ رہے ہیں تو وجہ base URL کا unset ہونا ہے، کیونکہ default hosted instance کی طرف اشارہ کرتا ہے۔

موجودہ Python SDK v5 کے لیے Python 3.11 یا اس کے بعد کا ورژن اور self-hosted Langfuse v4.59.0 یا اس کے بعد کا ورژن درکار ہے۔ اوپر pin کیا گیا server اس شرط کو پورا کرتا ہے۔

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 decorator function کے گرد ایک observation کھولتا ہے، اس کے arguments اور return value capture کرتا ہے، اور اسے پہلے سے active observation کے اندر nested کرتا ہے۔ AnthropicInstrumentor Anthropic client کے لیے OpenTelemetry instrumentation ہے۔ یہ ہر messages.create call کو ایک generation میں تبدیل کرتا ہے جس میں model name، token usage اور latency شامل ہوتے ہیں، اور call site میں کوئی تبدیلی نہیں کرنی پڑتی۔

دو calls یہ checking خود کر دیتے ہیں۔ langfuse.auth_check() غلط keys یا غلط base URL کی صورت میں False return کرتا ہے۔ یہ dashboard خالی ہونے کی وجہ تلاش کرنے سے زیادہ تیز ہے۔ langfuse.flush() queued spans بھیجے جانے تک انتظار کرتا ہے۔ مختصر مدت تک چلنے والے processes کے لیے یہ ضروری ہے، کیونکہ SDK background میں batches بناتا ہے اور فوراً exit ہونے والی script اپنی unsent batch بھی ساتھ ختم کر دیتی ہے۔ اگر ایک script کے بجائے پوری team traces بھیج رہی ہو تو یہ تینوں variables ہر شخص کے shell میں set کرنے کے بجائے اس gateway میں ایک بار set کریں جس سے سب کے agents پہلے ہی گزرتے ہیں۔ اسی طرح ایک self-hosted OneCLI harness ہر colleague کی runs کو instrumented رکھتا ہے اور keys ایک ہی جگہ محفوظ رہتی ہیں۔

ClickHouse کا حجم مسلسل کیوں بڑھتا رہتا ہے؟

Traces وہ data ہیں جو زیادہ تر لوگ self-host کرتے وقت سب سے تیزی سے بڑھتے ہوئے دیکھتے ہیں۔ ہر agent run ہر step کے لیے ایک row لکھتا ہے، اور inputs اور outputs مکمل طور پر محفوظ کیے جاتے ہیں۔ اس لیے طویل prompts والا زیادہ باتونی agent روزانہ اس application سے کہیں زیادہ bytes پیدا کرتا ہے جس کی وہ نگرانی کر رہا ہوتا ہے۔ اگر اسے اسی طرح چھوڑ دیا جائے تو ClickHouse disk بھر دیتا ہے، اور مکمل disk ingestion کو سست کرنے کے بجائے روک دیتی ہے۔

یہاں دو الگ چیزیں بڑھتی ہیں، اور ان کے لیے دو الگ fixes درکار ہیں۔

پہلی چیز آپ کا اپنا trace data ہے، اور اس کا fix retention setting ہے۔ self-hosted instance پر data retention ایک Enterprise Edition feature ہے اور اسے license key درکار ہوتی ہے۔ اس کے بغیر Langfuse traces، observations، scores اور media کو غیر معینہ مدت تک محفوظ رکھتا ہے۔ اس لیے disk کو اسی حساب سے size کریں اور اس section کے آخر میں موجود disk alert پر انحصار کریں۔ license کے ساتھ project owners اور admins project settings کھول کر data retention period دنوں میں مقرر کر سکتے ہیں۔ Langfuse کم از کم 3 دن قبول کرتا ہے۔ اس کے بعد ایک nightly job مقررہ مدت سے پرانے traces، observations، scores اور media assets منتخب کرکے انہیں ClickHouse اور blob storage سے حذف کرتی ہے، البتہ saved dataset items سے وابستہ media اس سے مستثنیٰ ہے۔ اس job کو bucket پر DeleteObject permission درکار ہوتی ہے، جو default compose file میں موجود MinIO root credentials کے پاس پہلے ہی ہوتی ہے۔ حذف کرنا مستقل ہوتا ہے، اس لیے اگر آپ کو long term history درکار ہو تو پہلے blob storage export configure کریں۔ Langfuse کی اپنی tables میں TTL clauses خود نہ لکھیں۔ retention job ہی ClickHouse اور bucket کو ہم آہنگ رکھتی ہے، جبکہ manual TTL صرف ایک side سے data حذف کرتا ہے۔

window کا انتخاب اپنے حقیقی استعمال کی بنیاد پر کریں۔ Cost اور quality review مہینوں پرانے data کے بجائے چند دن پرانے data پر ہوتا ہے۔ چھوٹی team کے لیے 30 دن ایک مناسب آغاز ہے، اور اگر آپ trace صرف کسی خرابی کے وقت کھولتے ہیں تو 14 دن کافی ہیں۔

دوسری چیز ClickHouse کی اپنی system log tables ہیں۔ یہ بات لوگوں کو حیران کرتی ہے، کیونکہ retention configure کرنے کے بعد بھی disk کا حجم بڑھتا رہتا ہے۔ ClickHouse اپنی diagnostics کے لیے trace_log، text_log، opentelemetry_span_log، metric_log، asynchronous_metric_log اور latency_log لکھتا ہے۔ یہ tables کسی TTL کے بغیر آتی ہیں، اور Langfuse انہیں کبھی read نہیں کرتا۔ پہلے معلوم کریں کہ disk حقیقت میں کہاں استعمال ہوئی ہے۔

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" کے ساتھ چلائیں۔ اگر system tables فہرست میں اوپر ہوں تو انہیں config overlay کے ذریعے بند کریں، کیونکہ ClickHouse start کے وقت /etc/clickhouse-server/config.d/ میں موجود ہر file کو اپنی main config پر 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

اس سے نئی writes رک جاتی ہیں۔ Disk پر پہلے سے موجود rows برقرار رہتی ہیں، اس لیے DROP TABLE IF EXISTS system.trace_log کے ذریعے space واضح طور پر reclaim کریں، اور ہر حذف کی گئی table کے لیے یہی عمل دہرائیں۔ اگر آپ diagnostics محفوظ رکھنا چاہتے ہیں تو remove="1" کے بجائے ہر table پر aggressive TTL لگانا متبادل طریقہ ہے، جس کی تفصیل Langfuse scaling docs میں موجود ہے۔ یہ TTL directives صرف اس وقت لاگو ہوتی ہیں جب system table پہلی بار create کی جائے۔ اس لیے existing install میں یہی docs tables میں TTL بعد میں شامل کرنے کا طریقہ بھی بتاتی ہیں۔

ایک اور table کے بارے میں جاننا مفید ہے۔ blob_storage_file_log آپ کے bucket میں upload کی گئی event files کو track کرتی ہے۔ اگر آپ bucket پر lifecycle policy بھی set کرتے ہیں تو table کے لیے matching TTL مقرر کریں، تاکہ دونوں میں وقت کے ساتھ فرق پیدا نہ ہو۔

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

data disk پر سادہ df -h alert بھی لگائیں۔ Traces ہموار رفتار سے نہیں بڑھتے۔ جس دن آپ نیا agent deploy کرتے ہیں، اسی دن ان کا حجم اچانک بڑھ سکتا ہے۔ اس کی پہلی علامت ingestion کا fail ہونا نہیں ہونی چاہیے۔

Postgres اور ClickHouse کا بیک اپ لیں

Langfuse کے بیک اپ کے تین حصے ہوتے ہیں۔ Postgres میں users، organisations، projects اور API keys محفوظ ہوتی ہیں۔ ClickHouse میں traces محفوظ ہوتے ہیں۔ MinIO میں raw events محفوظ ہوتے ہیں۔ صرف Postgres بحال کرنے سے login کام کرنے لگتا ہے، لیکن کوئی history موجود نہیں ہوتی۔ صرف ClickHouse بحال کرنے سے history تو مل جاتی ہے، لیکن اسے دیکھنے کے لیے کوئی login نہیں کر سکتا۔ یہ تقسیم صرف Langfuse تک محدود نہیں ہے۔ self-hosted Chatwoot support desk کی ساخت بھی ایسی ہی ہے، جہاں uploads directory کے بغیر لیا گیا Postgres dump ایسی conversations بحال کرتا ہے جن کی تمام attachments غائب ہوتی ہیں۔

Postgres ایک سادہ pg_dump ہے، اور Docker installation کے لیے Langfuse کی backup documentation بھی یہی استعمال کرتی ہے۔

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

ClickHouse کے لیے زیادہ احتیاط ضروری ہے، کیونکہ merges کے دوران live data directory کی copy مستقل backup نہیں ہوتی۔ ایک ہی server پر آسان طریقہ یہ ہے کہ container روک کر volume کو archive کر لیا جائے۔

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

docker volume ls جو volume name دکھائے، وہی استعمال کریں؛ YAML میں لکھا ہوا نام استعمال نہ کریں۔ فائل میں langfuse_clickhouse_data درج ہے، اور Compose اس کے آگے project name کا prefix لگا دیتا ہے۔ اس لیے langfuse نام کی directory میں clone کرنے سے langfuse_langfuse_clickhouse_data بنتا ہے۔ اگر یہ نام غلط ہو تو docker run بغیر کسی error کے نیا خالی volume بنا دیتا ہے، اور آپ کے archive میں کچھ بھی موجود نہیں ہوتا۔

Langfuse ہر ingestion request پر raw event data کو bucket میں upload کرتا ہے اور failed ingestion jobs کو دوبارہ آزمانے کے لیے اسے پھر پڑھتا ہے۔ اس لیے ClickHouse کو مختصر وقت کے لیے روکنے کا عموماً مطلب یہ ہوتا ہے کہ worker بعد میں دوبارہ کوشش کرے گا۔ یہ کام کم مصروف وقت میں کریں اور وقفہ مختصر رکھیں۔ زیادہ مصروف instance کے لیے ClickHouse کا اپنا BACKUP DATABASE default TO S3(...) statement server روکے بغیر مستقل backup لکھتا ہے۔ MinIO تیسرا حصہ ہے، اور mc mirror یا MinIO replication کے ذریعے off-box bucket میں replication اسے محفوظ کر دیتی ہے۔ آپ جو بھی backup بنائیں، اسے server سے باہر منتقل کریں۔ VPS پر encrypted restic backups اسی مقصد کے لیے ہیں۔

Redis queue اور cache محفوظ رکھتا ہے۔ Redis ضائع ہونے سے queued jobs ضائع ہو جاتے ہیں، چاہے ان کی raw event files bucket میں موجود رہیں۔

Consistency سے متعلق یہ احتیاط حقیقی ہے اور اسے واضح طور پر بیان کرنا ضروری ہے۔ Postgres اور ClickHouse مختلف اوقات میں dump ہوتے ہیں، اس لیے restore کے بعد کسی project کی row موجود ہو سکتی ہے لیکن اس کے traces نہ ہوں، یا ایسے traces موجود ہوں جن کا project اب باقی نہ رہا ہو۔ Langfuse اس صورت حال کو برداشت کرتا ہے، لیکن دونوں dumps قریب قریب ایک ہی وقت میں اور کم network traffic کے دوران لیں۔ Event bucket اصل safety net ہے، کیونکہ Langfuse ہر ingestion request پر raw event data وہاں upload کرتا ہے۔

کم از کم ایک بار scratch stack میں restore کریں۔ اس طرح outage کے دوران نہیں، بلکہ ابھی معلوم ہو جاتا ہے کہ volume name غلط ہے۔

پہلے کس چیز کا جائزہ لیں

پہلے ہفتے میں چار چیزیں شامل کرنا قابلِ قدر ہے۔

  • ہر trace کی لاگت۔ Langfuse ماڈل کے نام اور token کے استعمال سے لاگت کا حساب لگاتا ہے، اس لیے traces کو لاگت کے لحاظ سے sort کریں اور سب سے مہنگے trace کو شروع سے آخر تک پڑھیں۔ عموماً مسئلہ ایسا prompt ہوتا ہے جو بہت بڑا ہو گیا ہو: پورا document context میں paste کر دیا گیا ہو، یا conversation history کو کوئی trim نہ کرتا ہو۔ جب یہ نظر آنے لگے تو AI agent کی لاگت کو قابو میں رکھنا اندازے کے بجائے engineering task بن جاتا ہے۔
  • input اور output کے لحاظ سے token usage کی تقسیم۔ Input tokens زیادہ اور سستے ہوتے ہیں، output tokens کم اور مہنگے ہوتے ہیں، جبکہ cached input اس سے بھی سستا ہوتا ہے۔ یہی accounting Claude Code کے token usage کا حساب کیسے کیا جاتا ہے میں تفصیل سے بیان کی گئی ہے، اور اس کا اطلاق ہر اس agent پر ہوتا ہے جسے آپ خود لکھیں۔
  • Latency percentiles۔ Median مسئلہ چھپا دیتا ہے۔ p95 اور p99 پر timeouts واقع ہوتے ہیں، اور agent loop کے اندر p95 پر ہونے والی سست tool call کو iterations کی تعداد سے ضرب دی جاتی ہے۔
  • ناکام tool calls۔ Observations کو level ERROR کے لحاظ سے filter کریں۔ ایسا tool جو 5% وقت ناکام ہو، مجموعی success rate میں نظر نہیں آتا، لیکن traces میں واضح دکھائی دیتا ہے، جہاں آپ model کو دوبارہ کوشش کرتے اور پھر اس کے گرد کام کرنے کے لیے tokens خرچ کرتے دیکھتے ہیں۔

Retention window مقرر کریں اور وہ dashboard منتخب کریں جسے آپ deployment والے دن ہی ہر ہفتے ایک ہی دن check کریں گے۔ ایسا observability tool جسے کوئی نہیں کھولتا، دراصل وہ database ہے جو disk بھر دیتا ہے۔

FAQ

self-hosted Langfuse کے لیے کتنی memory درکار ہے؟

4 CPU cores اور 16 GiB memory مختص کریں۔ ایک virtual machine کے لیے Langfuse کی Docker Compose guide یہی تجویز کرتی ہے۔ اس کے علاوہ تقریباً 100 GiB storage بھی درکار ہے۔ شائع کردہ component minimums کے مطابق ClickHouse کے لیے 8 GiB، جبکہ web اور worker containers کے لیے فی container 4 GiB درکار ہے۔ اسی صفحے پر Postgres کے لیے 4 GiB، Redis کے لیے 1.5 GiB اور MinIO کے لیے 4 GiB درج ہیں۔ یوں تمام چھ components کا مجموعہ 25.5 GiB بنتا ہے، جو 16 GiB کی Compose recommendation سے زیادہ ہے۔

data retention مقرر کرنے کے بعد بھی میری ClickHouse disk کیوں بھر رہی ہے؟

Retention setting صرف Langfuse کے اپنے data پر لاگو ہوتی ہے۔ ClickHouse الگ سے اپنی diagnostic tables trace_log، text_log، opentelemetry_span_log، metric_log، asynchronous_metric_log اور latency_log میں data لکھتا ہے، اور ان tables کے ساتھ کوئی TTL شامل نہیں ہوتا۔ Table کے لحاظ سے grouping کر کے system.parts query چلائیں تاکہ معلوم ہو سکے کہ کون سی table سب سے بڑی ہے۔ پھر /etc/clickhouse-server/config.d/ کے تحت موجود کسی file میں remove="1" entry شامل کر کے غیر استعمال شدہ tables disable کریں، ClickHouse restart کریں، اور پہلے سے موجود tables drop کر دیں تاکہ استعمال شدہ space واپس حاصل ہو سکے۔

Langfuse میں کم از کم data retention period کیا ہے؟

تین دن۔ Retention ہر project کے لیے project settings میں یا Organization Management API کے ذریعے مقرر کی جاتی ہے۔ ایک nightly job اس window سے پرانے traces، observations، scores اور media assets کو ClickHouse اور blob storage دونوں سے delete کرتی ہے۔ اس سے وہ media مستثنیٰ ہے جو saved dataset items سے وابستہ ہو۔ self-hosted instance میں یہ Enterprise Edition کا feature ہے اور اس کے لیے license key درکار ہوتی ہے۔ License key کے بغیر data غیر معینہ مدت تک محفوظ رہتا ہے۔ Deletion واپس نہیں کی جا سکتی، اس لیے اگر آپ کو اس window سے زیادہ پرانی history درکار ہو تو پہلے blob storage export configure کریں۔

کیا مجھے Postgres اور ClickHouse دونوں کا backup لینا ہوگا؟

ہاں، کیونکہ دونوں میں مختلف data محفوظ ہوتا ہے۔ Postgres میں users، organisations، projects اور API keys محفوظ ہوتی ہیں، جبکہ ClickHouse میں اصل trace data ہوتا ہے۔ صرف Postgres restore کرنے سے ایسا instance ملے گا جس میں login تو کیا جا سکے گا، لیکن اس کے اندر کوئی data نہیں ہوگا۔ MinIO bucket کا بھی backup لیں، کیونکہ اس میں وہ raw events محفوظ ہوتے ہیں جنہیں Langfuse وصول کرتے ہی persist کرتا ہے۔ اس stack میں یہ source of truth سے قریب ترین چیز ہے۔

کیا میں اپنے موجودہ OpenTelemetry setup کو self-hosted Langfuse کی طرف بھیج سکتا ہوں؟

ہاں۔ Langfuse v4 اور اس کے موجودہ SDKs OpenTelemetry پر مبنی ہیں، اور Anthropic اور OpenAI OTel instrumentations براہ راست اس میں export کرتی ہیں۔ Python میں pip install langfuse opentelemetry-instrumentation-anthropic چلائیں، startup پر ایک مرتبہ AnthropicInstrumentor().instrument() call کریں، اور LANGFUSE_PUBLIC_KEY، LANGFUSE_SECRET_KEY اور LANGFUSE_BASE_URL کو اپنے host پر set کریں۔ Missing dashboard تلاش کرنے سے پہلے langfuse.auth_check() کے ذریعے تصدیق کریں۔

کیا یہ مضمون مفید تھا؟