AI agent కోసం Langfuse ను self-host చేయడం ఎలా

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 సమస్యను లేదా quality సమస్యను పరిష్కరించలేరు. Provider invoice ప్రకారం మంగళవారం ఖర్చు సోమవారం ఖర్చుకంటే నాలుగు రెట్లు అయింది. Trace మాత్రం దానికి కారణమైన agent run ఏదో, ఏ prompt 40,000 tokens కు పెరిగిందో, చివరకు విఫలమయ్యే ముందు ఏ retry loop తొమ్మిది సార్లు నడిచిందో చూపిస్తుంది. Invoice సంఖ్యను ఇస్తుంది. Trace ఆ సంఖ్యను ఉత్పత్తి చేసిన code ను చూపిస్తుంది.

ఈ guide అంతటా మూడు పదాలు ఉపయోగిస్తారు. Trace అనేది మీ agent యొక్క ప్రారంభం నుంచి ముగింపు వరకు జరిగిన ఒక run. Observation అనేది ఆ run లోని ఒక దశ: సాధారణ code కోసం ఒక span, model కు చేసిన call కోసం ఒక generation. Score అనేది trace కు జతచేయబడిన సంఖ్య; ఇది మానవ సమీక్ష లేదా automated evaluator నుంచి రావచ్చు. Langfuse distributed tracing కోసం vendor neutral standard అయిన OpenTelemetry (OTel) ను ఉపయోగిస్తుంది. అందువల్ల మీ వద్ద ఇప్పటికే ఉన్న instrumentation ను దాని వైపు పంపవచ్చు.

Self-hosting Langfuseలో వాస్తవంగా నడిచే భాగాలు

Langfuse v4 ఒకే container కాదు. ఇందులో రెండు application containers మరియు నాలుగు storage services ఉంటాయి. ఒకే VPSలో ఈ ఆరు భాగాలూ మీ serverలోనే నడుస్తాయి.

• langfuse-web web interface మరియు ingestion API ను అందిస్తుంది.
• langfuse-worker queueలోని పనులను backgroundలో పూర్తి చేస్తుంది. ఇది 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 మీ serverలో S3 compatible object storage ను అందిస్తుంది. ఇది ప్రతి raw incoming event తో పాటు మీరు జతచేసే media ను కూడా నిల్వ చేస్తుంది.

పని చేసే మూడు components కోసం Langfuse కనీస 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 అవసరం. Langfuse resource sizing చేసిన 3 components కోసం ఇవి ప్రచురించిన కనీస పరిమాణాలు. దీనికి అదనంగా Postgres, Redis మరియు MinIOలకు కూడా memory అవసరం. Project యొక్క స్వంత Docker Compose guide 4 cores, 16 GiB memory మరియు సుమారు 100 GiB storage ఉన్న machine ను సిఫారసు చేస్తుంది. ఈ లెక్కతో అది సరిపోతుంది; అదనపు భద్రతా మార్జిన్‌ను ఉద్దేశపూర్వకంగా జోడించలేదు.

2 GiB planపై దీన్ని ప్రయత్నించవద్దు. ClickHouse ప్రారంభమై కొంతకాలం writes ను స్వీకరిస్తుంది. తరువాత background merge సమయంలో ఆగిపోతుంది, ఎందుకంటే merge సమయంలో tableలోని పెద్ద parts memoryలోకి load అవుతాయి. docker compose ps clickhouse containerను restartingగా report చేయడం, dmesgలో Out of memory: Killed process 1234 (clickhouse-serv) వంటి line కనిపించడం, అలాగే ప్రతి Langfuse dashboard 500ను తిరిగి ఇవ్వడం మీరు చూస్తారు. తక్కువ loadలో ClickHouse queryను తిరస్కరించి, బదులుగా DB::Exception: Memory limit (total) exceededను log చేయవచ్చు. రోజుకు కొన్ని వేల traces పంపే ఒక developer కోసం 8 GiB సరిపోతుంది. అయితే ప్రణాళిక రూపొందించేటప్పుడు 16 GiBను లక్ష్యంగా పెట్టాలి.

