SSD Nodes Learn Hosting plans →
मार्गदर्शक Matt Connorद्वारे Matt Connor

Langfuse स्वतःच्या VPS वर कसे self-host करावे

Langfuse स्वतःच्या VPS वर चालवताना किमान resources, pinned image tags, TLS आणि ClickHouse retention आधी ठरवा. Disk भरू नये म्हणून काम करणारे backups तपासा.

AI agent चे trace मुळात का घ्यावे

तुमच्या agent ने एखाद्या run मध्ये प्रत्यक्षात काय केले हे पाहण्यासाठी तुम्ही Langfuse self-host करता. 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 फक्त संख्या देते. Trace ती संख्या निर्माण करणारा code दाखवतो.

या guide मध्ये तीन संज्ञा वापरल्या आहेत. trace म्हणजे तुमच्या agent चा सुरुवातीपासून शेवटपर्यंतचा एक run. observation म्हणजे त्या run मधील एक step: सामान्य code साठी span आणि model ला केलेल्या call साठी generation. score म्हणजे trace शी जोडलेली संख्या, जी human review किंवा automated evaluator कडून मिळते. Langfuse OpenTelemetry (OTel) वापरते. हे distributed tracing साठीचे vendor neutral standard आहे. त्यामुळे तुमच्याकडे आधीपासून असलेले instrumentation Langfuse कडे निर्देशित करता येते.

स्वतः होस्ट केलेले Langfuse प्रत्यक्षात काय चालवते

Langfuse v4 हे एकच कंटेनर नाही. यात दोन अॅप्लिकेशन कंटेनर आणि चार स्टोरेज सेवा आहेत. एकाच VPS वर या सर्व सहा सेवा तुमच्या मशीनवर चालतात.

  • langfuse-web वेब इंटरफेस आणि ingestion API उपलब्ध करून देतो.
  • langfuse-worker पार्श्वभूमीत queue रिकामी करतो. तो ingestion batches parse करतो, खर्चाची गणना करतो आणि nightly retention job चालवतो.
  • Postgres मध्ये users, organisations, projects, API keys आणि prompts यांसारखा transactional data साठवला जातो.
  • ClickHouse मध्ये trace data स्वतः, म्हणजे observations आणि scores, साठवले जातात. हे analytical queries साठी तयार केलेले column store आहे. त्यामुळे शंभर दशलक्षांहून अधिक rows असलेल्या dashboard कडूनही उत्तर जलद मिळते.
  • Redis हे web आणि worker यांच्या दरम्यान असलेले queue आणि cache आहे.
  • MinIO तुमच्या मशीनवर S3 compatible object storage उपलब्ध करून देतो. यात प्रत्येक raw incoming event आणि तुम्ही जोडलेली कोणतीही 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 memory आवश्यक आहे. Chart मधील 3 components साठी ही प्रकाशित केलेली किमान मूल्ये आहेत. त्याच पानावर Postgres साठी 4 GiB, Redis किंवा Valkey साठी 1.5 GiB आणि MinIO साठी 4 GiB दिले आहेत. त्यामुळे सर्व सहा components साठीची किमान memory मिळून 25.5 GiB होते. प्रकल्पाच्या स्वतःच्या Docker Compose मार्गदर्शकात एका मशीनसाठी किमान 4 cores, 16 GiB memory आणि सुमारे 100 GiB storage सुचवले आहे. ही रक्कम components च्या किमान आवश्यकतांच्या बेरजेपेक्षा कमी आहे. त्यामुळे shared Compose मशीनसाठी 16 GiB ही आवश्यक किमान क्षमता समजा; यात अतिरिक्त headroom नाही.

