Langfuse-ஐ உங்கள் சொந்த VPS-ல் self-host செய்வது எப்படி?
Langfuse-ஐ உங்கள் சொந்த VPS-ல் இயக்குவதற்கான முழுமையான வழிகாட்டி. ClickHouse disk space மேலாண்மை, TLS அமைப்பு, pinned image tags மற்றும் நம்பகமான backup முறைகளை இதில் விரிவாகக் காணலாம்.
AI agent-ஐ ஏன் கண்காணிக்க (trace) வேண்டும்
உங்கள் agent ஒரு run-ல் உண்மையில் என்ன செய்தது என்பதைப் பார்க்க, நீங்கள் Langfuse-ஐ self-host செய்யலாம். Langfuse என்பது ஒரு open source LLM (large language model) observability கருவியாகும். இது ஒவ்வொரு prompt, model response, tool call மற்றும் token ஆகியவற்றை பதிவு செய்து, அவற்றை நீங்கள் திறந்து வாசிக்கக்கூடிய ஒரு trace-ஆக தொகுக்கிறது. இதை உங்கள் சொந்த VPS-ல் இயக்குவதன் மூலம், அந்த prompt-கள் உங்கள் கட்டுப்பாட்டில் உள்ள server-ஐ விட்டு வெளியேறாது.
இதற்கான காரணம் தெளிவானது. உங்களால் பார்க்க முடியாத ஒரு செலவுப் பிரச்சனையையோ அல்லது தரப் பிரச்சனையையோ உங்களால் சரிசெய்ய முடியாது. ஒரு provider invoice, திங்கட்கிழமையை விட செவ்வாய்க்கிழமை நான்கு மடங்கு செலவு அதிகம் என்று மட்டும் சொல்லும். ஆனால், ஒரு trace எந்த agent run-ல் இது நடந்தது, எந்த prompt 40,000 tokens வரை வளர்ந்தது, மற்றும் எந்த retry loop ஒன்பது முறை இயங்கிய பின் தோல்வியடைந்தது என்பதைத் துல்லியமாகக் காட்டும். Invoice வெறும் எண்ணை மட்டுமே தரும். Trace அந்த எண்ணை உருவாக்கிய code-ஐயே தரும்.
இந்த வழிகாட்டி முழுவதும் மூன்று கலைச்சொற்கள் பயன்படுத்தப்படுகின்றன. ஒரு trace என்பது உங்கள் agent-ன் ஒரு முழுமையான run ஆகும். ஒரு observation என்பது அந்த run-க்குள் நடக்கும் ஒரு படிநிலை: சாதாரண code-க்கான span, அல்லது model-க்கான அழைப்பு (generation). ஒரு score என்பது மனித மதிப்பாய்வு அல்லது தானியங்கி மதிப்பீட்டாளர் மூலம் ஒரு trace-க்கு வழங்கப்படும் எண் ஆகும். Langfuse, distributed tracing-க்கான vendor neutral தரநிலையான OpenTelemetry (OTel)-ஐ ஆதரிக்கிறது. எனவே, உங்களிடம் ஏற்கனவே உள்ள instrumentation-ஐ இதனுடன் இணைக்க முடியும்.
Langfuse self-hosting-ல் உண்மையில் என்ன இயங்குகிறது
Langfuse v4 என்பது ஒரே ஒரு container அல்ல. இது இரண்டு application container-கள் மற்றும் நான்கு storage service-களைக் கொண்டது. ஒரு தனி VPS-ல் இந்த ஆறுமே உங்கள் server-ல் இயங்கும்.
langfuse-webweb interface மற்றும் ingestion API-ஐ வழங்குகிறது.langfuse-workerபின்னணியில் queue-ஐக் கையாளுகிறது. இது ingestion batches-ஐப் பிரித்து, செலவைக் கணக்கிட்டு, nightly retention job-ஐ இயக்குகிறது.- Postgres பயனர்கள், நிறுவனங்கள், திட்டங்கள், API keys மற்றும் prompts போன்ற transactional தரவுகளைச் சேமிக்கிறது.
- ClickHouse trace தரவுகளை, அதாவது observations மற்றும் scores-ஐச் சேமிக்கிறது. இது analytical queries-க்காக உருவாக்கப்பட்ட column store ஆகும். இதனால்தான் நூறு மில்லியன் rows கொண்ட dashboard-லும் முடிவுகள் விரைவாகக் கிடைக்கின்றன.
- Redis என்பது web மற்றும் worker-க்கு இடையே உள்ள queue மற்றும் cache ஆகும்.
- MinIO உங்களுக்கு S3 compatible object storage-ஐ வழங்குகிறது. இது உள்ளே வரும் அனைத்து raw events மற்றும் நீங்கள் இணைக்கும் media கோப்புகளைச் சேமிக்கிறது.
Langfuse தான் இயக்கும் ஒவ்வொரு component-க்கும் தேவையான குறைந்தபட்ச வளங்களை (resources) வெளியிடுகிறது. கீழே உள்ள அட்டவணை பணியைச் செய்யும் மூன்றைக் காட்டுகிறது.
இந்த விளக்கப்படத்தின் தரவு
[
{
"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 தேவை. இவை அட்டவணையில் உள்ள 3 component-களுக்கான குறைந்தபட்ச அளவுகள் ஆகும். அதே பக்கத்தில் Postgres-க்கு 4 GiB, Redis அல்லது Valkey-க்கு 1.5 GiB மற்றும் MinIO-க்கு 4 GiB எனப் பட்டியலிடப்பட்டுள்ளது. எனவே, இந்த ஆறுக்கும் சேர்த்து மொத்தம் 25.5 GiB தேவைப்படுகிறது. திட்டத்தின் சொந்த Docker Compose வழிகாட்டி, ஒரு தனி machine-க்கு குறைந்தபட்சம் 4 cores, 16 GiB memory மற்றும் சுமார் 100 GiB storage-ஐப் பரிந்துரைக்கிறது. இது component-களின் குறைந்தபட்ச தேவைகளின் கூட்டுத்தொகையை விடக் குறைவு என்பதால், 16 GiB-ஐ ஒரு shared Compose box-க்குத் தேவையான மிகக்குறைந்த அளவாகக் கருதவும்; இதை உபரி வளமாக (headroom) நினைக்க வேண்டாம்.
இதை 2 GiB plan-ல் முயற்சி செய்ய வேண்டாம். ClickHouse தொடங்கும், சிறிது நேரம் தரவுகளை ஏற்கும், ஆனால் background merge-ன் போது நின்றுவிடும். ஏனெனில், merge செயல்முறை table-ன் பெரிய பகுதிகளை memory-ல் ஏற்றும். அப்போது docker compose ps, clickhouse container-ஐ restarting என்று காட்டும், dmesg-ல் Out of memory: Killed process 1234 (clickhouse-serv) போன்ற வரிகள் இருக்கும், மேலும் அனைத்து Langfuse dashboard-களும் 500 பிழையைத் தரும். குறைந்த அழுத்தத்தில் ClickHouse query-ஐ நிராகரித்துவிட்டு DB::Exception: Memory limit (total) exceeded என்று log செய்யும். திட்டமிடுவதற்கு 16 என்பதுதான் சரியான எண். அதே VPS-ல் வேறு எதையாவது இயக்கத் திட்டமிட்டால், அதற்கான வளங்களைத் தனியாக ஒதுக்குங்கள். ஏனெனில், self-hosted AFFiNE workspace போன்ற ஒப்பீட்டளவில் இலகுவான stack-கிற்குக்கூட சில gigabytes தேவைப்படும், ClickHouse தான் எடுத்துக்கொண்ட memory-ஐத் திருப்பித் தராது.
Docker Compose மூலம் Langfuse-ஐ நிறுவுதல்
Repository-ஐ clone செய்யவும். Stack, அதன் இணைப்பு மற்றும் இயல்புநிலை சூழல் (default environment) அனைத்தும் அதன் docker-compose.yml-ல் உள்ளன.
git clone https://github.com/langfuse/langfuse.git
cd langfuseநீங்கள் மாற்ற வேண்டிய ஒவ்வொரு மதிப்பும் அந்த கோப்பில் # CHANGEME எனக் குறிக்கப்பட்டுள்ளது. முதலில் மூன்று application secrets-ஐ உருவாக்கவும்.
openssl rand -base64 32 # NEXTAUTH_SECRET
openssl rand -base64 32 # SALT
openssl rand -hex 32 # ENCRYPTION_KEYENCRYPTION_KEY என்பது 64 hex characters கொண்ட 256 bits மதிப்பாக இருக்க வேண்டும், இதைத்தான் openssl rand -hex 32 வெளியிடுகிறது. இது உங்கள் instance-ல் சேமிக்கப்படும் LLM provider keys உட்பட அனைத்து முக்கியமான தரவுகளையும் encrypt செய்கிறது. தரவுகள் உள்ளே வந்த பிறகு இதை மாற்றினால், அந்த தரவுகளை மீண்டும் decrypt செய்ய முடியாது, எனவே முதல் boot-லிருந்தே இதை நிரந்தரமான ஒன்றாகக் கருதவும். SALT உங்கள் Langfuse API keys-ஐ hash செய்யப் பயன்படுகிறது, எனவே இதை மாற்றினால் உங்கள் agents பயன்படுத்தும் அனைத்து keys-ம் செல்லாததாகிவிடும்.
பிறகு 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. இதில் ஒன்றை தவறவிட்டாலும் MinIO அந்த client-ஐ SignatureDoesNotMatch பிழையுடன் நிராகரிக்கும்; web interface சரியாகத் தெரிந்தாலும், இந்த பிழை worker log-ல் பதிவாகும். இந்த மதிப்புகளை tracked compose file-ல் வைக்காமல் env file-ல் வைத்திருப்பது Docker Compose env files and secrets-ல் விவரிக்கப்பட்டுள்ள முறையாகும்.
தொடங்கும் முன் image tags-ஐ நிலைநிறுத்தவும் (Pin)
வழங்கப்பட்ட கோப்பு 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-ஐ ஏற்படுத்தலாம். இரண்டையும் ஒரு docker-compose.override.yml-ல் ஒரே release-க்கு நிலைநிறுத்தவும் (pin). Compose இதை வழங்கப்பட்ட கோப்பின் மேல் இணைக்கும், இதனால் பிற்காலத்தில் செய்யப்படும் 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ஆகஸ்ட் 2026 நிலவரப்படி, 4.3.1 என்பது தற்போதைய 4.3 release ஆகும். அதன்பிறகு releases வேகமாக வந்துள்ளன, அக்டோபர் 11, 2026 நிலவரப்படி v4.56.0 என்பது GitHub-ல் சமீபத்தியதாக இருந்தது. மேலே உள்ள override, அக்டோபர் 31, 2026 நிலவரப்படி GitHub-ல் சமீபத்தியதாக உள்ள v4.72.0-ஐப் பயன்படுத்துகிறது. திட்டத்தின் GitHub releases பக்கத்தைச் சரிபார்த்து, நீங்கள் நிறுவும் நாளில் எது சமீபத்தியதோ அதை நிலைநிறுத்தி, பிறகு அந்த எண்ணை கவனமாக மாற்றவும். வழங்கப்பட்ட கோப்பில் உள்ள சில storage images-ம் இதே கவனத்திற்கு உரியவை, ஏனெனில் அவற்றின் tags-ம் மாறக்கூடியவை. postgres:17 (ஒரு POSTGRES_VERSION மாறியின் இயல்புநிலை) மற்றும் redis:7 ஆகியவை major version-ஐப் பின்பற்றுகின்றன. வழங்கப்பட்ட கோப்பு இப்போது docker.io/clickhouse/clickhouse-server-க்கு ஒரு துல்லியமான version tag-ஐப் பயன்படுத்துகிறது, இது ClickHouse version-ஐ நிலைநிறுத்துகிறது. இந்த விதி Langfuse-க்கு மட்டும் உரியதல்ல: ஒரு self-hosted openGym workout tracker இந்த stack-ன் ஒரு பகுதியை மட்டுமே இயக்குகிறது, ஆனாலும் அதற்கு ஒரு குறிப்பிட்ட git tag தேவைப்படுகிறது. ஏனெனில், தொடக்கத்திலேயே தனது database-ஐ migrate செய்யும் எந்தவொரு மென்பொருளும், வழக்கமான pull-ஐ ஒரு schema மாற்றமாக மாற்றிவிடக்கூடும்.
அதை இயக்கவும்.
docker compose up -d
docker compose ps
docker compose logs -f langfuse-workerமுதல் boot-ன் போது migrations இயங்கும், எனவே எதற்கும் பதில் கிடைக்கும் முன் இரண்டு அல்லது மூன்று நிமிடங்கள் காத்திருக்கவும். Web container தயாரானதும் Ready என log-ல் பதிவாகும். docker compose ps கட்டளை ஆறு services-ம் running நிலையில் இருப்பதை உறுதிப்படுத்த வேண்டும். ஒரு container மீண்டும் மீண்டும் restart ஆனால், அதன் log-ல் அதற்கான காரணம் இருக்கும். Web container தொடங்கும் போதுதான் ClickHouse migrations பயன்படுத்தப்படும், எனவே ஒரு தவறான CLICKHOUSE_MIGRATION_URL, நீங்கள் கவனித்துக் கொண்டிருக்கும் worker log-ல் தெரியாமல் docker compose logs langfuse-web-ல் தெரியும். அந்த மாறி port 9000-ல் உள்ள ClickHouse native protocol-ஐப் பயன்படுத்துகிறது, HTTP port 8123-ஐ அல்ல; அதை 8123-க்கு மாற்றினால் web container-ன் startup migrations தோல்வியடையும். Worker மெதுவான background migrations-ஐ இயக்குவதால், அவை அந்த 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 அழைப்பு, API process இயங்குகிறது என்பதை மட்டுமே உறுதிப்படுத்தும், ஏனெனில் இது இயல்பாக database-ஐச் சரிபார்ப்பதில்லை. failIfDatabaseUnavailable=true வடிவம் தான் monitor-க்குக் கொடுக்க வேண்டியது, database அணுக முடியாதபோது இது 503-ஐத் தரும். Web container traffic-ஐப் பெறத் தயாராக இருக்கும்போது /api/public/ready 200-ஐத் தரும், அது நிறுத்தப்பட வேண்டும் என்று கட்டளையிடப்பட்ட பிறகு 500-ஐத் தரும். இவை இரண்டும் சாதாரண HTTP checks என்பதால், ஒரு Uptime Kuma status page மூலம் இவற்றைத் தொடர்ந்து கண்காணித்து, உங்கள் agents-க்குத் தெரியும் முன்பே stack செயலிழந்துள்ளதை நீங்கள் அறியலாம்.
TLS-ஐ முன்னால் வைத்து கூடுதல் போர்ட்களை மூடுதல்
வழங்கப்பட்ட compose file, web container-க்காக 3000:3000 மற்றும் MinIO-க்காக 9090:9000 ஆகிய போர்ட்களை வெளியிடுகிறது (publish). இவை இரண்டுமே அனைத்து interface-களிலும் bind ஆகின்றன. ஒரு public IP-ல், போர்ட் 3000-ஐ ஸ்கேன் செய்யும் எவரும் உங்கள் sign up பக்கத்தை அடைய முடியும்; போர்ட் 9090-ஐ ஸ்கேன் செய்யும் எவரும் உங்கள் raw prompts-களைக் கொண்ட bucket-உடன் தொடர்பு கொள்ள முடியும்.
Firewall விதி மட்டும் இவற்றை மூடாது. Docker தனது சொந்த DNAT விதிகளை nat table-ல் எழுதும். ufw-ன் filter விதிகள் பாக்கெட்டைப் பார்ப்பதற்கு முன்பே இவை மதிப்பீடு செய்யப்படுவதால், ufw deny 3000 வெளியிடப்பட்ட போர்ட்டைத் திறந்து வைத்திருக்கும். இது பலரை பாதிக்கும் என்பதால் இதற்கென தனி வழிகாட்டி உள்ளது: Docker published ports ஏன் ufw-ஐத் தவிர்க்கின்றன. அதற்குப் பதிலாக உங்கள் override file-ல் loopback-ல் bind செய்யவும். Docker Compose 2.24.4 அல்லது அதற்குப் பிந்தைய பதிப்புகளில் !override-ஐப் பயன்படுத்தி வெளியிடப்பட்ட போர்ட்களை மாற்றவும்; சாதாரண பட்டியல் அசல் 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-உடன் கூடிய சரியான public முகவரியாக இருக்க வேண்டும், ஏனெனில் 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-க்கு route செய்யவும். அந்த server-ல் Langfuse மட்டுமே இருந்தால், Caddy-யை இரண்டு வரிகளில் அதே வேலையைச் செய்ய வைக்கலாம். curl -sI https://langfuse.example.com/api/public/ready மூலம் சரிபார்க்கவும், பின்னர் இரண்டாவது கணினியிலிருந்து curl http://YOUR_IP:3000-ஐ அணுக முடியாது என்பதை உறுதிப்படுத்தவும்.
MinIO குறித்த ஒரு எச்சரிக்கை: Langfuse, அந்த S3 endpoint-ஐச் சுட்டிக்காட்டும் presigned URL-களை SDK-களுக்கும், அவற்றை ஏற்றும் உங்கள் உலாவிக்கும் வழங்குகிறது. எனவே, படங்கள் அல்லது ஆடியோவைக் கொண்ட multi-modal traces-ஐப் பயன்படுத்தினால், loopback-மட்டும் கொண்ட MinIO-வில் அந்த இணைப்புகள் (attachments) பிற கணினிகளிலிருந்து பதிவேற்றப்படாது அல்லது உங்கள் உலாவியில் ஏற்றப்படாது. அதை proxy செய்வதற்கு முன் blob storage configuration பக்கத்தைப் படிக்கவும், ஏனெனில் presigned URL-ல் எழுதப்பட்ட endpoint ஆன LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, நீங்கள் வெளியிடும் முகவரியுடன் ஒத்துப்போக வேண்டும். Plain text traces-க்கு இது பொருந்தாது.
முதல் வருகையின்போது உங்கள் கணக்கை உருவாக்கவும், பின்னர் அந்த instance-ஐ உங்களுடையதாகவே வைத்திருக்கவும். உங்கள் கணக்கு உருவானதும் AUTH_DISABLE_SIGNUP=true-ஐ அமைக்கவும், இதன் மூலம் அந்தப் பக்கத்தை அடையும் அந்நியர்கள் யாரும் பதிவு செய்ய முடியாது. Langfuse-ல் LANGFUSE_ALLOWED_ORGANIZATION_CREATORS வசதியும் உள்ளது, இது யார் நிறுவனங்களை உருவாக்கலாம் என்பதைக் கட்டுப்படுத்துகிறது, ஆனால் இது Enterprise Edition அம்சம் மற்றும் license key இருந்தால் மட்டுமே செயல்படும். நீங்கள் ஏற்கனவே Authentik-ஐ உங்கள் சொந்த identity provider-ஆக இயக்கி வருகிறீர்கள் என்றால், Langfuse ஒரு standard OIDC இணைப்பை ஏற்கும். இதனால் கணக்குகள் இந்த box-க்கு மட்டும் தெரிந்த password பட்டியலில் இருக்காமல், உங்கள் மற்ற செயலிகளுடன் இணைந்து செயல்படும்.
உங்கள் முதல் 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 பெயர், இது March 2026-ல் வெளியிடப்பட்டது. பழைய code மற்றும் வழிகாட்டிகள் LANGFUSE_HOST-ஐப் பயன்படுத்துகின்றன. உங்கள் traces உங்கள் server-க்கு பதிலாக Langfuse Cloud-க்கு சென்றால், base URL அமைக்கப்படாததே அதற்குக் காரணம், ஏனெனில் default மதிப்பு hosted instance-ஐக் குறிக்கும்.
தற்போதைய Python SDK v5-க்கு Python 3.11 அல்லது அதற்குப் பிந்தைய பதிப்பும், self-hosted Langfuse v4.59.0 அல்லது அதற்குப் பிந்தைய பதிப்பும் தேவை, இவற்றை மேலே குறிப்பிடப்பட்ட pinned server பூர்த்தி செய்கிறது.
pip install langfuse opentelemetry-instrumentation-anthropic anthropicimport 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-ஐப் பதிவு செய்து, ஏற்கனவே active-ல் இருக்கும் observation-க்குக் கீழே அதை nest செய்கிறது. AnthropicInstrumentor என்பது Anthropic client-க்கான OpenTelemetry instrumentation ஆகும், இது ஒவ்வொரு messages.create அழைப்பையும் model பெயர், token பயன்பாடு மற்றும் latency ஆகியவற்றுடன் கூடிய generation-ஆக மாற்றுகிறது, அழைப்பு இடத்தில் எந்த மாற்றமும் இன்றி இது நிகழ்கிறது.
இரண்டு அழைப்புகள் உங்களுக்காகச் சரிபார்ப்பைச் செய்கின்றன. langfuse.auth_check() தவறான keys அல்லது தவறான base URL இருந்தால் False-ஐத் தரும், இது dashboard ஏன் காலியாக உள்ளது என்று யோசிப்பதை விட வேகமானது. langfuse.flush() வரிசையில் உள்ள spans அனுப்பப்படும் வரை காத்திருக்கும் (block), குறுகிய காலம் இயங்கும் processes-க்கு இது அவசியம், ஏனெனில் SDK பின்னணியில் batch செய்கிறது மற்றும் உடனடியாக வெளியேறும் script தான் அனுப்பப்படாத batch-ஐயும் சேர்த்து அழித்துவிடும். ஒரு script-க்கு பதிலாக ஒரு முழு குழுவும் traces-ஐ அனுப்புகிறது என்றால், ஒவ்வொருவரின் shell-லும் அமைப்பதற்குப் பதிலாக, அனைவரும் பயன்படுத்தும் gateway-ல் அந்த மூன்று variables-ஐயும் ஒருமுறை அமைக்கவும், இதுவே a self-hosted OneCLI harness மூலம் ஒவ்வொரு சக ஊழியரின் runs-ஐயும் instrument செய்து, keys-ஐ ஒரே இடத்தில் பாதுகாப்பாக வைத்திருக்க உதவும் வழியாகும்.
ClickHouse ஏன் தொடர்ந்து வளர்ந்து கொண்டே இருக்கிறது?
Traces என்பது பெரும்பாலானோர் தாங்களாகவே ஹோஸ்ட் செய்யும் தரவுகளில் மிக வேகமாக வளரும் ஒன்றாகும். ஒவ்வொரு agent இயங்கும்போதும் ஒரு வரி (row) எழுதப்படுகிறது; உள்ளீடுகள் மற்றும் வெளியீடுகள் முழுமையாகச் சேமிக்கப்படுகின்றன. எனவே, நீண்ட prompts-களைக் கொண்ட ஒரு சுறுசுறுப்பான agent, அது கண்காணிக்கும் application-ஐ விட அதிக அளவிலான bytes-களை நாளொன்றுக்கு உருவாக்குகிறது. கவனிக்கப்படாமல் விட்டால், ClickHouse disk-ஐ நிரப்பிவிடும். disk முழுமையாக நிரம்பினால், ingestion வேகம் குறையாது, மாறாக முற்றிலும் நின்றுவிடும்.
இங்கு இரண்டு தனித்தனி விஷயங்கள் வளர்கின்றன, அவற்றுக்கு இரண்டு தனித்தனி தீர்வுகள் தேவை.
முதலாவது உங்களது சொந்த trace தரவு; இதற்கு retention அமைப்பே தீர்வாகும். சுய-ஹோஸ்ட் செய்யப்பட்ட instance-ல், தரவுத் தக்கவைப்பு (data retention) என்பது Enterprise Edition வசதியாகும், இதற்கு license key தேவை. அது இல்லையென்றால், Langfuse ஆனது traces, observations, scores மற்றும் media ஆகியவற்றை காலவரையின்றி வைத்திருக்கும். எனவே, அதற்கேற்ப disk அளவைத் திட்டமிட்டு, இந்தப் பிரிவின் இறுதியில் உள்ள disk எச்சரிக்கையைச் சார்ந்து செயல்படுங்கள். license இருந்தால், project உரிமையாளர்கள் மற்றும் நிர்வாகிகள் project settings-க்குச் சென்று, தரவுத் தக்கவைப்பு காலத்தை நாட்களாக அமைக்கலாம். Langfuse குறைந்தபட்சம் 3 நாட்களை அனுமதிக்கிறது. ஒரு nightly job, அந்த காலத்திற்கு முந்தைய traces, observations, scores மற்றும் media assets-களைத் தேர்ந்தெடுத்து, அவற்றை ClickHouse மற்றும் blob storage-லிருந்து நீக்கும் (saved dataset items-உடன் தொடர்புடைய media-வைத் தவிர). இந்த job-க்கு bucket-ல் DeleteObject அனுமதி தேவை; default compose கோப்பில் உள்ள MinIO root credentials-க்கு ஏற்கனவே இந்த அனுமதி உள்ளது. நீக்கம் நிரந்தரமானது, எனவே நீண்ட கால வரலாறு தேவைப்பட்டால் முதலில் blob storage export-ஐ உள்ளமைக்கவும். Langfuse-ன் சொந்த அட்டவணைகளில் (tables) நீங்களாகவே TTL clauses-களை எழுத வேண்டாம்: retention job மட்டுமே ClickHouse மற்றும் bucket-ஐ ஒருங்கிணைத்து வைத்திருக்கும்; கைமுறையாக TTL அமைத்தால் ஒரு பக்கம் மட்டுமே தரவு நீக்கப்படும்.
நீங்கள் உண்மையில் பயன்படுத்தும் கால அளவைத் தேர்வு செய்யுங்கள். செலவு மற்றும் தர மதிப்பாய்வு என்பது சில நாட்களுக்கு முந்தைய தரவுகளில் நடக்கும், மாதங்களுக்கு முந்தைய தரவுகளில் அல்ல. ஒரு சிறிய குழுவிற்கு 30 நாட்கள் என்பது தொடங்குவதற்குச் சரியான கால அளவு; ஏதேனும் சிக்கல் ஏற்படும்போது மட்டும் trace-ஐப் பார்ப்பீர்கள் என்றால் 14 நாட்கள் போதுமானது.
இரண்டாவது ClickHouse-ன் சொந்த system log அட்டவணைகள். இது பலரை ஆச்சரியப்படுத்துகிறது, ஏனெனில் retention அமைக்கப்பட்ட பிறகும் disk வளர்ந்து கொண்டே இருக்கும். ClickHouse தனது சொந்த நோயறிதலுக்காக (diagnostics) trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log மற்றும் latency_log ஆகியவற்றை எழுதுகிறது. இவை எந்த TTL-உம் இன்றி வருகின்றன, மேலும் Langfuse இவற்றை ஒருபோதும் வாசிப்பதில்லை. முதலில் 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 அட்டவணைகள் பட்டியலில் முதலிடத்தில் இருந்தால், config overlay மூலம் அவற்றை அணைக்கவும். ஏனெனில் ClickHouse தொடங்கும் போது /etc/clickhouse-server/config.d/-ல் உள்ள ஒவ்வொரு கோப்பையும் அதன் முதன்மை config-உடன் இணைக்கும் (merges).
<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இது புதிய பதிவுகளைத் தடுக்கும். ஏற்கனவே disk-ல் உள்ள வரிகள் அங்கேயே இருக்கும், எனவே DROP TABLE IF EXISTS system.trace_log மூலம் இடத்தைச் சரிசெய்யவும் (ஒவ்வொரு நீக்கப்பட்ட அட்டவணைக்கும் இதையே செய்யவும்). நோயறிதல் தரவுகள் தேவைப்பட்டால், remove="1"-க்கு பதிலாக ஒவ்வொரு அட்டவணைக்கும் தீவிரமான TTL-ஐ அமைப்பதே மாற்று வழி; இது Langfuse scaling ஆவணங்களில் விளக்கப்பட்டுள்ளது. அந்த TTL directives ஒரு system அட்டவணை உருவாக்கப்படும்போது மட்டுமே பொருந்தும், எனவே ஏற்கனவே உள்ள நிறுவலில் அந்த அட்டவணைகளை மாற்றியமைக்க அதே ஆவணங்களைப் பின்பற்றவும்.
மேலும் ஒரு அட்டவணை பற்றித் தெரிந்துகொள்வது அவசியம். blob_storage_file_log உங்கள் bucket-ல் பதிவேற்றப்பட்ட event கோப்புகளைக் கண்காணிக்கிறது. நீங்கள் bucket-ல் lifecycle policy-ஐ அமைத்திருந்தால், இந்த அட்டவணைக்கும் அதே TTL-ஐ வழங்கவும், அப்போதுதான் இரண்டும் முரண்படாமல் இருக்கும்.
ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;data disk-ல் ஒரு எளிய df -h எச்சரிக்கையையும் (alert) அமைக்கவும். Traces சீராக வளர்வதில்லை. நீங்கள் ஒரு புதிய agent-ஐ வெளியிடும் நாளில் அவை வேகமாக வளரும்; அந்த நேரத்தில் ingestion தோல்வியடைவது முதல் அறிகுறியாக இருக்கக்கூடாது.
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 செய்யப்படும், ஆனால் இணைப்புகள் (attachments) அனைத்தும் காணாமல் போய்விடும்.
Postgres என்பது ஒரு சாதாரண pg_dump ஆகும், இதுவே Docker install-க்கான Langfuse பேக்கப் ஆவணங்களில் பயன்படுத்தப்படுகிறது.
docker compose exec -T postgres pg_dump -U postgres postgres \
| gzip > langfuse-pg-$(date +%F).sql.gzClickHouse-க்கு கூடுதல் கவனம் தேவை, ஏனெனில் merges இயங்கிக்கொண்டிருக்கும்போது நகலெடுக்கப்படும் நேரடி தரவு அடைவு (live data directory) ஒரு சீரான பேக்கப் ஆக இருக்காது. ஒரே 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 clickhouseYAML-ல் எழுதப்பட்ட பெயரைப் பயன்படுத்தாமல், docker volume ls காட்டும் volume பெயரைப் பயன்படுத்தவும். கோப்பில் langfuse_clickhouse_data என்று குறிப்பிடப்பட்டிருக்கும், Compose அதை project பெயருடன் முன்னொட்டாகச் சேர்க்கும். எனவே langfuse என்று பெயரிடப்பட்ட directory-ல் clone செய்தால், அது langfuse_langfuse_clickhouse_data என்று உருவாகும். இதைத் தவறாகக் குறிப்பிட்டால், docker run எந்த எச்சரிக்கையும் இன்றி புதிய காலி volume-ஐ உருவாக்கிவிடும், உங்கள் archive-ல் எதுவும் இருக்காது.
Langfuse ஒவ்வொரு ingestion கோரிக்கையின் போதும் raw event தரவை bucket-ல் பதிவேற்றுகிறது மற்றும் தோல்வியுற்ற ingestion பணிகளை மீண்டும் முயற்சிக்க அதை மீண்டும் படிக்கிறது. எனவே, ClickHouse-ஐ சிறிது நேரம் நிறுத்துவது, பெரும்பாலும் worker மீண்டும் முயற்சிக்கும் என்று பொருள்படும். இதை குறைந்த போக்குவரத்து உள்ள நேரத்தில் செய்யவும், விரைவாக முடிக்கவும். அதிக பயன்பாடுள்ள instance-களுக்கு, ClickHouse-ன் சொந்த BACKUP DATABASE default TO S3(...) கட்டளை server-ஐ நிறுத்தாமலேயே சீரான பேக்கப்-ஐ உருவாக்கும். MinIO மூன்றாவது பகுதி, இதை mc mirror அல்லது MinIO replication மூலம் off-box bucket-க்கு நகர்த்துவது பாதுகாப்பானது. நீங்கள் எதை உருவாக்கினாலும், அதை server-லிருந்து வெளியே எடுத்துவிடவும்; இதற்காகத்தான் encrypted restic backups on a VPS பயன்படுத்தப்படுகிறது.
Redis வரிசை (queue) மற்றும் cache-ஐ வைத்திருக்கிறது. இதை இழந்தால், raw event கோப்புகள் bucket-ல் இருந்தாலும், வரிசையில் உள்ள பணிகள் நீக்கப்படும்.
நிலைத்தன்மை (consistency) குறித்த எச்சரிக்கை உண்மையானது மற்றும் அதைத் தெளிவாகக் கூறுவது அவசியம். Postgres மற்றும் ClickHouse வெவ்வேறு நேரங்களில் dump செய்யப்படுவதால், restore செய்யும்போது ஒரு project வரிசையில் traces இல்லாமல் போகலாம் அல்லது ஏற்கனவே இல்லாத ஒரு project-க்குச் சொந்தமான traces இருக்கலாம். Langfuse இதைச் சமாளிக்கும், இருப்பினும் இரண்டு dump-களையும் நெருக்கமான நேரத்திலும், குறைந்த போக்குவரத்து உள்ள காலத்திலும் எடுக்கவும். event bucket தான் உண்மையான பாதுகாப்பு வலை, ஏனெனில் Langfuse ஒவ்வொரு ingestion கோரிக்கையின் போதும் raw event தரவை அங்கு பதிவேற்றுகிறது.
குறைந்தது ஒரு முறையாவது ஒரு scratch stack-ல் restore செய்து பார்க்கவும். அப்போதுதான், ஒரு பாதிப்பின் போது (outage) அல்லாமல், இப்போதே தவறான volume பெயரை உங்களால் கண்டறிய முடியும்.
முதலில் கவனிக்க வேண்டியவை
முதல் வாரத்தில் நான்கு விஷயங்களுக்கு முன்னுரிமை அளிக்க வேண்டும்.
- Trace ஒன்றுக்கான செலவு (Cost per trace). Langfuse, model பெயர் மற்றும் token பயன்பாட்டைக் கொண்டு செலவைக் கணக்கிடுகிறது. எனவே, traces-ஐ செலவின் அடிப்படையில் வரிசைப்படுத்தி, அதிக செலவாகும் trace-ஐ முழுமையாக ஆய்வு செய்யவும். பெரும்பாலும், prompt-ன் அளவு அதிகரித்திருப்பதே இதற்குக் காரணமாக இருக்கும்: முழு ஆவணத்தையும் context-ல் சேர்த்திருப்பது அல்லது உரையாடல் வரலாற்றைச் சுருக்காமல் வைத்திருப்பது போன்றவை. இதைக் கண்டறிந்தவுடன், AI agent-ன் செலவைக் கட்டுப்படுத்துவது என்பது யூகமாக இல்லாமல், ஒரு பொறியியல் பணியாக மாறிவிடும்.
- Input மற்றும் output வாரியான token பயன்பாடு. Input tokens எண்ணிக்கையில் அதிகம் மற்றும் விலை குறைவு; output tokens எண்ணிக்கையில் குறைவு மற்றும் விலை அதிகம்; cached input இன்னும் விலை குறைவானது. இதே கணக்கீடு Claude Code token பயன்பாடு எவ்வாறு கணக்கிடப்படுகிறது என்பதில் விளக்கப்பட்டுள்ளது, இது நீங்கள் உருவாக்கும் எந்தவொரு agent-க்கும் பொருந்தும்.
- Latency percentiles. Median மதிப்பைப் பார்ப்பது சிக்கலை மறைத்துவிடும். p95 மற்றும் p99 அளவீடுகளில்தான் timeouts நிகழ்கின்றன. ஒரு agent loop-க்குள், p95 அளவில் மெதுவாகச் செயல்படும் tool call, அந்த loop-ன் சுற்றுகளின் எண்ணிக்கையைப் பொறுத்து பலமடங்கு தாமதத்தை ஏற்படுத்தும்.
- தோல்வியடைந்த tool calls. Observations-ஐ
ERRORநிலையின் அடிப்படையில் வடிகட்டவும். 5% தோல்வியடையும் ஒரு tool, ஒட்டுமொத்த வெற்றி விகிதத்தில் (aggregate success rate) தெரியாது. ஆனால், traces-ல் தெளிவாகத் தெரியும்; அங்கு model மீண்டும் முயற்சிப்பதையும், அதைச் சமாளிக்க tokens-ஐ வீணாக்குவதையும் நீங்கள் கவனிக்கலாம்.
Retention window-ஐ அமைத்து, ஒவ்வொரு வாரமும் deployment செய்யும் அதே நாளில் நீங்கள் சரிபார்க்க வேண்டிய dashboard-ஐத் தேர்வு செய்யவும். யாரும் பார்க்காத ஒரு observability tool என்பது, disk-ஐ நிரப்பும் ஒரு database மட்டுமே.
FAQ
self-hosted Langfuse-க்கு எவ்வளவு memory தேவை?
4 CPU cores மற்றும் 16 GiB memory-ஐ திட்டமிடுங்கள். இதுவே ஒரு single virtual machine-ல் Langfuse Docker Compose வழிகாட்டி பரிந்துரைக்கும் அளவாகும்; இதனுடன் சுமார் 100 GiB சேமிப்பகமும் தேவைப்படும். வெளியிடப்பட்ட குறைந்தபட்ச தேவைகளின்படி, ClickHouse-க்கு 8 GiB-ம், web மற்றும் worker containers ஒவ்வொன்றிற்கும் 4 GiB-ம் தேவை. அதே பக்கத்தில் Postgres-க்கு 4 GiB, Redis-க்கு 1.5 GiB மற்றும் MinIO-க்கு 4 GiB எனப் பட்டியலிடப்பட்டுள்ளது. இவை அனைத்தையும் கூட்டினால் 25.5 GiB வரும், இது Compose பரிந்துரைக்கும் 16 GiB-ஐ விட அதிகம்.
data retention அமைத்த பிறகும் ஏன் எனது ClickHouse disk நிரம்புகிறது?
Retention அமைப்பு Langfuse-ன் சொந்தத் தரவுகளை மட்டுமே உள்ளடக்கும். ClickHouse தனித்தனியாக அதன் diagnostic tables-ஐ trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log மற்றும் latency_log என எழுதுகிறது; அவற்றுக்கு TTL கிடையாது. எந்த table அதிக இடத்தை எடுத்துக்கொள்கிறது என்பதை அறிய system.parts query-ஐ table வாரியாக group செய்து பார்க்கவும். பின்னர், /etc/clickhouse-server/config.d/-க்குக் கீழ் உள்ள கோப்பில் ஒரு remove="1" entry மூலம் தேவையற்ற tables-ஐ முடக்கவும். ClickHouse-ஐ restart செய்து, ஏற்கனவே பயன்படுத்தப்பட்ட இடத்தை மீட்க அந்த tables-ஐ நீக்கவும் (drop).
Langfuse-ல் குறைந்தபட்ச data retention காலம் எவ்வளவு?
மூன்று நாட்கள். Retention என்பது project settings-ல் அல்லது Organization Management API மூலம் ஒவ்வொரு project-க்கும் அமைக்கப்படுகிறது. ஒரு nightly job, குறிப்பிட்ட காலத்திற்கு முந்தைய traces, observations, scores மற்றும் media assets ஆகியவற்றை ClickHouse மற்றும் blob storage இரண்டிலிருந்தும் நீக்கும். சேமிக்கப்பட்ட dataset items-உடன் தொடர்புடைய media மட்டும் இதற்கு விதிவிலக்கு. Self-hosted instance-ல் இது ஒரு Enterprise Edition வசதியாகும், இதற்கு license key தேவை. அது இல்லையெனில், தரவுகள் காலவரையின்றி சேமிக்கப்படும். நீக்கப்பட்ட தரவுகளை மீண்டும் பெற முடியாது, எனவே அந்த காலத்திற்குப் பிறகும் வரலாறு தேவைப்பட்டால், முதலில் blob storage export-ஐ configure செய்யவும்.
நான் Postgres மற்றும் ClickHouse இரண்டையும் backup எடுக்க வேண்டுமா?
ஆம், ஏனெனில் அவை வெவ்வேறு தரவுகளைக் கொண்டுள்ளன. Postgres பயனர்கள், நிறுவனங்கள், projects மற்றும் API keys-ஐச் சேமிக்கிறது; ClickHouse trace தரவுகளைச் சேமிக்கிறது. Postgres-ஐ மட்டும் restore செய்தால், உங்களால் உள்ளே நுழைய முடியும், ஆனால் உள்ளே எந்தத் தரவும் இருக்காது. MinIO bucket-ஐயும் backup எடுக்கவும், ஏனெனில் Langfuse-க்கு வரும் raw events-ஐ அதுவே சேமிக்கிறது; இதுவே இந்த stack-ல் உண்மையான ஆதாரத்திற்கு (source of truth) மிக நெருக்கமானதாகும்.
ஏற்கனவே உள்ள OpenTelemetry அமைப்பை self-hosted Langfuse-க்கு மாற்ற முடியுமா?
ஆம். Langfuse v4 மற்றும் அதன் தற்போதைய SDK-கள் OpenTelemetry-ஐ அடிப்படையாகக் கொண்டவை. Anthropic மற்றும் OpenAI OTel instrumentations நேரடியாக அதற்கு 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() மூலம் உறுதிப்படுத்தவும்.