Docker Composeతో Langfuseను అమలు చేయండి

Repositoryని clone చేయండి. Stack, దాని wiring మరియు 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_KEY

ENCRYPTION_KEY విలువ 64 hex charactersగా రాసిన 256 bits అయి ఉండాలి. openssl rand -hex 32 సరిగ్గా ఇదే ఆకృతిని ముద్రిస్తుంది. ఇది instanceలో నిల్వ చేసే LLM provider keysతో సహా, నిల్వలో ఉన్న sensitive valuesను encrypt చేస్తుంది. Data సృష్టించిన తర్వాత దీన్ని మార్చితే, ఆ rowsను మళ్లీ decrypt చేయలేరు. అందువల్ల మొదటి boot నుంచే దీన్ని శాశ్వత విలువగా పరిగణించండి. SALT మీ Langfuse API keysను hash చేయడానికి ఉపయోగించబడుతుంది. దీన్ని మార్చితే agents ఇప్పటికే ఉపయోగిస్తున్న ప్రతి key చెల్లదు.

తర్వాత 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తో తిరస్కరిస్తుంది. ఈ లోపం worker logలో కనిపిస్తుంది, అయితే web interface మాత్రం సక్రమంగా ఉన్నట్లు కనిపిస్తుంది. Tracked compose fileలో కాకుండా env fileలో ఈ విలువలను ఉంచే విధానాన్ని Docker Compose env files మరియు secretsలో వివరించాం.

ప్రారంభించే ముందు image tagsను స్థిరపరచండి

చేర్చిన fileలో langfuse/langfuse:4 మరియు langfuse/langfuse-worker:4 ఉపయోగించబడ్డాయి. ఆ tags మారుతూ ఉంటాయి. Langfuse ప్రారంభ సమయంలో తన Postgres మరియు ClickHouse migrationsను స్వయంచాలకంగా అమలు చేస్తుంది. అందువల్ల కొన్ని నెలల తరువాత జరిగే సాధారణ docker compose pull, ఆ రోజు backup చేయని databaseపై అనుకోని schema migrationగా మారవచ్చు. రెండింటినీ ఒకే releaseకు docker-compose.override.ymlలో pin చేయండి. Compose దీన్ని చేర్చిన fileపై వర్తింపజేస్తుంది. అప్పుడు తరువాతి git pull మీ మార్పులతో విభేదించదు.

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

August 2026 నాటికి 4.3.1 ప్రస్తుత 4.3 release (తరువాత 4.4.0 విడుదలైంది). Project GitHub releases pageను పరిశీలించండి. Deploy చేసే రోజున ప్రస్తుత version ఏదైతే ఉందో దానిని pin చేయండి. తరువాత ఆ సంఖ్యను ఉద్దేశపూర్వకంగా మార్చండి. చేర్చిన fileలోని storage images ఇప్పటికే major versionsకు pin చేయబడ్డాయి: postgres:17, clickhouse-server:25.12 మరియు redis:7. వాటికీ ఇదే విధానాన్ని పాటించాలి.

దీన్ని ప్రారంభించండి.

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

మొదటి boot migrationsను అమలు చేస్తుంది. అందువల్ల ఏదైనా response వచ్చే ముందు ఒకటి లేదా రెండు నిమిషాలు వేచి ఉండండి. docker compose ps ఆరు servicesను running stateలో చూపాలి. Worker పదేపదే restart అవుతుంటే, దానికి కారణం దాని logలో ఉంటుంది: CLICKHOUSE_MIGRATION_URL ClickHouse native protocolను port 9000పై ఉపయోగిస్తుంది, HTTP port 8123పై కాదు. దాన్ని 8123కు చూపితే worker విఫలమవుతుంది, అయితే web container మాత్రం సక్రమంగా ఉన్నట్లు కనిపిస్తుంది.