हे 2 GiB plan वर चालवण्याचा प्रयत्न करू नका. ClickHouse सुरू होतो आणि काही काळ writes स्वीकारतो. त्यानंतर background merge दरम्यान बंद पडतो, कारण merge मुळे table चे मोठे parts memory मध्ये load होतात. docker compose ps मध्ये clickhouse container ची स्थिती restarting म्हणून दिसेल. dmesg मध्ये Out of memory: Killed process 1234 (clickhouse-serv) सारखी line दिसेल आणि प्रत्येक Langfuse dashboard 500 error परत करेल. भार कमी असेल, तर ClickHouse query नाकारतो आणि त्याऐवजी DB::Exception: Memory limit (total) exceeded log करतो. नियोजनासाठी 16 GiB ही क्षमता वापरा. त्याच VPS वर इतर कोणतीही सेवा चालवायची असल्यास तिच्यासाठी स्वतंत्रपणे memory राखा, कारण स्वतः होस्ट केलेल्या AFFiNE workspace सारख्या तुलनेने हलक्या stack लाही स्वतःचे काही gigabytes आवश्यक असतात आणि ClickHouse त्यातील memory परत देणार नाही.

Docker Compose वापरून Langfuse deploy करा

Repository clone करा. Stack, त्याची wiring आणि default environment हे सर्व त्यातील docker-compose.yml मध्ये असतात.

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

त्या file मध्ये बदलायची प्रत्येक value # CHANGEME ने चिन्हांकित केलेली आहे. सर्वप्रथम application secrets तयार करा.

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

ENCRYPTION_KEY हे 64 hex characters मध्ये लिहिलेले 256 bits असणे आवश्यक आहे. openssl rand -hex 32 ने नेमके हेच output मिळते. हे rest मध्ये साठवलेल्या sensitive values encrypt करते. यात instance मध्ये साठवलेल्या LLM provider keys चाही समावेश होतो. Data तयार झाल्यानंतर ते बदलल्यास त्या rows पुन्हा decrypt करता येणार नाहीत. त्यामुळे पहिल्या boot पासून याला कायमस्वरूपी value समजा. SALT तुमच्या Langfuse API keys चा hash तयार करण्यासाठी वापरले जाते. ते बदलल्यास agents सध्या वापरत असलेल्या सर्व keys invalid होतात.

त्यानंतर POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH आणि MINIO_ROOT_PASSWORD सेट करा. 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 म्हणून. यापैकी एक value चुकल्यास MinIO त्या client ला SignatureDoesNotMatch सह नाकारते. हा error worker log मध्ये दिसतो, जरी web interface निरोगी दिसत असले तरी. Tracked compose file ऐवजी या values env file मध्ये ठेवण्याची पद्धत Docker Compose env files आणि secrets मध्ये स्पष्ट केली आहे.

सुरुवात करण्यापूर्वी image tags निश्चित करा

दिलेल्या file मध्ये docker.langfuse.com/langfuse/langfuse:4 आणि docker.langfuse.com/langfuse/langfuse-worker:4 वापरले आहेत. हे tags बदलू शकतात. Langfuse सुरुवातीला Postgres आणि ClickHouse migrations आपोआप चालवते. त्यामुळे काही महिन्यांनंतर केलेला नियमित docker compose pull, त्या सकाळी backup न घेतलेल्या database वरील अनियोजित schema migration ठरू शकतो. दोन्ही images एका release वर docker-compose.override.yml मध्ये pin करा. Compose ही file दिलेल्या file वर merge करते, त्यामुळे नंतरचा git pull तुमच्या बदलांशी संघर्ष करत नाही. याच images 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

August 2026 पर्यंत version 4.3.1 हा 4.3 release मधील current version होता. त्यानंतर releases जलदगतीने आले आणि October 11, 2026 रोजी GitHub वर v4.56.0 ही latest version होती. October 31, 2026 रोजी GitHub वर v4.72.0 ही latest version होती; वरील override मध्ये तीच वापरली आहे. Project च्या GitHub releases page वर तपासा, deploy करताना त्या दिवशीची current version pin करा आणि नंतर तो number जाणीवपूर्वक बदला. दिलेल्या file मधील काही storage images साठीही हीच पद्धत वापरा, कारण त्यांचे tags देखील बदलू शकतात. postgres:17 (POSTGRES_VERSION variable चे default) आणि redis:7 major version वापरतात. दिलेल्या file मध्ये आता docker.io/clickhouse/clickhouse-server साठी exact version tag वापरला आहे. त्यामुळे exact ClickHouse version pin होते. हा नियम फक्त Langfuse साठी नाही. self-hosted openGym workout tracker या stack च्या काही भागावर चालतो, तरीही named git tag आवश्यक असतो. कारण सुरुवातीला स्वतःचा database migrate करणारी कोणतीही सेवा नियमित pull ला schema change मध्ये बदलू शकते.

