Langfuse-ஐ உங்கள் சொந்த VPS-ல் self-host செய்வது எப்படி?

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 உண்மையில் எவ்வாறு இயங்குகிறது

Langfuse v4 என்பது ஒரே ஒரு container அல்ல. இது இரண்டு application container-கள் மற்றும் நான்கு storage service-களைக் கொண்டது. ஒரு VPS-ல் இவை ஆறும் உங்கள் server-லேயே இயங்கும்.

• langfuse-web web 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 உங்கள் server-லேயே S3 compatible object storage-ஐ வழங்குகிறது. இது உள்ளே வரும் அனைத்து raw events மற்றும் நீங்கள் இணைக்கும் media கோப்புகளைச் சேமிக்கிறது.

Langfuse தனது பணியைச் செய்யும் மூன்று கூறுகளுக்கான குறைந்தபட்ச வளத் தேவைகளை வெளியிடுகிறது.

[
  {
    "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 தேவை. இவை Langfuse அளவிடும் 3 கூறுகளுக்கான குறைந்தபட்ச தேவைகள்; இதனுடன் Postgres, Redis மற்றும் MinIO ஆகியவற்றிற்கும் கூடுதல் memory தேவைப்படும். இந்தத் திட்டத்தின் சொந்த Docker Compose வழிகாட்டி, 4 cores, 16 GiB memory மற்றும் சுமார் 100 GiB storage கொண்ட machine-ஐப் பரிந்துரைக்கிறது. இது வெறும் மிகைப்படுத்தல் அல்ல, கணக்கீட்டின்படி அவசியமானது.

இதை 2 GiB plan-ல் முயற்சி செய்ய வேண்டாம். ClickHouse தொடங்கும், சிறிது நேரம் தரவுகளை ஏற்கும், ஆனால் background merge-ன் போது செயலிழந்துவிடும். ஏனெனில் merge செயல்முறை அட்டவணையின் பெரிய பகுதிகளை 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 செய்யும். ஒரு developer தினமும் சில ஆயிரம் traces அனுப்பினால் 8 GiB போதுமானது. ஆனால், 16 GiB என்பதே திட்டமிட வேண்டிய அளவு.

Docker Compose மூலம் Langfuse-ஐ நிறுவுதல்

Repository-ஐ clone செய்யவும். Stack, அதன் இணைப்பு மற்றும் இயல்புநிலை 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_KEY

ENCRYPTION_KEY என்பது 64 hex characters கொண்ட 256 bits மதிப்பாக இருக்க வேண்டும், இதைத்தான் openssl rand -hex 32 வெளியிடுகிறது. இது நீங்கள் instance-ல் சேமிக்கும் LLM provider keys உள்ளிட்ட முக்கியமான தரவுகளை encrypt செய்கிறது. தரவுகள் உள்ள நிலையில் இதை மாற்றினால், அந்த rows-ஐ மீண்டும் 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 கோப்பில் வைக்காமல் env கோப்பில் வைத்திருப்பது Docker Compose env files and secrets பகுதியில் விவரிக்கப்பட்டுள்ள முறையாகும்.

தொடங்குவதற்கு முன் image tags-ஐ நிலைப்படுத்தவும் (Pin)

வழங்கப்பட்ட கோப்பு langfuse/langfuse:4 மற்றும் langfuse/langfuse-worker:4-ஐப் பயன்படுத்துகிறது. அந்த tags மாறக்கூடியவை. Langfuse தனது Postgres மற்றும் ClickHouse migrations-ஐ தொடக்கத்திலேயே தானாகவே செய்கிறது, எனவே மாதங்கள் கழித்து செய்யப்படும் ஒரு வழக்கமான docker compose pull, நீங்கள் அன்று காலை backup எடுக்காத database-ல் திட்டமிடப்படாத schema migration-ஐ ஏற்படுத்தலாம். இரண்டையும் ஒரு docker-compose.override.yml-ல் ஒரு குறிப்பிட்ட release-க்கு நிலைப்படுத்தவும்; இது Compose மூலம் இணைக்கப்படும்போது, பிற்காலத்தில் செய்யப்படும் git pull உங்கள் மாற்றங்களை பாதிக்காது.

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

ஆகஸ்ட் 2026 நிலவரப்படி, 4.3.1 என்பது தற்போதைய 4.3 release ஆகும் (4.4.0 ஏற்கனவே வெளியாகிவிட்டது). திட்டத்தின் GitHub releases பக்கத்தைச் சரிபார்த்து, நீங்கள் நிறுவும் நாளில் எது தற்போதைய பதிப்போ அதை நிலைப்படுத்தவும், பிறகு அந்த எண்ணை கவனமாக மாற்றவும். வழங்கப்பட்ட கோப்பில் உள்ள storage images ஏற்கனவே majors, postgres:17, clickhouse-server:25.12 மற்றும் redis:7 என நிலைப்படுத்தப்பட்டுள்ளன, அவற்றுக்கும் அதே முறையைப் பின்பற்ற வேண்டும்.

அமைப்பைத் தொடங்கவும்.

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

முதல் boot-ன் போது migrations நடக்கும், எனவே பதிலளிக்க ஒன்று அல்லது இரண்டு நிமிடங்கள் அனுமதிக்கவும். docker compose ps ஆறு services-ஐ running நிலையில் காட்ட வேண்டும். worker மீண்டும் மீண்டும் restart ஆனால், அதன் log-ல் காரணம் இருக்கும்: CLICKHOUSE_MIGRATION_URL, HTTP port 8123-க்கு பதிலாக port 9000-ல் உள்ள ClickHouse native protocol-ஐப் பயன்படுத்துகிறது; அதை 8123-க்கு மாற்றினால் web container சரியாகத் தெரிந்தாலும், அங்கே பிழை ஏற்படும்.

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 பிழையைத் தரும். migrations முடிந்ததும் மற்றும் container traffic-ஐ ஏற்கும் நிலையில் இருக்கும்போது /api/public/ready 200 என்ற குறியீட்டைத் தரும். இவை இரண்டும் சாதாரண HTTP checks என்பதால், an Uptime Kuma status page மூலம் இவற்றைத் தொடர்ந்து கண்காணித்து, உங்கள் agents-க்குத் தெரியும் முன்பே stack செயலிழந்ததை நீங்கள் அறியலாம்.

TLS-ஐ முன்னால் வைத்து கூடுதல் போர்ட்களை மூடுதல்

வழங்கப்பட்ட compose கோப்பு, web container-க்காக 3000:3000-ஐயும், MinIO-க்காக 9090:9000-ஐயும் வெளியிடுகிறது (publish). இவை இரண்டுமே அனைத்து interface-களிலும் bind ஆகின்றன. ஒரு public IP-ல், port 3000-ஐ ஸ்கேன் செய்யும் எவரும் உங்கள் sign up பக்கத்தை அடைய முடியும்; port 9090-ஐ ஸ்கேன் செய்யும் எவரும் உங்கள் raw prompts-களைக் கொண்ட bucket-ஐ அணுக முடியும்.

Firewall விதி மட்டும் இவற்றை மூடிவிடாது. Docker தனது சொந்த DNAT விதிகளை nat table-ல் எழுதும். இவை ufw-ன் filter விதிகள் பாக்கெட்டைப் பார்ப்பதற்கு முன்பே செயல்படுத்தப்படும். எனவே, ufw deny 3000 வெளியிட்ட போர்ட்டைத் திறந்தே வைத்திருக்கும். இது பலரை பாதிக்கும் ஒரு பொதுவான சிக்கல் என்பதால், இதற்கென தனி வழிகாட்டி உள்ளது: Docker published ports ஏன் ufw-ஐத் தவிர்க்கின்றன. உங்கள் override கோப்பில் loopback-ல் bind செய்யுமாறு மாற்றவும்.

services:
  langfuse-web:
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports:
      - "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-ஐப் பயன்படுத்துவது வழக்கமான முறை. இதற்கான routing labels ஒரே Traefik reverse proxy-க்கு பின்னால் பல செயலிகளை இயக்குதல் என்பதில் விவரிக்கப்பட்டுள்ளன. Langfuse மட்டுமே அந்த server-ல் இருந்தால், Caddy-ஐ இரண்டு வரிகளில் இதற்காகப் பயன்படுத்தலாம். curl -sI https://langfuse.example.com/api/public/ready மூலம் சரிபார்க்கவும், பின்னர் மற்றொரு கணினியிலிருந்து curl http://YOUR_IP:3000 இப்போது time out ஆகிறதா என்பதை உறுதிப்படுத்தவும்.

MinIO குறித்து ஒரு எச்சரிக்கை. Langfuse இணைக்கப்பட்ட media-க்களை, அந்த S3 endpoint-ஐக் குறிக்கும் presigned URL-கள் மூலம் உங்கள் உலாவிக்கு வழங்குகிறது. எனவே, படங்கள் அல்லது ஆடியோ கொண்ட multi-modal traces-களைப் பயன்படுத்தினால், loopback-only MinIO-வில் அந்த இணைப்புகள் (attachments) ஏற்றப்படாது. அதை proxy செய்வதற்கு முன் blob storage configuration பக்கத்தைப் படிக்கவும். ஏனெனில், presigned URL-ல் எழுதப்படும் endpoint நீங்கள் வெளியிடும் முகவரியுடன் ஒத்துப்போக வேண்டும். Plain text traces-கள் இதனால் பாதிக்கப்படாது.

முதல் முறை நுழையும்போது உங்கள் கணக்கை உருவாக்கவும், பின்னர் அந்த instance-ஐ உங்கள் கட்டுப்பாட்டில் வைத்திருக்கவும். LANGFUSE_ALLOWED_ORGANIZATION_CREATORS-ஐ உங்கள் மின்னஞ்சல் முகவரிக்கு அமைக்கவும். அப்போதுதான், அந்தப் பக்கத்தை அடையும் அந்நியர்கள் உங்கள் server-ல் புதிய அமைப்பை (organisation) உருவாக்க முடியாது. நீங்கள் ஏற்கனவே Authentik-ஐ உங்கள் identity provider-ஆக இயக்கி வருகிறீர்கள் என்றால், Langfuse ஒரு standard OIDC இணைப்பை ஏற்கும். இதனால், இந்த server-க்கு மட்டுமே தெரிந்த 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-ஐக் குறிக்கும்.

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-ஐப் பதிவு செய்கிறது; மேலும் ஏற்கனவே செயல்பாட்டில் உள்ள எந்தவொரு observation-க்குள்ளும் அதை nest செய்கிறது. AnthropicInstrumentor என்பது Anthropic client-க்கான OpenTelemetry instrumentation ஆகும். இது ஒவ்வொரு messages.create அழைப்பையும் model பெயர், token பயன்பாடு மற்றும் latency ஆகியவற்றைக் கொண்ட ஒரு generation-ஆக மாற்றுகிறது; அழைப்பு நிகழும் இடத்தில் (call site) எந்த மாற்றமும் தேவையில்லை.

இரண்டு அழைப்புகள் உங்களுக்காகச் சரிபார்ப்பைச் செய்கின்றன. langfuse.auth_check() தவறான keys அல்லது தவறான base URL இருந்தால் False-ஐத் திருப்பித் தரும், இது dashboard ஏன் காலியாக உள்ளது என்று யோசிப்பதை விட வேகமானது. langfuse.flush() வரிசைப்படுத்தப்பட்ட (queued) spans அனுப்பப்படும் வரை காத்திருக்கும். குறுகிய காலம் இயங்கும் process-களுக்கு இது அவசியம், ஏனெனில் SDK பின்னணியில் batch செய்கிறது; உடனடியாக வெளியேறும் ஒரு script, அனுப்பப்படாத batch-ஐயும் தன்னுடன் எடுத்துச் சென்றுவிடும்.

ClickHouse ஏன் தொடர்ந்து வளர்ந்துகொண்டே இருக்கிறது?

Traces என்பது பெரும்பாலானோர் தாங்களாகவே ஹோஸ்ட் செய்யும் தரவுகளில் மிக வேகமாக வளரும் ஒன்றாகும். ஒவ்வொரு agent இயக்கமும் ஒரு படிக்கு ஒரு வரிசையை எழுதுகிறது, மேலும் உள்ளீடுகள் மற்றும் வெளியீடுகள் முழுமையாகச் சேமிக்கப்படுகின்றன. எனவே, நீண்ட prompts கொண்ட ஒரு சுறுசுறுப்பான agent, அது கண்காணிக்கும் application-ஐ விட அதிக bytes-களை ஒரு நாளில் உருவாக்குகிறது. கவனிக்கப்படாமல் விட்டால், ClickHouse disk-ஐ நிரப்பிவிடும்; disk முழுமையாக நிரம்பினால், ingestion வேகம் குறையாது, மாறாக முற்றிலும் நின்றுவிடும்.

இங்கு இரண்டு தனித்தனி விஷயங்கள் வளர்கின்றன, அவற்றுக்கு இரண்டு தனித்தனி தீர்வுகள் தேவை.

முதலாவது உங்கள் சொந்த trace தரவு, இதற்கு retention அமைப்புதான் தீர்வு. Web interface-ல் project settings-ஐத் திறந்து, தரவு வைத்திருக்கும் கால அளவை (நாட்களில்) அமைக்கவும். Langfuse குறைந்தபட்சம் 3 நாட்களை அனுமதிக்கிறது. ஒரு nightly job அந்த காலத்திற்கு முந்தைய traces, observations, scores மற்றும் media assets-களைத் தேர்ந்தெடுத்து, அவற்றை ClickHouse மற்றும் blob storage-லிருந்து நீக்கும். இந்த job-க்கு bucket-ல் DeleteObject அனுமதி தேவை, இது default compose file-ல் உள்ள MinIO root credentials-ல் ஏற்கனவே உள்ளது. நீக்கம் நிரந்தரமானது, எனவே நீண்ட கால வரலாறு தேவைப்பட்டால் முதலில் blob storage export-ஐ configure செய்யவும். Langfuse-ன் சொந்த அட்டவணைகளில் நீங்களாகவே 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 ஆகியவற்றை எழுதுகிறது. இவை எந்த 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-ன் மேல் இணைக்கிறது (merge).

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_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 மற்றும் நீங்கள் நீக்கிய ஒவ்வொரு அட்டவணைக்கும் அதே கட்டளையைப் பயன்படுத்தி இடத்தை மீட்டெடுக்கவும். ஒருவேளை நீங்கள் diagnostics-ஐ வைத்திருக்க விரும்பினால், remove="1"-க்கு பதிலாக ஒவ்வொரு அட்டவணைக்கும் தீவிரமான TTL-ஐ அமைப்பதே மாற்று வழியாகும், இது Langfuse scaling ஆவணங்களில் விளக்கப்பட்டுள்ளது.

இன்னொரு அட்டவணை குறித்தும் தெரிந்துகொள்வது அவசியம். 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-ஐ மட்டும் மீட்டெடுத்தால், வரலாறு இல்லாத ஒரு செயல்பாட்டு உள்நுழைவு (login) மட்டுமே கிடைக்கும். ClickHouse-ஐ மட்டும் மீட்டெடுத்தால், வரலாறு இருக்கும், ஆனால் யாரும் உள்நுழைந்து பார்க்க முடியாது.

Postgres ஒரு எளிய pg_dump ஆகும், இதுவே Langfuse பேக்கப் ஆவணங்கள் பரிந்துரைக்கும் முறையாகும்.

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

ClickHouse-க்கு கூடுதல் கவனம் தேவை, ஏனெனில் merges இயங்கிக்கொண்டிருக்கும்போது நகலெடுக்கப்படும் நேரடி தரவு அடைவு (live data directory) ஒரு சீரான பேக்கப் ஆக இருக்காது. ஒரே சர்வரில் இதற்கான எளிய வழி, 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 பெயரைப் பயன்படுத்தவும், YAML-ல் எழுதப்பட்ட பெயரைப் பயன்படுத்த வேண்டாம். கோப்பு langfuse_clickhouse_data என்று குறிப்பிடுகிறது, Compose அதை project பெயருடன் முன்னொட்டாகச் சேர்க்கிறது, எனவே langfuse என்று பெயரிடப்பட்ட கோப்பகத்தில் உள்ள clone, langfuse_langfuse_clickhouse_data-ஐ உருவாக்குகிறது. இதைத் தவறாகச் செய்தால், docker run எந்த எச்சரிக்கையும் இன்றி புதிய காலி volume-ஐ உருவாக்கிவிடும், உங்கள் archive-ல் எதுவும் இருக்காது.

Web container ஒவ்வொரு நிகழ்வையும் worker செயலாக்குவதற்கு முன்பே bucket-ல் எழுதிவிடுகிறது, எனவே ClickHouse-ஐ சிறிது நேரம் நிறுத்துவது என்பது, worker பிறகு மீண்டும் முயற்சிக்கும் என்று அர்த்தம். இதை குறைந்த போக்குவரத்து உள்ள நேரத்தில் செய்யவும், விரைவாக முடிக்கவும். அதிக பயன்பாடுள்ள instance-களுக்கு, ClickHouse-ன் சொந்த BACKUP DATABASE default TO S3(...) கூற்று சர்வரை நிறுத்தாமலேயே சீரான பேக்கப்-ஐ உருவாக்குகிறது. MinIO மூன்றாவது பகுதி, இதை mc mirror அல்லது MinIO replication மூலம் சர்வர்-க்கு வெளியே உள்ள bucket-க்கு நகலெடுப்பது பாதுகாப்பானது. நீங்கள் எதை உருவாக்கினாலும், அதை சர்வரிலிருந்து வெளியே எடுத்துவிடவும், இதற்காகவே VPS-ல் குறியாக்கம் செய்யப்பட்ட restic பேக்கப்-கள் பயன்படுகின்றன.

Redis-க்கு பேக்கப் தேவையில்லை. இது queue மற்றும் cache-ஐ வைத்திருக்கிறது, எனவே இதை இழந்தால் தற்போது செயல்பாட்டில் உள்ள நிகழ்வுகள் மட்டுமே இழக்கப்படும், பழைய தரவுகள் பாதிக்கப்படாது.

தரவு நிலைத்தன்மை (consistency) குறித்த எச்சரிக்கை உண்மையானது மற்றும் அதைத் தெளிவாகக் கூறுவது அவசியம். Postgres மற்றும் ClickHouse வெவ்வேறு நேரங்களில் dump செய்யப்படுவதால், மீட்டெடுக்கும்போது traces இல்லாத project வரிசை அல்லது ஏற்கனவே இல்லாத project-க்கு சொந்தமான traces இருக்கலாம். Langfuse இதைச் சமாளிக்கும், இருப்பினும் இரண்டு dump-களையும் குறைந்த போக்குவரத்து உள்ள நேரத்தில் அருகருகே எடுக்கவும். Event bucket தான் உண்மையான பாதுகாப்பு வலை, ஏனெனில் Langfuse ஒவ்வொரு நிகழ்வையும் செயலாக்குவதற்கு முன்பே அங்கு சேமித்துவிடுகிறது.

குறைந்தது ஒருமுறையாவது ஒரு scratch stack-ல் மீட்டெடுத்துப் பார்க்கவும். அப்போதுதான், ஒரு செயலிழப்பின் போது அல்லாமல், இப்போதே தவறான 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 நினைவகத்தை திட்டமிடுங்கள். இதுவே ஒரு single virtual machine-ல் Langfuse Docker Compose வழிகாட்டி பரிந்துரைக்கும் அளவாகும், மேலும் சுமார் 100 GiB சேமிப்பகமும் தேவைப்படும். வெளியிடப்பட்ட குறைந்தபட்ச தேவைகள் ClickHouse-க்கு 8 GiB, web மற்றும் worker containers-க்கு தலா 4 GiB ஆகும். இவை தவிர Postgres, Redis மற்றும் MinIO ஆகியவற்றிற்கும் கூடுதல் நினைவகம் தேவை. ஒரு டெவலப்பரின் பயன்பாட்டிற்கு 8 GiB போதுமானது. 2 GiB போதாது: பின்னணி இணைப்புகளின்போது (background merges) ClickHouse-ஐ kernel நிறுத்திவிடும், அப்போது dmesg என்பது Out of memory: Killed process-ஐக் காட்டும்.

தரவுத் தக்கவைப்பு (data retention) அமைத்த பிறகும் ஏன் எனது ClickHouse வட்டு நிரம்புகிறது?

இந்த retention அமைப்பு Langfuse-ன் சொந்த தரவுகளுக்கு மட்டுமே பொருந்தும். ClickHouse தனித்தனியாக trace_log, text_log, opentelemetry_span_log, metric_log மற்றும் asynchronous_metric_log ஆகிய diagnostic tables-ல் தரவுகளை எழுதுகிறது, அவற்றுக்கு TTL கிடையாது. எந்த அட்டவணை அதிக இடத்தை எடுத்துக்கொள்கிறது என்பதை அறிய system.parts வினவலை (query) அட்டவணை வாரியாகப் பார்க்கவும். பின்னர் /etc/clickhouse-server/config.d/-க்கு கீழ் உள்ள கோப்பில் remove="1" உள்ளீட்டைச் சேர்த்து தேவையற்ற அட்டவணைகளை முடக்கவும். ClickHouse-ஐ மறுதொடக்கம் செய்து, ஏற்கனவே பயன்படுத்தப்பட்ட இடத்தை மீட்டெடுக்க அந்த அட்டவணைகளை நீக்கவும் (drop).

Langfuse-ல் குறைந்தபட்ச தரவுத் தக்கவைப்பு காலம் எவ்வளவு?

மூன்று நாட்கள். ஒவ்வொரு திட்டத்திற்கும் (project) அதன் அமைப்புகளில் அல்லது projects API மூலம் தக்கவைப்பு காலம் அமைக்கப்படுகிறது. ஒரு nightly job, அந்த காலத்திற்கு முந்தைய traces, observations, scores மற்றும் media assets ஆகியவற்றை ClickHouse மற்றும் blob storage இரண்டிலிருந்தும் நீக்கும். நீக்கப்பட்ட தரவை மீண்டும் பெற முடியாது, எனவே அந்த காலத்திற்குப் பிறகும் வரலாறு தேவைப்பட்டால், முதலில் blob storage export-ஐ உள்ளமைக்கவும்.

நான் Postgres மற்றும் ClickHouse இரண்டையும் காப்புப்பிரதி (backup) எடுக்க வேண்டுமா?

ஆம், ஏனெனில் அவை வெவ்வேறு தரவுகளைக் கொண்டுள்ளன. Postgres பயனர்கள், நிறுவனங்கள், திட்டங்கள் மற்றும் API keys ஆகியவற்றைச் சேமிக்கிறது; ClickHouse trace தரவுகளைச் சேமிக்கிறது. Postgres-ஐ மட்டும் மீட்டெடுத்தால், உங்களால் உள்நுழைய முடியும், ஆனால் உள்ளே எந்தத் தரவும் இருக்காது. MinIO bucket-ஐயும் காப்புப்பிரதி எடுக்கவும், ஏனெனில் Langfuse-க்கு வரும் raw events அங்குதான் சேமிக்கப்படுகின்றன. இதுவே இந்த stack-ல் உண்மையான தரவு ஆதாரத்திற்கு (source of truth) மிக நெருக்கமானதாகும்.

ஏற்கனவே உள்ள OpenTelemetry அமைப்பை சுய-வழங்கப்பட்ட Langfuse-க்கு மாற்ற முடியுமா?

ஆம். Langfuse v4 மற்றும் அதன் v4 SDK-கள் OpenTelemetry-ல் கட்டமைக்கப்பட்டுள்ளன. Anthropic மற்றும் OpenAI OTel instrumentations நேரடியாக அதற்கு ஏற்றுமதி செய்கின்றன. Python-ல், pip install langfuse opentelemetry-instrumentation-anthropic-ஐ இயக்கவும், தொடக்கத்தின்போது ஒருமுறை AnthropicInstrumentor().instrument()-ஐ அழைக்கவும், மேலும் LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY மற்றும் LANGFUSE_BASE_URL ஆகியவற்றை உங்கள் சொந்த host-க்கு அமைக்கவும். காணாமல் போன dashboard-ஐத் தேடும் முன் langfuse.auth_check() மூலம் உறுதிப்படுத்தவும்.