ఈ host నుంచే 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 సజీవంగా ఉందని మాత్రమే నిర్ధారిస్తుంది. Service అందుబాటులో ఉండటం కొనసాగించేందుకు ఇది ఉద్దేశపూర్వకంగా databaseను తనిఖీ చేయదు; అందువల్ల Postgresలో తాత్కాలిక అంతరాయం వచ్చినా service requestsను అందిస్తుంది. Monitorకు చూపించాల్సినది failIfDatabaseUnavailable=true రూపం. Database అందుబాటులో లేకపోతే ఇది 503ను తిరిగి ఇస్తుంది. Migrations పూర్తయిన తర్వాత /api/public/ready 200ను తిరిగి ఇస్తుంది. అప్పుడు container trafficను స్వీకరిస్తుంది. రెండూ సాధారణ HTTP checks. కాబట్టి Uptime Kuma status page వాటిని monitor చేసి, మీ agents గుర్తించేలోపే stack down అయిందని తెలియజేయగలదు.

TLS ను ముందు ఉంచి అదనపు ports మూసివేయండి

ఇచ్చిన Compose file web container కోసం 3000:3000 ను, MinIO కోసం 9090:9000 ను publish చేస్తుంది. ఇవి రెండూ ప్రతి interface పై bind అవుతాయి. Public IP పై port 3000 ను scan చేసే ఎవరైనా మీ sign up page ను చేరుకుంటారు. Port 9090 ను scan చేసే ఎవరైనా మీ raw prompts ఉన్న bucket తో నేరుగా మాట్లాడగలరు.

Firewall rule ఒక్కటే వీటిని మూసివేయదు. Docker తన DNAT rules ను nat table లో స్వయంగా రాస్తుంది. ufw యొక్క filter rules packet ను చూడకముందే ఈ rules అమలవుతాయి. అందువల్ల ufw deny 3000 ఉన్నా published port తెరిచి ఉంటుంది. ఈ సమస్య చాలామందికి ఎదురవుతుంది కాబట్టి దీనిపై ప్రత్యేక guide ఉంది: Docker published ports ufw ను ఎలా bypass చేస్తాయి. మీ override file లో 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 address అయి ఉండాలి. Login flow తన callback URL ను ఈ విలువ నుంచి నిర్మిస్తుంది. HTTPS proxy వెనుక దీనిని http://localhost:3000 గా ఉంచితే, sign in round trip browser చేరుకోలేని చిరునామాకు పంపబడుతుంది.

ఇప్పుడు reverse proxy ను 127.0.0.1:3000 కు point చేసి, certificate ను దానితో నిర్వహించండి. అదే Compose project లోని Traefik సాధారణంగా ఉపయోగించే ఎంపిక. Routing labels గురించి ఒకే Traefik reverse proxy వెనుక అనేక అప్లికేషన్లను నడపడం లో వివరించారు. Langfuse మాత్రమే ఈ server పై ఉంటే, Caddy రెండు lines తో అదే పని చేస్తుంది. curl -sI https://langfuse.example.com/api/public/ready తో నిర్ధారించండి. తరువాత మరో machine నుంచి curl http://YOUR_IP:3000 ఇప్పుడు timeout అవుతోందని నిర్ధారించండి.

MinIO విషయంలో ఒక జాగ్రత్త ఉంది. Langfuse attached media ను ఆ S3 endpoint ను సూచించే presigned URLs ద్వారా మీ browser కు అందిస్తుంది. అందువల్ల images లేదా audio ఉన్న multi-modal traces ఉపయోగిస్తే, loopback-only MinIO కారణంగా ఆ attachments load కావు. MinIO ను proxy చేసే ముందు blob storage configuration page చదవండి. Presigned URL లో రాసే endpoint మీరు publish చేసే endpoint తో సరిపోవాలి. Plain text traces పై దీని ప్రభావం ఉండదు.