Stack सुरू करा.

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

पहिल्या boot वेळी migrations चालतात. त्यामुळे कोणतीही सेवा response देण्यापूर्वी दोन किंवा तीन मिनिटे द्या. Web container सुरू झाल्यावर Ready log करतो. docker compose ps मध्ये running state असलेल्या सहा services दिसल्या पाहिजेत. एखादा container सतत restart होत असल्यास त्याच्या log मध्ये कारण असते. Web container सुरू होताना ClickHouse migrations लागू होतात. त्यामुळे चुकीचा CLICKHOUSE_MIGRATION_URL हा docker compose logs langfuse-web मध्ये दिसतो, तुम्ही tail करत असलेल्या worker log मध्ये नाही. हा variable port 9000 वरील ClickHouse native protocol वापरतो; HTTP port 8123 नाही. त्याला 8123 कडे निर्देश केल्यास web container च्या startup migrations अयशस्वी होतात. Worker धीम्या background migrations चालवतो. त्यामुळे त्या migrations चे reports त्याच्या log मध्ये दिसतात.

स्वतः server वरून health तपासा.

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 तपासत नाही. Monitor ला जोडण्यासाठी failIfDatabaseUnavailable=true हा form वापरणे योग्य आहे. Database उपलब्ध नसल्यास तो 503 return करतो. Web container traffic स्वीकारण्यासाठी तयार असल्यास /api/public/ready 200 return करतो. त्याला shutdown करण्यास सांगितल्यानंतर तो 500 return करतो. दोन्ही साधे HTTP checks आहेत. त्यामुळे Uptime Kuma status page त्यांच्यावर लक्ष ठेवू शकते आणि agents च्या आधीच stack बंद असल्याचे सांगू शकते.

TLS समोर ठेवून अतिरिक्त पोर्ट बंद करा

प्रदान केलेल्या compose फाइलमध्ये web container साठी 3000:3000 आणि MinIO साठी 9090:9000 प्रकाशित केले आहेत. दोन्ही प्रत्येक network interface वर bind होतात. सर्व्हरकडे public IP असल्यास, port 3000 स्कॅन करणाऱ्या कोणालाही तुमचे sign up पेज दिसते आणि port 9090 स्कॅन करणारा कोणीही तुमचे raw prompts असलेल्या bucket शी संवाद साधू शकतो.

केवळ firewall rule लावल्याने हे पोर्ट बंद होत नाहीत. Docker स्वतःचे DNAT rules nat table मध्ये लिहितो. ufw चे filter rules packet पाहण्यापूर्वीच ही rules लागू होतात. त्यामुळे ufw deny 3000 असूनही प्रकाशित पोर्ट खुले राहते. ही समस्या इतकी सामान्य आहे की तिच्यासाठी स्वतंत्र मार्गदर्शक आहे: Docker चे प्रकाशित पोर्ट ufw ला का वगळतात. त्याऐवजी override फाइलमध्ये loopback वर bind करा. प्रकाशित ports बदलण्यासाठी Docker Compose 2.24.4 किंवा त्यानंतरच्या आवृत्तीत !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 या मूल्यापासून callback URL तयार करतो. HTTPS proxy मागे ते http://localhost:3000 ठेवल्यास sign in ची round trip browser ला अशा ठिकाणी पाठवते जिथे तो पोहोचू शकत नाही.

आता reverse proxy ला 127.0.0.1:3000 कडे निर्देशित करा आणि certificate त्याच्याकडे ठेवा. त्याच Compose project मध्ये Traefik वापरत असल्यास, एकाच Traefik reverse proxy मागे अनेक अॅप्स चालवणे येथे दिलेल्या labels वापरून Compose network वरून langfuse-web:3000 कडे routing करा. Langfuse हेच एकमेव अॅप असल्यास Caddy दोन lines मध्ये हे काम करते. curl -sI https://langfuse.example.com/api/public/ready वापरून पडताळणी करा. त्यानंतर दुसऱ्या machine वरून curl http://YOUR_IP:3000 शी connection होऊ शकत नाही याची खात्री करा.