మొదటి సందర్శనలో మీ account సృష్టించండి. తరువాత instance పై నియంత్రణను మీ వద్దే ఉంచండి. LANGFUSE_ALLOWED_ORGANIZATION_CREATORS ను మీ స్వంత email address గా సెట్ చేయండి. అప్పుడు page ను చేరుకునే అపరిచితుడు మీ server పై organisation సృష్టించలేడు. మీరు ఇప్పటికే మీ స్వంత identity provider గా Authentik ను నడుపుతున్నట్లయితే, Langfuse standard OIDC connection ను స్వీకరిస్తుంది. అందువల్ల accounts మీ ఇతర apps తో పాటు సృష్టించబడతాయి, తొలగించబడతాయి. ఈ box కు మాత్రమే తెలిసిన password list లో అవి విడిగా ఉండవు.

మీ మొదటి trace ను పంపండి

వెబ్ ఇంటర్‌ఫేస్‌లో ఒక 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"

SDK v4లో LANGFUSE_BASE_URL variable name. ఇది March 2026లో విడుదలైంది. పాత code మరియు పాత guides లో LANGFUSE_HOST ను ఉపయోగిస్తారు. మీ traces మీ server కు బదులుగా Langfuse Cloud కు చేరుతున్నట్లయితే, కారణం base URL unset గా ఉండటమే. ఎందుకంటే 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 ను capture చేస్తుంది, అలాగే ఇప్పటికే active గా ఉన్న observation కింద దాన్ని nest చేస్తుంది. AnthropicInstrumentor అనేది Anthropic client కోసం OpenTelemetry instrumentation. ఇది ప్రతి messages.create call ను model name, token usage మరియు latency కలిగిన generation గా మారుస్తుంది. Call site వద్ద ఎలాంటి మార్పు అవసరం లేదు.

ఈ checking ను రెండు calls మీ తరఫున చేస్తాయి. తప్పు keys లేదా తప్పు base URL ఉన్నప్పుడు langfuse.auth_check() False ను return చేస్తుంది. Dashboard ఎందుకు ఖాళీగా ఉందో పరిశీలించడంకన్నా ఇది వేగవంతమైన పద్ధతి. langfuse.flush() queued spans పంపబడే వరకు వేచి ఉంటుంది. తక్కువ వ్యవధి మాత్రమే నడిచే processes కు ఇది అవసరం. SDK background లో batches ను పంపుతుంది; వెంటనే exit అయ్యే script తన unsent batch ను పంపకుండానే ముగుస్తుంది.

ClickHouse పరిమాణం ఎందుకు నిరంతరం పెరుగుతుంది?

చాలా మంది self-host చేసే డేటాలో traces అత్యంత వేగంగా పెరుగుతాయి. ప్రతి agent run ప్రతి step కు ఒక row రాస్తుంది. Inputs మరియు outputs పూర్తిగా నిల్వ చేయబడతాయి. అందువల్ల ఎక్కువ prompts కలిగిన, తరచుగా సందేశాలు పంపే agent, అది పర్యవేక్షించే application కంటే రోజుకు చాలా ఎక్కువ bytes సృష్టిస్తుంది. దీనిని అలాగే వదిలేస్తే ClickHouse disk ను నింపుతుంది. Disk పూర్తిగా నిండితే ingestion నెమ్మదించదు; బదులుగా ఆగిపోతుంది.

ఇక్కడ రెండు వేర్వేరు అంశాలు పెరుగుతాయి. వాటికి రెండు వేర్వేరు పరిష్కారాలు అవసరం.

మొదటిది మీ స్వంత trace data. దీనికి పరిష్కారం retention setting. Web interface లో project settings తెరిచి, data retention period ను రోజుల్లో సెట్ చేయండి. Langfuse కనీసం 3 రోజులను అంగీకరిస్తుంది. తరువాత nightly job ఆ వ్యవధి కంటే పాత traces, observations, scores మరియు media assets ను ఎంచుకుని ClickHouse మరియు blob storage రెండింటి నుంచి తొలగిస్తుంది. Bucket పై job కు DeleteObject permission అవసరం. Default compose file లోని MinIO root credentials కు ఈ permission ఇప్పటికే ఉంది. Deletion శాశ్వతం. అందువల్ల దీర్ఘకాల చరిత్ర అవసరమైతే ముందుగా blob storage export ను configure చేయండి. Langfuse స్వంత tables పై TTL clauses ను చేతితో రాయవద్దు. ClickHouse మరియు bucket సమకాలికంగా ఉండేలా retention job పనిచేస్తుంది. Manual TTL ఒక వైపు మాత్రమే తొలగిస్తుంది.