MinIO बाबत एक महत्त्वाची अट आहे. Langfuse media upload करणाऱ्या SDKs ना आणि media browser मध्ये load करणाऱ्या browser ला त्या S3 endpoint कडे निर्देश करणारे presigned URLs देते. त्यामुळे images किंवा audio असलेले multi-modal traces वापरत असल्यास, loopback-only MinIO मुळे attachments इतर machines वरून upload होणार नाहीत किंवा browser मध्ये load होणार नाहीत. त्याला proxy करण्यापूर्वी blob storage configuration पेज वाचा, कारण presigned URL मध्ये लिहिलेला endpoint, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, तुम्ही प्रकाशित केलेल्या endpoint शी जुळला पाहिजे. Plain text traces वर याचा परिणाम होत नाही.

पहिल्यांदा भेट देताना तुमचे account तयार करा. त्यानंतर instance वर तुमचे नियंत्रण ठेवा. तुमचे account तयार झाल्यावर AUTH_DISABLE_SIGNUP=true सेट करा, जेणेकरून पेजवर पोहोचणारा अनोळखी व्यक्ती नोंदणी करू शकणार नाही. Langfuse मध्ये LANGFUSE_ALLOWED_ORGANIZATION_CREATORS देखील आहे. यामुळे organisations तयार करण्याचा अधिकार कोणाला आहे हे मर्यादित करता येते. मात्र हे Enterprise Edition चे feature आहे आणि license key असल्यावरच लागू होते. तुम्ही तुमचा स्वतःचा identity provider म्हणून Authentik चालवत असाल, तर Langfuse standard OIDC connection स्वीकारतो. त्यामुळे accounts तुमच्या इतर अॅप्ससोबतच तयार आणि काढले जातात; या box ला माहीत असलेल्या स्वतंत्र password list मध्ये ते राहत नाहीत.

पहिला trace पाठवा

Web interface मध्ये project तयार करा आणि project settings मधून त्याच्या public आणि secret keys कॉपी करा. 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 आहे. SDK v4 मार्च 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 किंवा त्यानंतरची आवृत्ती आवश्यक आहे. वरील pinned 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 अंतर्गत त्याची nesting करतो. AnthropicInstrumentor हे Anthropic client साठीचे OpenTelemetry instrumentation आहे. ते प्रत्येक messages.create call ला model name, token usage आणि latency असलेल्या generation मध्ये रूपांतरित करते. Call site मध्ये कोणताही बदल आवश्यक नसतो.

तपासणीसाठी दोन calls पुरेसे आहेत. चुकीच्या keys किंवा चुकीच्या base URL असल्यास langfuse.auth_check() False परत करतो. त्यामुळे dashboard रिकामा का आहे याचा अंदाज लावण्यापेक्षा ही पद्धत जलद आहे. langfuse.flush() queued spans पाठवले जाईपर्यंत थांबतो. अल्पकाळ चालणाऱ्या processes साठी हे आवश्यक आहे, कारण SDK background मध्ये batching करतो आणि लगेच exit होणारी script न पाठवलेला batch सोबत घेऊन बंद होते. संपूर्ण team एकाच script ऐवजी traces पाठवत असेल, तर ही तीन variables प्रत्येक व्यक्तीच्या shell मध्ये सेट करण्याऐवजी सर्व agents आधीच ज्या gateway मधून चालतात तिथे एकदाच सेट करा. अशा प्रकारे self-hosted OneCLI harness प्रत्येक सहकाऱ्याच्या runs चे instrumentation ठेवते आणि keys एकाच ठिकाणी सुरक्षित राहतात.

ClickHouse सतत का वाढत राहते?

बहुतेक लोक self-host करत असलेल्या डेटामध्ये traces सर्वात वेगाने वाढतात. प्रत्येक agent run मध्ये प्रत्येक step साठी एक row लिहिली जाते आणि inputs व outputs पूर्णपणे साठवले जातात. त्यामुळे मोठे prompts वापरणारा आणि जास्त logs निर्माण करणारा agent, तो ज्या application वर लक्ष ठेवतो त्यापेक्षा दररोज कितीतरी अधिक bytes निर्माण करतो. हे तसेच ठेवले, तर ClickHouse मध्ये disk भरतो. Disk पूर्ण भरल्यावर ingestion मंद होत नाही; ते थांबते.

येथे दोन स्वतंत्र गोष्टी वाढतात आणि त्यांच्यासाठी दोन स्वतंत्र उपाय आवश्यक आहेत.

पहिली गोष्ट म्हणजे तुमचा स्वतःचा trace data. यासाठी retention setting वापरावी. self-hosted instance मध्ये data retention हे Enterprise Edition चे feature आहे आणि त्यासाठी license key आवश्यक आहे. License key नसल्यास Langfuse traces, observations, scores आणि media अनिश्चित काळासाठी ठेवते. त्यामुळे disk capacity त्यानुसार ठरवा आणि या section च्या शेवटी दिलेल्या disk alert वर अवलंबून रहा. License असल्यास project owners आणि admins project settings उघडून data retention period दिवसांमध्ये सेट करू शकतात. Langfuse किमान 3 days स्वीकारते. त्यानंतर nightly job त्या कालावधीपेक्षा जुने traces, observations, scores आणि media assets निवडते आणि saved dataset items शी संबंधित media वगळता ते ClickHouse आणि blob storage मधून हटवते. या job ला bucket वर DeleteObject permission आवश्यक आहे. Default compose file मधील MinIO root credentials कडे ही permission आधीपासून असते. Deletion कायमची असते. त्यामुळे दीर्घकालीन history आवश्यक असल्यास आधी blob storage export configure करा. Langfuse च्या स्वतःच्या tables वर TTL clauses स्वतः लिहू नका. Retention job ClickHouse आणि bucket यांना समक्रमित ठेवते, तर manual TTL केवळ एका बाजूचा data हटवते.

तुम्ही प्रत्यक्षात data कसा वापरता त्यानुसार retention window निवडा. Cost आणि quality review अनेक महिन्यांपूर्वीच्या data ऐवजी काही दिवस जुन्या data वर केले जाते. छोट्या team साठी 30 days ही योग्य सुरुवात आहे. काहीतरी बिघडल्यावरच trace उघडत असाल, तर 14 days पुरेसे आहेत.

दुसरी गोष्ट म्हणजे 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 त्यांना कधीही वाचत नाही. आधी disk space नेमके कुठे वापरले गेले ते शोधा.

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 startup वेळी /etc/clickhouse-server/config.d/ मधील प्रत्येक file मुख्य 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 वापरून आणि हटवलेल्या प्रत्येक table साठी त्याच पद्धतीने space स्पष्टपणे reclaim करा. Diagnostics ठेवायचे असल्यास remove="1" ऐवजी प्रत्येक table वर aggressive TTL लावणे हा पर्याय आहे. Langfuse scaling docs मध्ये याची सविस्तर माहिती आहे. हे TTL directives system table पहिल्यांदा तयार होताना लागू होतात. त्यामुळे existing install साठी tables मध्ये नंतर हे लागू करण्याची पद्धतही त्याच docs मध्ये दिली आहे.

आणखी एका table बद्दल माहिती असणे उपयुक्त आहे. blob_storage_file_log तुमच्या bucket वर upload केलेल्या event files चा मागोवा घेते. Bucket वर lifecycle policy देखील configure केली असल्यास, table साठी त्याच्याशी जुळणारा TTL द्या. त्यामुळे दोन्हींच्या कालावधीत फरक पडणार नाही.

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

Data disk वर साधा df -h alert देखील configure करा. Traces समान वेगाने वाढत नाहीत. नवीन agent release केल्याच्या दिवशी ते मोठ्या प्रमाणात वाढू शकतात. याचे पहिले लक्षण ingestion fail होणे नसावे.

Postgres आणि ClickHouse चा बॅकअप

Langfuse बॅकअपचे तीन भाग असतात. Postgres मध्ये तुमचे वापरकर्ते, संस्था, प्रकल्प आणि API keys असतात. ClickHouse मध्ये traces असतात. MinIO मध्ये raw events असतात. फक्त Postgres restore केल्यास login कार्यरत होतो, पण कोणताही इतिहास मिळत नाही. फक्त ClickHouse restore केल्यास इतिहास मिळतो, पण तो पाहण्यासाठी कोणीही login करू शकत नाही. ही विभागणी फक्त Langfuseपुरती मर्यादित नाही. self-hosted Chatwoot support desk मध्येही अशीच रचना असते. uploads directory शिवाय घेतलेला Postgres dump restore केल्यास conversations परत मिळतात, पण त्यांची सर्व attachments गहाळ असतात.