మీరు వాస్తవంగా ఉపయోగించే వ్యవధి ఆధారంగా 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 ను రాస్తుంది. వీటికి default గా 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" తో run చేయండి. System tables జాబితాలో పైభాగంలో ఉంటే config overlay తో వాటిని ఆపివేయండి. ఎందుకంటే ClickHouse ప్రారంభ సమయంలో /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"/>
</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 తో స్థలాన్ని స్పష్టంగా reclaim చేయండి. తొలగించిన ప్రతి table కు ఇదే విధంగా చేయండి. Diagnostics ను ఉంచాలనుకుంటే, remove="1" కు బదులుగా ప్రతి table పై aggressive TTL అమలు చేయడం ప్రత్యామ్నాయం. Langfuse scaling docs లో దీనికి సంబంధించిన వివరాలు ఉన్నాయి.

మరో table గురించి కూడా తెలుసుకోవాలి. blob_storage_file_log మీ bucket కు upload చేసిన event files ను track చేస్తుంది. Bucket పై lifecycle policy కూడా సెట్ చేస్తే, table కు దానికి సరిపోయే TTL ఇవ్వండి. లేకపోతే ఈ రెండూ కాలక్రమంలో వేర్వేరు స్థితులకు చేరతాయి.

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

Data disk పై plain df -h alert ను కూడా ఏర్పాటు చేయండి. Traces సమాన వేగంతో పెరగవు. మీరు కొత్త agent ను deploy చేసిన రోజున అవి వేగంగా పెరగవచ్చు. దాని మొదటి సంకేతం ingestion విఫలమవడం కాకూడదు.

Postgres మరియు ClickHouse బ్యాకప్ తీసుకోవడం

Langfuse బ్యాకప్‌లో మూడు భాగాలు ఉంటాయి. Postgres లో users, organisations, projects మరియు API keys ఉంటాయి. ClickHouse లో traces ఉంటాయి. MinIO లో raw events ఉంటాయి. Postgres ను మాత్రమే restore చేస్తే history లేని working login లభిస్తుంది. ClickHouse ను మాత్రమే restore చేస్తే login చేయగల user ఎవరూ లేకపోవడంతో ఆ historyని చూడలేరు.

Postgres ఒక plain pg_dump. Langfuse backup docs సిఫారసు చేసేది ఇదే.

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

ClickHouse విషయంలో మరింత జాగ్రత్త అవసరం. merges నడుస్తున్న సమయంలో live data directoryని copy చేస్తే అది consistent backup కాదు. ఒకే boxలో సులభమైన విధానం 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లో రాసిన పేరును ఉపయోగించవద్దు. Fileలో langfuse_clickhouse_data అని declare చేస్తుంది. Compose దానికి project nameను prefixగా జతచేస్తుంది. అందువల్ల langfuse అనే directoryలో clone చేస్తే langfuse_langfuse_clickhouse_data ఏర్పడుతుంది. ఇది తప్పితే docker run ఎలాంటి error లేకుండా కొత్త empty volumeను సృష్టిస్తుంది. అప్పుడు మీ archiveలో ఏమీ ఉండదు.