Postgres हा साधा pg_dump आहे. Docker install साठी Langfuse च्या बॅकअप दस्तऐवजात हीच पद्धत वापरली आहे.

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

ClickHouse साठी अधिक काळजी घ्यावी लागते. merges सुरू असताना live data directory कॉपी केल्यास consistent backup मिळत नाही. एका मशीनवरील सोपी पद्धत म्हणजे 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 लावते. त्यामुळे langfuse नावाच्या directory मधील clone साठी langfuse_langfuse_clickhouse_data तयार होते. हे चुकीचे ठरल्यास docker run कोणतीही सूचना न देता नवीन रिकामा volume तयार करते आणि तुमच्या archive मध्ये काहीही नसते.

Langfuse प्रत्येक ingestion request वेळी raw event data bucket मध्ये upload करते आणि अयशस्वी ingestion jobs पुन्हा प्रयत्न करण्यासाठी ते data पुन्हा वाचते. त्यामुळे ClickHouse थोड्या वेळासाठी थांबवल्यास worker नंतर बहुतेक वेळा पुन्हा प्रयत्न करतो. हे कमी वापराच्या वेळेत करा आणि downtime कमी ठेवा. अधिक व्यस्त instance साठी ClickHouse चे स्वतःचे BACKUP DATABASE default TO S3(...) statement server थांबविल्याशिवाय consistent backup लिहिते. MinIO हा तिसरा भाग आहे. mc mirror किंवा off-box bucket वर MinIO replication यासाठी पुरेसे आहे. तुम्ही कोणतीही पद्धत वापरली तरी बॅकअप server बाहेर ठेवा. VPS वरील encrypted restic backups यासाठीच वापरले जातात.

Redis मध्ये queue आणि cache असतात. ते गमावल्यास queued jobs नष्ट होतात, जरी त्यांच्या raw event files bucket मध्ये शिल्लक असल्या तरी.

Consistency संबंधीची अट वास्तविक आहे आणि ती स्पष्टपणे सांगणे आवश्यक आहे. Postgres आणि ClickHouse चे dumps वेगवेगळ्या वेळी घेतले जातात. त्यामुळे restore केल्यानंतर traces नसलेली project row राहू शकते किंवा अस्तित्वात नसलेल्या project शी संबंधित traces राहू शकतात. Langfuse ही स्थिती हाताळते. तरीही दोन्ही dumps शक्य तितक्या जवळच्या वेळी आणि कमी traffic असताना घ्या. Event bucket ही खऱ्या अर्थाने safety net आहे, कारण Langfuse प्रत्येक ingestion request वेळी raw event data तेथे upload करते.

किमान एकदा scratch stack मध्ये restore करून पाहा. चुकीचे volume name outage च्या वेळी नव्हे, तर आत्ताच लक्षात येण्यासाठी हीच पद्धत उपयोगी ठरते.

प्रथम काय तपासावे

पहिल्या आठवड्यात चार गोष्टींना प्राधान्य द्या.

  • प्रति trace खर्च. Langfuse model name आणि token usage वरून खर्च मोजते. त्यामुळे traces खर्चानुसार क्रमवारीत लावा आणि सर्वाधिक खर्चिक trace सुरुवातीपासून शेवटपर्यंत वाचा. याचे कारण सहसा वाढलेला prompt असतो: संपूर्ण document context मध्ये paste केलेला असतो किंवा कोणीही trim न केलेला conversation history असतो. हे दिसू लागल्यानंतर, AI agent चा खर्च नियंत्रित करणे हा अंदाजाचा विषय न राहता engineering task बनतो.
  • Input आणि output नुसार token usage चे विभाजन. Input tokens ची संख्या जास्त आणि किंमत कमी असते. Output tokens ची संख्या कमी आणि किंमत जास्त असते. Cached input ची किंमत त्याहूनही कमी असते. याच accounting चे स्पष्टीकरण Claude Code token usage कसे मोजले जाते येथे दिले आहे. तुम्ही स्वतः लिहिलेल्या कोणत्याही agent ला हे लागू होते.
  • Latency percentiles. Median मुळे समस्या लपते. Timeout बहुतेकदा p95 आणि p99 मध्ये दिसतात. Agent loop मध्ये p95 वरील धीमा tool call iterations च्या संख्येने अनेकदा वाढतो.
  • अपयशी tool calls. Observations ला level ERROR नुसार filter करा. एखादा tool 5% वेळा अपयशी ठरत असेल, तर aggregate success rate मध्ये तो दिसणार नाही. मात्र traces मध्ये तो स्पष्ट दिसेल; तिथे model पुन्हा प्रयत्न करताना आणि त्याभोवती काम करण्यासाठी tokens खर्च करताना दिसतो.