Worker process చేయడానికి ముందు web container ప్రతి incoming eventను bucketలో రాస్తుంది. అందువల్ల కొద్దిసేపు ClickHouseను ఆపితే worker తర్వాత మళ్లీ retry చేస్తుంది. దీన్ని తక్కువ traffic ఉన్న సమయంలో చేయండి. ఆపివేసే సమయాన్ని తక్కువగా ఉంచండి. ఎక్కువ traffic ఉన్న instanceలో ClickHouse యొక్క స్వంత BACKUP DATABASE default TO S3(...) statementను ఉపయోగించవచ్చు. ఇది serverను ఆపకుండా consistent backupను రాస్తుంది. MinIO మూడవ భాగం. mc mirror లేదా off-box bucketకు MinIO replication ఉపయోగిస్తే ఇది కూడా కవర్ అవుతుంది. మీరు ఏ backup తయారు చేసినా దాన్ని server వెలుపల ఉంచండి. ఇందుకోసమే VPSపై encrypted restic backups ఉపయోగిస్తారు.

Redisకు backup అవసరం లేదు. ఇది queue మరియు cacheను ఉంచుతుంది. అందువల్ల Redisను కోల్పోతే ప్రస్తుతం processలో ఉన్న events మాత్రమే కోల్పోతారు. అంతకుముందు ఉన్న data కోల్పోదు.

Consistency caveat వాస్తవమైనది. దీన్ని స్పష్టంగా గుర్తుంచుకోవాలి. Postgres మరియు ClickHouse వేర్వేరు సమయాల్లో dump అవుతాయి. అందువల్ల restore తర్వాత traces లేని project row ఉండవచ్చు. అలాగే ఇక లేని projectకు సంబంధించిన traces ఉండవచ్చు. Langfuse దీన్ని తట్టుకుంటుంది. అయినప్పటికీ రెండు dumpsను దగ్గర సమయాల్లో, తక్కువ traffic ఉన్న సమయంలో తీసుకోండి. Event bucketే నిజమైన safety net. ఎందుకంటే Langfuse ప్రతి incoming eventను process చేయడానికి ముందు అక్కడ persist చేస్తుంది.

కనీసం ఒకసారి scratch stackలో restore చేయండి. అప్పుడు తప్పు volume nameను outage సమయంలో కాకుండా ముందుగానే గుర్తించవచ్చు.

మొదట పరిశీలించాల్సినవి

మొదటి వారంలో ఈ నాలుగు అంశాలను తప్పక పరిశీలించాలి.

• Trace ఒక్కదానికి అయ్యే ఖర్చు. Langfuse model పేరు మరియు token వినియోగం ఆధారంగా ఖర్చును లెక్కిస్తుంది. అందువల్ల traceలను ఖర్చు ఆధారంగా క్రమబద్ధీకరించి, అత్యధిక ఖర్చు ఉన్న traceను ప్రారంభం నుంచి ముగింపు వరకు చదవండి. సాధారణంగా కారణం పెరిగిపోయిన prompt అవుతుంది: మొత్తం documentను contextలో paste చేయడం లేదా ఎవరూ కుదించని conversation history. కారణం కనిపించిన తర్వాత, AI agent మీకు అయ్యే ఖర్చును నియంత్రించడం అంచనాపై కాకుండా engineering పనిగా మారుతుంది.
• Input మరియు output ఆధారంగా విభజించిన token వినియోగం. Input tokens ఎక్కువగా ఉంటాయి మరియు తక్కువ ఖర్చు అవుతాయి. Output tokens తక్కువగా ఉంటాయి మరియు ఎక్కువ ఖర్చు అవుతాయి. Cached input ఇంకా తక్కువ ఖర్చుతో ఉంటుంది. ఇదే లెక్కింపు విధానాన్ని Claude Code token వినియోగం ఎలా లెక్కించబడుతుంది లో వివరించారు. మీరు స్వయంగా రాసే ఏ agentకైనా ఇది వర్తిస్తుంది.
• Latency percentiles. Median సమస్యను దాచిపెడుతుంది. Timeouts సాధారణంగా p95 మరియు p99 వద్ద కనిపిస్తాయి. Agent loopలో p95 వద్ద నెమ్మదిగా జరిగే tool call, iterations సంఖ్యకు అనుగుణంగా మొత్తం ఆలస్యాన్ని పెంచుతుంది.
• విఫలమైన tool calls. Observationsను level ERROR ఆధారంగా filter చేయండి. 5% సందర్భాల్లో విఫలమయ్యే tool aggregate success rateలో కనిపించకపోవచ్చు. కానీ tracesలో అది స్పష్టంగా కనిపిస్తుంది. అక్కడ model మళ్లీ ప్రయత్నించి, ఆ తరువాత ఆ toolను పక్కదారి ద్వారా ఉపయోగించడానికి 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 guide సిఫారసు చేసేది ఇదే. దీనికి అదనంగా సుమారు 100 GiB storage అవసరం. ప్రచురించిన component minimums ప్రకారం ClickHouse కు 8 GiB, web మరియు worker containers కు ఒక్కొక్కటికి 4 GiB అవసరం. వీటికి అదనంగా Postgres, Redis మరియు MinIO కు కూడా memory అవసరం. 8 GiB ఒక developer instance ను నడపగలదు. 2 GiB సరిపోదు: background merges సమయంలో kernel ClickHouse ను terminate చేస్తుంది, మరియు dmesg Out of memory: Killed process ను చూపిస్తుంది.

data retention సెట్ చేసిన తర్వాత కూడా నా ClickHouse disk ఎందుకు నిండిపోతోంది?

Retention setting Langfuse స్వంత data కు మాత్రమే వర్తిస్తుంది. ClickHouse diagnostic tables trace_log, text_log, opentelemetry_span_log, metric_log మరియు asynchronous_metric_log కు data ను ప్రత్యేకంగా రాస్తుంది. వీటికి TTL ముందుగా సెట్ చేయబడదు. ఏ table పెద్దదో చూడటానికి table ప్రకారం సమూహీకరించి system.parts ను query చేయండి. తరువాత ఉపయోగించని tables ను /etc/clickhouse-server/config.d/ కింద ఉన్న file లోని remove="1" entry తో disable చేయండి. ClickHouse ను restart చేసి, ఇప్పటికే ఉపయోగించిన space ను తిరిగి పొందడానికి ఉన్న tables ను drop చేయండి.

Langfuse లో కనిష్ఠ data retention period ఎంత?

3 రోజులు. Retention ను project settings లో ప్రతి project కు విడిగా సెట్ చేయవచ్చు లేదా projects API ద్వారా సెట్ చేయవచ్చు. Nightly job, ఈ వ్యవధి కంటే పాత traces, observations, scores మరియు media assets ను ClickHouse మరియు blob storage రెండింటి నుంచీ తొలగిస్తుంది. తొలగించిన data ను తిరిగి పొందలేరు. ఈ వ్యవధికి మించిన history అవసరమైతే ముందుగా blob storage export ను configure చేయండి.

Postgres మరియు ClickHouse రెండింటినీ backup చేయాలా?

అవును, ఎందుకంటే అవి వేర్వేరు data ను కలిగి ఉంటాయి. Postgres లో users, organisations, projects మరియు API keys ఉంటాయి. ClickHouse లో అసలు trace data ఉంటుంది. Postgres-only restore చేస్తే login చేయగలిగే instance లభిస్తుంది, కానీ అందులో data ఉండదు. MinIO bucket ను కూడా backup చేయండి. Langfuse స్వీకరించిన raw events అందులో ఉంటాయి. ఈ stack లో source of truth కు అత్యంత సమీపమైనది అదే.

ఉన్న OpenTelemetry setup ను self-hosted Langfuse కు పంపవచ్చా?

అవును. Langfuse v4 మరియు దాని v4 SDKs OpenTelemetry పై నిర్మించబడ్డాయి. Anthropic మరియు OpenAI OTel instrumentations నేరుగా దానికి export చేయగలవు. Python లో pip install langfuse opentelemetry-instrumentation-anthropic ను run చేయండి. Startup సమయంలో ఒకసారి AnthropicInstrumentor().instrument() ను call చేయండి. LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY మరియు LANGFUSE_BASE_URL ను మీ స్వంత host కు సెట్ చేయండి. Missing dashboard కోసం పరిశీలించే ముందు langfuse.auth_check() తో నిర్ధారించండి.