Retention window निश्चित करा. Deploy करतानाच प्रत्येक आठवड्यात कोणत्या दिवशी dashboard तपासायचा ते ठरवा. कोणीही उघडत नसलेले observability tool disk भरत जाणारा database ठरतो.

FAQ

self-hosted Langfuse साठी किती memory आवश्यक आहे?

4 CPU cores आणि 16 GiB memory साठी नियोजन करा. एका virtual machine साठी Langfuse Docker Compose मार्गदर्शकात हीच शिफारस केली आहे. याशिवाय सुमारे 100 GiB storage आवश्यक आहे. प्रकाशित component minimums नुसार ClickHouse साठी 8 GiB आणि web व worker containers साठी प्रत्येकी 4 GiB आवश्यक आहे. त्याच पृष्ठावर Postgres साठी 4 GiB, Redis साठी 1.5 GiB आणि MinIO साठी 4 GiB दिले आहेत. त्यामुळे सर्व सहा components मिळून 25.5 GiB होतात. हे Compose च्या 16 GiB शिफारसीपेक्षा जास्त आहे.

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 सर्वात मोठा आहे हे पाहण्यासाठी system.parts ला table नुसार group करा. त्यानंतर /etc/clickhouse-server/config.d/ अंतर्गत असलेल्या file मध्ये remove="1" entry देऊन वापरात नसलेले tables disable करा. ClickHouse restart करा आणि आधीपासून तयार असलेले tables drop करा, म्हणजे त्यांनी व्यापलेली जागा परत मिळेल.

Langfuse मध्ये minimum data retention period किती आहे?

तीन दिवस. Retention प्रत्येक project साठी project settings मध्ये किंवा Organization Management API द्वारे सेट करता येते. Nightly job या कालावधीपेक्षा जुने traces, observations, scores आणि media assets ClickHouse आणि blob storage या दोन्ही ठिकाणांहून delete करते. मात्र saved dataset items शी संबंधित media याला अपवाद आहे. Self-hosted instance मध्ये हे Enterprise Edition feature आहे आणि यासाठी license key आवश्यक आहे. License key नसल्यास data अमर्याद काळासाठी ठेवला जातो. Deletion पूर्ववत करता येत नाही. त्यामुळे त्या कालावधीपलीकडील history आवश्यक असल्यास आधी blob storage export configure करा.

Postgres आणि ClickHouse या दोन्हींचा backup घ्यावा लागतो का?

होय, कारण दोन्ही ठिकाणी वेगवेगळे data असते. Postgres मध्ये users, organisations, projects आणि API keys असतात. ClickHouse मध्ये प्रत्यक्ष trace data असतो. फक्त Postgres restore केल्यास login करता येईल अशी instance मिळेल, पण त्यात कोणताही trace data नसेल. MinIO bucket चा backup देखील घ्या. Langfuse arrival वेळी persist करते ते raw events त्यात असतात. Stack मधील source of truth म्हणून यालाच सर्वात जवळचे मानता येते.

विद्यमान OpenTelemetry setup self-hosted Langfuse कडे point करता येईल का?

होय. Langfuse v4 आणि त्याचे current 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 सेट करा. Dashboard दिसत नाही म्हणून troubleshooting सुरू करण्यापूर्वी langfuse.auth_check() ने पडताळणी करा.

हा लेख उपयुक्त होता का?